AgenticNetOS 2.41.0

Everything here comes from one field report: a Claude Code client on a Windows Desktop Lite install built a scheduled persona net whose reasoning step spawns headless Claude Code, and documented every place our own teaching misled it. Two patterns we shipped as canonical turned out to be wrong.

Added

• docs/real-agents — building real agents on nets (agentic-net-mcp). The new knowledge doc answers what a client needs before it starts rather than after it has guessed: a persona is a net (charter place, task inbox, reasoning lane, output place), and its reasoning step has four possible executors — a server llm/agent lane, a command lane spawning a headless CLI agent, an external fire, or host_transition — with a table of which are unattended and what each requires. The consequence worth knowing up front: when master has no LLM provider, a command lane spawning headless Claude Code is the only fully unattended reasoning path, so a provider-less install can still fetch, compute and reason with nobody connected. Also covers workingDir as the context switch (a spawned agent auto-loads that project's memory — capability and hazard), multi-agent systems as nets sharing places, and the cost/secret boundaries. Reachable as agenticnets://docs/real-agents and through search_knowledge.

Fixed

• The documented way to spawn a CLI agent was the quoting trap (agentic-net-mcp — server instructions, docs/commands, docs/recipes). We taught claude -p '<prompt>' … < /dev/null. Through the chain of command token → executor process spawn → shell, those nested quotes can be consumed: the CLI then starts with no prompt at all, waits ~3s for stdin, and answers at its own discretion — with the workingDir project's memory loaded, so the output looks plausible rather than obviously broken. Every occurrence now teaches printf '%s' '<prompt>' | claude -p --model sonnet …, which removes nested quoting entirely and supplies stdin, so the redirect that the old form needed is no longer a separate thing to remember.
• Windows command-lane setup was documented wrongly (agentic-net-mcp — docs/commands, docs/real-agents). "Windows needs Git Bash on PATH" does not describe what happens: the executor spawns /bin/sh, which Windows resolves against the current drive root, i.e. C:\bin\sh.exe. The docs now give the actual one-time bridge (copy Git's usr\bin\sh.exe and msys-2.0.dll into C:\bin\, create an empty C:\tmp\), name the trap that Git's other sh.exe is a 47 KB launcher which cannot work relocated, and state the shell's real constraints — no MSYS mount table (/c/... paths are meaningless), no GNU userland, so use Windows paths with forward slashes and an absolute args.workingDir.
• docs/llm implied a session-bound feature was the unattended answer (agentic-net-mcp). Its provider-disabled section offered host_transition for "unattended AI lanes", but hosted lanes run only while the MCP session is connected. It now points at the command-lane path for genuinely unattended reasoning and keeps host_transition in its true role.
• The server instructions omitted external-fire from the topic list (agentic-net-mcp). The doc shipped and was searchable, but the one place that enumerates the pack for a new client never named it — a gap in exactly the area a provider-less install depends on.

Changed

• Knowledge-pack budget and its guard (agentic-net-mcp). The pack cap moves 72 KB → 78 KB for the new doc; the 8 KB per-doc discipline is unchanged. The instructions size test now pins the multi-model build as well as the single-model one — the multi-model preamble is longer, and that build was already 23 bytes over the cap with every test green.

Windows update repair. If you are on 2.40.0 or earlier, this release's update still runs through the old updater — if it stops with "cannot close AgenticNetOS" or "error writing to file", end the leftover AgenticNetOS/node.exe/java.exe processes (or reboot) and run the installer from the releases page. Your data in ~/.agenticos is never touched by the installer, including by a failed one. From this version on, the updater handles that case itself.

Added

• Windows upgrade is tested in CI (.github/workflows/desktop-windows.yml). Nothing in any suite ran msiexec, so the upgrade path could only be tested by shipping it. A new job installs the previous published release, runs it (Studio answering on 4200 proves the jlink runtime, service jars and static GUI all reached the bundle), seeds a marker under ~/.agenticos, upgrades in place, and asserts exactly one registered install at the new version, the marker intact, and the upgraded app still serving.

Fixed

• Updates identify our processes positively before killing anything (agentic-net-desktop — new PidRegistry, InstallProcesses). Two independent identifications, either sufficient, nothing less accepted. (1) Every spawned child is recorded at ~/.agenticos/desktop/run/<service>/pid as <pid> <startEpochMillis>; an entry counts only when the live process's start instant matches the record — pids are numbers the OS reuses, and a crashed launcher's orphans still carry their records. (2) A scan for processes whose executable resolves under the install root (symlinks resolved — macOS /var is one) and carries a shipped image name (java/node/AgenticNetOS), the fallback for lost registrations. Identified processes are killed and awaited until provably dead; a process under the root that is not positively ours is never killed — it surfaces as a survivor and the update aborts naming it, rather than letting msiexec fail into a rollback. Descendants are deliberately not expanded: tree membership is not identity. On macOS the sweep runs before the update applier is spawned, since the applier is itself a java process from the install runtime and must not be swept.
• Windows tray update could destroy the installation (agentic-net-desktop — SelfUpdater, Supervisor, TrayUi). The updater started msiexec FIRST and then began the multi-second service shutdown, so the installer's files-in-use scan always caught the app running. Windows Restart Manager cannot close the background node/java children (no windows, not registered), and force-closing the tray process skipped the JVM shutdown hook and orphaned them — an orphaned MCP node.exe then held handles under app\mcp\, the install failed with "error writing to file", and cancelling rolled back a half-done upgrade whose old version was already removed, leaving no installation at all. The update now stops every child and waits for the kills to land (including after destroyForcibly, since handles release only at actual process death), then launches msiexec through a detached script with a ~2s delay so the launcher itself has exited before the scan runs. User data under ~/.agenticos/ was never at risk — the msi only manages the app directory. Recovery on affected versions: end the leftover AgenticNetOS/node.exe/java.exe processes (or reboot) and re-run the installer.

---

AgenticNetOS Desktop Lite

The fast local creator/operator profile: node, deterministic master, gateway,
executor, encrypted local credential vault (no OpenBao), MCP endpoint, and
Studio — supervised by a tray app on bundled Java/Node runtimes. No Docker,
host Java/Node installation, API key, or server-side LLM is required. Connect
an MCP client and let its model build, schedule, inspect, and execute nets.
This loopback-only profile is not the recommended production deployment.

macOS: open the .dmg, accept the license, drag AgenticNetOS to Applications.
First launch of this unsigned build: right-click the app and choose "Open", or allow
it under System Settings → Privacy & Security → "Open Anyway". Verify the download
against SHA256SUMS.txt first.

Linux (Debian/Ubuntu): sudo apt install ./AgenticNetOS-<version>-linux-<arch>.deb,
then run /opt/agenticnetos/bin/AgenticNetOS. An
.rpm is provided for Fedora/RHEL. On servers without a desktop the app runs headless;
the tray is optional.

Windows: not yet published — planned.

Build it yourself: agentic-net-desktop/scripts/build.sh (or build-windows.ps1)
in the repository bundles an installer for your machine from this release's
standalone binaries (agentic-net-node-*.jar, agentic-net-master-*.jar,
agentic-net-gui-*.zip below — EULA applies), no Docker needed.

Connect an MCP client: the tray copies a ready Codex config.toml block,
Claude Code command, or generic MCP URL + bearer token. Studio: tray menu →
"Open Studio" (login secret is one click away under "Copy Studio Admin Secret").
Server-run AI lanes can be enabled later, but fresh installs use
llm.provider=disabled, so new AI lanes default to MCP external fires and need
no server model.

Data lives in ~/.agenticos/ and survives updates. The bundled node, master and
gui binaries are covered by the EULA shown at install (also in the app dir);
everything else is BSL 1.1.