@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/daemon.js

@@ -1,7 +1,13 @@
+import { claimDaemonIdentity } from './control/daemonIdentity.js';
+import { openRuntimeHost } from './control/runtimeHost.js';
+import { stoppedRuntime } from './control/protocol.js';
+import { normalizeWorkstationServer } from './control/serverIdentity.js';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AGENT_WIRE_MIN_VERSION } from './protocol/agent.js';
-import { clientDir, loadClientConfig, readKeys, updateServiceContext } from './config.js';
+import { clientDir, loadClientConfig, updateServiceContext } from './config.js';
 import { AgentSessionManager } from './agentSessions.js';
 import { AcpAgents } from './acp/acpAgents.js';
 import { ConnectionSupervisor } from './connection/supervisor.js';
@@ -9,10 +15,26 @@ import { ManagementChannel } from './channels/management.js';
 import { ComputerChannel } from './channels/computer.js';
 import { AgentChannel, dispatchAgentFrame as dispatchAgentChannelFrame } from './channels/agent.js';
 import { TaskRegistry } from './update/taskRegistry.js';
+import { RdUpkeep } from './rd/upkeep.js';
 import { createUpdateCoordinator } from './update/runUpdate.js';
 import { resolveCliPath } from './daemonctl.js';
 import { SystemMetricsSampler } from './systemMetrics.js';
-import { preflightOptionalPty } from './update/ptyPreflight.js';
+import { cachedPtyStatus, preflightOptionalPty } from './update/ptyPreflight.js';
+import { FilesHostClient } from './files/client.js';
+import { ToolsClient } from './tools/client.js';
+import { WorkstationTools } from './tools/router.js';
+import { aggregateToolsInfo, computeFilesInfo } from './tools/info.js';
+import { defaultDistDir, KeeperLauncher } from './keepers/kit/launcher.js';
+import { readKeeperManifest } from './keepers/kit/bundle.js';
+import { KEEPER_POLICY_TICK_MS, KeeperPolicy, oneShotDrain, oneShotProbe } from './keepers/policy.js';
+import { TerminalGenerations } from './keepers/terminal/generations.js';
+import { AcpKeeperClient } from './keepers/acp/client.js';
+import { KeeperTransport } from './acp/processor/transport/keeper.js';
+import { keeperGenerations } from './acp/processor/transport/generations.js';
+import { ExecPolicy } from './exec/policy.js';
+import { LegacyToolsKeeper } from './keepers/legacy.js';
+import { TerminalRouter, terminalEnv, terminalShell } from './tools/terminalRouter.js';
+import { ToolchainProbe } from './toolchain.js';
 /**
  * The path `runDaemon` hands `createUpdateCoordinator` as `cliPath`, used to re-provision the OS
  * service after an update (see runUpdate.ts's `provisionService`).
@@ -106,6 +128,45 @@ export const IDLE_SWEEP_INTERVAL_MS = 10 * 60 * 1000;
  * nobody awaits a timer callback, and an escaping rejection is an unhandled rejection, which Node
  * answers by exiting.
  */
+/**
+ * The daemon's start-time adapter build upkeep: legacy migration, then the certified reconcile; calls
+ * `onRosterChanged` once if either changed any agent's current build. Never rejects.
+ */
+export async function maintainAdapterBuilds(acp, onRosterChanged) {
+    try {
+        const migrated = await acp.migrateLegacyAdapters();
+        const moves = await acp.reconcileCertifiedBuilds();
+        if (migrated.length || moves.length)
+            await onRosterChanged();
+    }
+    catch (error) {
+        console.warn(`[acp-builds] adapter build upkeep failed: ${String(error)}`);
+    }
+}
+/** How often held sessions are looked at for a pending switch (spec §6.3 step 7) or a lost adapter to reopen (Task 24). */
+export const SWITCH_POLL_INTERVAL_MS = 5_000;
+/** How often unused adapter builds are collected (spec §6.3 "GC"; the first run is one grace period after start). */
+export const BUILD_GC_INTERVAL_MS = 10 * 60_000;
+/**
+ * Task 24: the switch scheduler (every {@link SWITCH_POLL_INTERVAL_MS}: `agent_reopen_request` for idle sessions with a pending
+ * switch, and for keeper-hosted sessions whose adapter keeper-acp lost) and build GC (every {@link BUILD_GC_INTERVAL_MS}). Both
+ * timers are `unref`'d, and neither callback can reject. Returns the stop.
+ */
+export function startSwitchUpkeep(agents, acp, pollMs = SWITCH_POLL_INTERVAL_MS, gcMs = BUILD_GC_INTERVAL_MS) {
+    let polling = false;
+    const poll = setInterval(() => {
+        if (polling)
+            return;
+        polling = true;
+        void Promise.resolve().then(() => agents.pollSwitches()).catch((err) => {
+            console.error(`[agent] switch poll failed: ${err instanceof Error ? err.message : String(err)}`);
+        }).finally(() => { polling = false; });
+    }, pollMs);
+    poll.unref();
+    const gc = setInterval(() => { void Promise.resolve().then(() => acp.collectBuilds()).catch(() => undefined); }, gcMs);
+    gc.unref();
+    return () => { clearInterval(poll); clearInterval(gc); };
+}
 export function startIdleSweep(agents, ttlMs = IDLE_SESSION_TTL_MS, intervalMs = IDLE_SWEEP_INTERVAL_MS) {
     const timer = setInterval(() => {
         void (async () => {
@@ -157,7 +218,99 @@ export function resolveServiceLifecycle(options) {
 export async function buildManagementSnapshot(supervisor, tasks, updates) {
     return { channels: supervisor.channelSnapshot(), ...tasks.snapshot(), update: await updates.snapshotAsync() };
 }
+/**
+ * The files host's configured roots: every workspace cwd, absolute (a relative one is taken relative to the home
+ * directory; FileTools refuses relative roots because they would resolve against whatever directory a pinned section
+ * holds).
+ */
+export function workspaceRoots(cfg, home = os.homedir()) {
+    return [path.join(home, '.axom', 'playground'), ...(cfg.workspaces ?? []).filter(workspace => typeof workspace?.cwd === 'string' && workspace.cwd.length > 0).map(workspace => path.resolve(home, workspace.cwd))];
+}
+/** The roots that exist as directories right now. A missing workspace must not keep the host (all of Files) down. */
+export async function existingDirectories(roots) {
+    const existing = [];
+    for (const root of roots) {
+        try {
+            if ((await fs.stat(root)).isDirectory())
+                existing.push(root);
+        }
+        catch { /* left out until it exists */ }
+    }
+    return existing;
+}
+/** How often the daemon re-reads the workspaces config (and root existence) to restart the files host on a change. */
+export const FILES_ROOTS_POLL_MS = 10_000;
+/** How often the legacy tools keeper is re-probed and checked for retirement (keepers/legacy.ts). */
+export const LEGACY_TICK_MS = 30_000;
+/**
+ * Builds the object `ManagementChannelOptions.keepers` reports (Task 26): the policy's statuses, never a rejection (a failure is
+ * `null`, which the channel also guarantees). `countedExecs` (final review minor 7): keeper-terminal execs `activeShellTasks` also
+ * counts right now — reported as the current terminal keeper's `execCounted` metric (sampled with this heartbeat), so the
+ * Workstations page counts `activeShellTasks + execRunning − execCounted` commands, each once.
+ */
+export async function buildKeeperStatuses(policy, countedExecs = () => 0) {
+    let statuses;
+    try {
+        statuses = await policy.statuses();
+    }
+    catch {
+        return null;
+    }
+    const terminals = statuses.filter((status) => status.kind === 'terminal' && !status.legacy);
+    const target = terminals.find((status) => status.replacement === 'none') ?? terminals[0];
+    if (!target)
+        return statuses;
+    let counted = 0;
+    try {
+        const value = countedExecs();
+        counted = Number.isSafeInteger(value) && value > 0 ? value : 0;
+    }
+    catch {
+        counted = 0;
+    }
+    // A copy: the policy reuses its sample for a while.
+    return statuses.map((status) => (status === target ? { ...status, metrics: { ...status.metrics, execCounted: counted } } : status));
+}
+/**
+ * Runs `poll` every `intervalMs`, skipping a tick while the previous run is still in flight (on a hung mount a stat
+ * may never return; overlapping runs would pile up behind it). The timer is unref'd. Returns the stop function.
+ */
+export function startExclusivePoll(poll, intervalMs) {
+    let running = false;
+    const timer = setInterval(() => {
+        if (running)
+            return;
+        running = true;
+        void poll().catch(() => { }).finally(() => { running = false; });
+    }, intervalMs);
+    timer.unref();
+    return () => clearInterval(timer);
+}
 export async function runDaemon(options = {}) {
+    const directory = clientDir();
+    const shutdown = new AbortController();
+    const state = { snapshot: async () => ({ ...stoppedRuntime(), connection: 'connecting' }) };
+    const { host, identity } = await claimDaemonIdentity(directory, async (identity) => {
+        const config = identity.config;
+        const host = await openRuntimeHost({ directory, binding: { server: normalizeWorkstationServer(config.server), workstationId: config.workstationId, ...(config.ownerUserId ? { ownerUserId: config.ownerUserId } : {}) },
+            mode: options.supervisedByServiceManager ? 'launchd' : 'foreground', snapshot: () => state.snapshot(), shutdown: async () => { shutdown.abort(); },
+            update: async (release, operationId) => {
+                if (!state.update)
+                    return { phase: 'BUSY', commandId: operationId };
+                void state.update.handle({ commandId: operationId, release, force: false }).catch(error => console.error('[update] local request failed', error));
+                return { phase: 'REQUESTED', commandId: operationId, version: release.version };
+            },
+        });
+        return { host, identity };
+    });
+    try {
+        await runOwnedDaemon(options, shutdown, state, identity);
+    }
+    finally {
+        await host.close();
+    }
+}
+async function runOwnedDaemon(options, shutdown, localState, identity) {
     // Last line of defence for the whole process. Node's default for an unhandled rejection is to
     // *exit*, and this daemon is the only thing keeping every session on this workstation alive —
     // dying because one async callback rejected is strictly worse than logging and carrying on.
@@ -167,10 +320,27 @@ export async function runDaemon(options = {}) {
         console.error(`[daemon] unhandled rejection (ignored, daemon stays up): ${detail}`);
     });
     const dir = clientDir();
-    const cfg = await loadClientConfig(dir);
-    const { clientKey, serverPub } = await readKeys(dir);
+    const cfg = identity.config;
+    let activateRdAfterReadiness;
+    if (process.platform === 'linux') {
+        const { synchronizeRd } = await import('./rd/update.js');
+        activateRdAfterReadiness = await synchronizeRd(dir, cfg.server);
+    }
+    const { NativeProvider } = await import('./desktopControl/nativeProvider.js');
+    const { DeviceSockets } = await import('./desktopControl/deviceSockets.js');
+    const { DesktopSessionSupervisor } = await import('./desktopControl/supervisor.js');
+    const { MacProvider } = await import('./desktopControl/macProvider.js');
+    const { LinuxDesktopProvider } = await import('./rd/provider.js');
+    const legacyDesktop = cfg.desktopProvider ? new NativeProvider({ ...cfg.desktopProvider, validateSession: async () => {
+            const { readRdState } = await import('./rd/state.js');
+            if (await readRdState(dir))
+                throw new Error('Remote desktop configuration changed');
+        } }) : undefined;
+    const desktopProvider = options.desktopProvider ?? (process.platform === 'linux' ? new LinuxDesktopProvider(dir, cfg.server, legacyDesktop) :
+        legacyDesktop ?? (process.platform === 'darwin' && process.arch === 'arm64' ? new MacProvider(dir, cfg) : undefined));
+    const { clientKey, serverPub } = identity;
     // Repair the first fixed release even when it was installed by an older ignore-scripts updater,
-    // before a newly started terminal keeper snapshots native dependency availability.
+    // before a newly started keeper-terminal snapshots native dependency availability.
     await preflightOptionalPty(updateServiceContext(dir));
     const tasks = new TaskRegistry();
     // Attaches both the server-driven update path (onUpdate below) and axom update's manual path to
@@ -194,35 +364,223 @@ export async function runDaemon(options = {}) {
         // invoked*, not on what the host merely supports.
         serviceLifecycle: resolveServiceLifecycle(options),
     });
+    localState.update = updates;
     // One ACP client for every external agent; the roster it reports is the ACP agent registry, keyed
     // by registry agent id (ruling R2) — the same key `agent_open.bridge` now carries.
-    const acp = new AcpAgents({ cacheDir: dir });
-    const agents = new AgentSessionManager(acp, null, path.join(dir, 'agents'), undefined, tasks);
+    // Live sessions run in keeper-acp (spec §5.3) — the adapters outlive the daemon there — or, when it cannot be reached, in the
+    // daemon itself through the local fallback (§5.7). Short-lived connections (list, delete, verify, login) stay direct children.
+    const acpLauncher = new KeeperLauncher({ configDir: dir, workstationId: cfg.workstationId, server: cfg.server });
+    const acpTransport = new KeeperTransport(new AcpKeeperClient({ launcher: acpLauncher }));
+    // Sessions keeper-acp still runs from a previous daemon (a restart, an upgrade, a crash) are adopted where they are — across
+    // keeper-acp generations (spec §5.5, §6.3) — before the agent channel's reconnect offer is answered.
+    const acpGenerations = keeperGenerations({ launcher: acpLauncher, current: acpTransport });
+    const acp = new AcpAgents({ cacheDir: dir, serverOrigin: cfg.server, transports: { keeper: acpTransport }, keeperGenerations: acpGenerations });
+    const agents = new AgentSessionManager(acp, null, path.join(dir, 'agents'), tasks);
+    void agents.adoptSessions();
     let bridges = await acp.roster();
+    // A scan's roster (and a pushed one) also carries the adapter builds live sessions run and how many could move now (spec §6.4,
+    // Task 25): keeper-acp's process labels joined with this daemon's sessions. The hello's roster above does not — it is not a scan.
+    const scanRoster = () => acp.roster({ sessions: (session) => agents.rosterSessionState(session) });
     let supervisor;
     // Plaintext WebSockets are only for an explicitly opted-in local development fixture. Production
     // ticket handshakes must be WSS because the ticket is the data-channel key derivation material.
     const allowInsecureWs = process.env.AXOM_WORKSTATION_ALLOW_INSECURE_WS === '1';
-    const computer = new ComputerChannel({ server: cfg.server, allowInsecureWs, taskRegistry: tasks,
-        toolsConfig: { configDir: dir, workstationId: cfg.workstationId, server: cfg.server, roots: (cfg.workspaces ?? []).map(workspace => workspace.cwd), browserBinding: cfg.browserBinding },
+    // Files: one daemon-owned host process (files/host.ts) serves file_*_request frames and files.* tool requests.
+    const home = os.homedir();
+    const playgroundCwd = path.join(home, '.axom', 'playground');
+    await fs.mkdir(playgroundCwd, { recursive: true });
+    let roots = workspaceRoots(cfg, home);
+    let hostRoots = [];
+    const filesHost = new FilesHostClient({
+        configDir: dir,
+        options: async () => { hostRoots = await existingDirectories(roots); return { home, roots: hostRoots }; },
+        onActivityChanged: () => tasks.externalActivityChanged(),
+        log: (line) => console.error(`${new Date().toISOString()} ${line}`),
+    });
+    tasks.externalActivity = () => filesHost.activity();
+    filesHost.start();
+    const stopRootsPoll = startExclusivePoll(async () => {
+        try {
+            roots = workspaceRoots(await loadClientConfig(dir), home);
+            const current = await existingDirectories(roots);
+            if (JSON.stringify(current) !== JSON.stringify(hostRoots))
+                filesHost.reconfigure();
+        }
+        catch { /* an unreadable config keeps the current host */ }
+    }, FILES_ROOTS_POLL_MS);
+    // tools.info is aggregated here and starts no keeper: its terminal fields come from keeper-terminal's hello when that keeper
+    // already runs, else from the cached node-pty check. terminal.* go through the TerminalRouter (keeper-terminal, or a legacy
+    // tools keeper an older CLI left running with live PTYs: served until they end, then stopped). browser.* keep the
+    // browser-kind ToolsClient path. Nothing here constructs a terminal-kind ToolsClient: its request() would start the legacy keeper.
+    const toolsConfig = { configDir: dir, workstationId: cfg.workstationId, server: cfg.server, roots, browserBinding: cfg.browserBinding };
+    const browserTools = new ToolsClient(toolsConfig, 'browser');
+    const ptyStatus = cachedPtyStatus();
+    // keeper-terminal generations (Task 26): new work goes to the serving generation; PTYs and execs an older generation still runs
+    // after an upgrade are routed to it by owner until the replacement policy retires it.
+    const terminalLauncher = new KeeperLauncher({ configDir: dir, workstationId: cfg.workstationId, server: cfg.server });
+    const terminalKeepers = new TerminalGenerations({ launcher: terminalLauncher });
+    const legacyKeeper = new LegacyToolsKeeper({
+        tools: toolsConfig,
+        recoverUploads: (uploads) => filesHost.recoverUploads(uploads),
+        log: (line) => console.error(`${new Date().toISOString()} ${line}`),
+    });
+    void legacyKeeper.detect();
+    const stopLegacyPoll = startExclusivePoll(() => legacyKeeper.tick(), LEGACY_TICK_MS);
+    const terminals = new TerminalRouter({
+        kits: terminalKeepers,
+        legacy: legacyKeeper,
+        launch: async (cwd) => ({ cwd: await filesHost.terminalCwd(cwd), shell: terminalShell(), env: terminalEnv() }),
+    });
+    const workstationTools = new WorkstationTools({
+        files: filesHost,
+        terminal: (method, params) => terminals.request(method, params),
+        browser: (method, params) => browserTools.request(method, params),
+        info: () => aggregateToolsInfo({
+            files: async () => filesHost.info() ?? computeFilesInfo(home, roots),
+            terminal: () => terminalKeepers.terminalStatus(ptyStatus),
+            browser: (method, params) => browserTools.request(method, params),
+        }),
+    });
+    // exec_request: keeper-terminal (durable) when available, else in this process; argv/env/deadline/shaping decided here.
+    // Execs a previous daemon left in keeper-terminal are recovered first: wire ≤ 4 ones are stopped (their channel is gone), wire v5
+    // ones are followed for the server to re-attach (exec_attach on the next computer channel).
+    // Keeper replacement (spec §8.3, Task 26): what the heartbeat reports of each keeper generation, and what happens to an older one.
+    const drainKeeper = oneShotDrain((kind, gen) => (kind === 'acp' ? acpLauncher : terminalLauncher).pathsFor(kind, gen));
+    const keeperPolicy = new KeeperPolicy({
+        dir: path.join(dir, 'keepers'),
+        probe: oneShotProbe((kind, gen) => (kind === 'acp' ? acpLauncher : terminalLauncher).pathsFor(kind, gen)),
+        terminal: {
+            currentGen: () => terminalKeepers.currentGen(),
+            live: async () => (await terminalKeepers.running()).map((generation) => generation.gen),
+            manifest: () => terminalKeepers.manifest(),
+            stop: async (gen, mode) => {
+                const result = await terminalLauncher.stop('terminal', gen, mode);
+                if (result.stopped)
+                    terminalKeepers.forget(gen);
+                return result;
+            },
+            reachable: async (gen) => (await terminalKeepers.client(gen)).runningHello(),
+            drain: (gen) => drainKeeper('terminal', gen),
+        },
+        legacy: legacyKeeper,
+        acp: {
+            currentGen: () => acpGenerations.current(),
+            live: () => acpGenerations.live(),
+            manifest: () => readKeeperManifest(path.join(defaultDistDir(), 'acp')),
+            stop: (gen, mode) => acpLauncher.stop('acp', gen, mode),
+            moveOff: (gens) => agents.moveOffOlderKeeperGenerations(undefined, gens),
+            cancelMoves: async (refs) => { for (const sessionRef of refs)
+                await agents.cancelSwitch({ sessionRef }); },
+            retireIdle: () => acp.retireIdleGenerations(),
+            session: (ref) => agents.sessionView(ref),
+        },
+        agentName: (agentId) => bridges.find((bridge) => bridge.type === agentId)?.displayName || agentId,
+        legacyShell: () => terminalShell(),
+        log: (line) => console.error(`${new Date().toISOString()} ${line}`),
+    });
+    terminalKeepers.picker = (current, older) => keeperPolicy.terminalServing(current, older);
+    const stopKeeperPolicy = startExclusivePoll(() => keeperPolicy.tick(), KEEPER_POLICY_TICK_MS);
+    // Spec §3.1: keeper sockets that fell back to /tmp (a long configDir path) are touched so a /tmp cleaner never reaps them.
+    const stopSocketTouch = startExclusivePoll(async () => {
+        await acpLauncher.touchSockets('acp');
+        await terminalLauncher.touchSockets('terminal');
+    }, KEEPER_POLICY_TICK_MS);
+    void keeperPolicy.tick();
+    const execPolicy = new ExecPolicy({ generations: terminalKeepers, log: (line) => console.error(`${new Date().toISOString()} ${line}`) });
+    void execPolicy.recover();
+    const computer = new ComputerChannel({ server: cfg.server, allowInsecureWs, taskRegistry: tasks, browserBinding: cfg.browserBinding,
+        runExec: (request, onOutput, signal, hooks) => execPolicy.run(request, onOutput, signal, hooks),
+        execs: execPolicy, log: (line) => console.error(`${new Date().toISOString()} ${line}`),
+        tools: (method, params) => workstationTools.request(method, params),
+        runFrame: (request, signal) => workstationTools.runFrame(request, signal),
     });
     const metrics = new SystemMetricsSampler(cfg.workspaces ?? []);
     await metrics.start();
+    const toolchain = new ToolchainProbe(() => terminalShell(), () => terminalEnv());
+    toolchain.start();
+    const desktopSupervisor = desktopProvider && !options.onDesktopCommand ? new DesktopSessionSupervisor({ provider: desktopProvider,
+        sockets: new DeviceSockets(cfg.server, process.env.AXOM_DESKTOP_ALLOW_PRIVATE_WS === '1'),
+        report: (generation, frame) => management.sendDesktopState(generation, frame),
+        refreshCapabilities: generation => management.refreshDesktopCapabilities(generation), }) : undefined;
+    let rdGeneration;
+    const rdUpkeep = process.platform === 'linux' && desktopSupervisor ? new RdUpkeep({
+        synchronize: async () => {
+            if (!rdGeneration || shutdown.signal.aborted)
+                return;
+            const { synchronizeRd } = await import('./rd/update.js');
+            return synchronizeRd(dir, cfg.server, { deferActivation: true });
+        },
+        whenIdle: operation => desktopSupervisor.whenIdle(async () => {
+            if (!tasks.canUpdate() || !rdGeneration || shutdown.signal.aborted)
+                return;
+            await operation();
+        }),
+        refresh: () => { if (rdGeneration)
+            management.refreshDesktopCapabilities(rdGeneration); },
+        log: message => console.error(`${new Date().toISOString()} ${message}`),
+    }) : undefined;
+    const stopRdUpkeep = rdUpkeep ? startExclusivePoll(() => rdUpkeep.tick(), 60_000) : () => { };
     const management = new ManagementChannel({
         server: cfg.server, workstationId: cfg.workstationId, workstation: cfg.workstationId, clientKey, serverPub,
         bridges: () => bridges,
         workspaces: cfg.workspaces,
+        playgroundCwd,
         metrics: () => metrics.snapshot(),
+        toolchain: () => toolchain.current(),
         allowInsecureWs,
-        onReady: (ready) => updates.managementReady(ready.release, ready.generation),
+        onReady: async (ready) => {
+            await updates.managementReady(ready.release, ready.generation);
+            await activateRdAfterReadiness?.();
+            if (ready.selectedWire >= 9)
+                desktopSupervisor?.managementReady(ready.generation);
+            rdGeneration = ready.selectedWire >= 9 ? ready.generation : undefined;
+            void rdUpkeep?.tick();
+        },
+        desktopProvider,
+        onDesktopCommand: options.onDesktopCommand ?? ((frame, generation) => desktopSupervisor?.dispatch(frame, generation) ?? Promise.resolve()),
+        onClosed: generation => {
+            if (rdGeneration === generation)
+                rdGeneration = undefined;
+            desktopSupervisor?.managementClosed(generation);
+            options.onDesktopManagementClosed?.(generation);
+        },
         onUpdate: (command) => updates.handle(command),
         onExternalAgentsScan: async () => {
-            bridges = await acp.roster();
+            bridges = await scanRoster();
             return bridges;
         },
         snapshot: () => buildManagementSnapshot(supervisor, tasks, updates),
+        keepers: () => buildKeeperStatuses(keeperPolicy, () => tasks.countedKeeperExecs),
+        onKeeperControl: (frame) => keeperPolicy.control(frame),
     });
+    options.onDesktopManagement?.(management);
     const agent = new AgentChannel({ server: cfg.server, agents, bridges: () => bridges, allowInsecureWs });
+    // Spec §6.2: first take over what an older CLI left (`_npx` copies, pre-build binary dirs) so agents
+    // that worked keep working; then §6.1: a version this CLI certifies (runtime.json/catalog pin) or a
+    // changed patch set moves an installed agent's current build forward by itself ("Updated by Axom").
+    // In the background: either may copy or download, an open of an agent not done yet waits on that
+    // agent's lock, and running sessions keep the build they were spawned from either way. A changed
+    // roster reaches the server the way a scan's does; offline, the next hello carries it.
+    void maintainAdapterBuilds(acp, async () => {
+        bridges = await scanRoster();
+        management.pushRoster(bridges);
+    });
+    // A quota capability learned mid-flight (this process's first spawn of an agent) changes what the
+    // roster would say; push it the way a build change does. Coalesced: several agents flipping
+    // around one burst of opens share a single scan, and a flip during that scan queues one more.
+    let rosterPushQueued = false;
+    acp.onRosterChanged(() => {
+        if (rosterPushQueued)
+            return;
+        rosterPushQueued = true;
+        void Promise.resolve().then(async () => {
+            rosterPushQueued = false;
+            bridges = await scanRoster();
+            management.pushRoster(bridges);
+        }).catch((error) => {
+            console.warn(`[acp-builds] roster push after capability change failed: ${String(error)}`);
+        });
+    });
     supervisor = new ConnectionSupervisor({
         management, computer, agent,
         // Timestamped here rather than inside the supervisor: the daemon owns this log's shape. The
@@ -231,7 +589,15 @@ export async function runDaemon(options = {}) {
         log: (message) => console.log(`${new Date().toISOString()} ${message}`),
     });
     const stopIdleSweep = startIdleSweep(agents);
-    const shutdown = new AbortController();
+    const stopSwitchUpkeep = startSwitchUpkeep(agents, acp);
+    localState.snapshot = async () => {
+        const channels = supervisor.channelSnapshot();
+        const active = await buildManagementSnapshot(supervisor, tasks, updates);
+        const keepers = await buildKeeperStatuses(keeperPolicy, () => tasks.countedKeeperExecs);
+        const sum = (key) => keepers?.reduce((n, k) => n + (k.metrics[key] ?? 0), 0) ?? 0;
+        return { ...stoppedRuntime(), connection: channels.management === 'CONNECTED' ? 'online' : 'reconnecting',
+            activity: keepers === null ? null : { commands: Math.max(0, active.activeShellTasks + sum('execRunning') - sum('execCounted')), terminals: sum('ptyOpen'), agents: active.activeAgentTasks + sum('sessions'), transfers: 0 } };
+    };
     const stop = () => shutdown.abort();
     process.once('SIGINT', stop);
     process.once('SIGTERM', stop);
@@ -239,9 +605,24 @@ export async function runDaemon(options = {}) {
         await supervisor.run(shutdown.signal);
     }
     finally {
+        stopRdUpkeep();
+        rdUpkeep?.stop();
+        await desktopSupervisor?.close();
         process.removeListener('SIGINT', stop);
         process.removeListener('SIGTERM', stop);
         stopIdleSweep();
+        stopSwitchUpkeep();
         metrics.stop();
+        toolchain.stop();
+        stopRootsPoll();
+        stopLegacyPoll();
+        stopKeeperPolicy();
+        stopSocketTouch();
+        terminalKeepers.disconnect(); // only the connections: keeper-terminal and its PTYs outlive the daemon
+        // keeper-hosted sessions are detached (head checkpoint, adapter untouched, no failed turn); the others checkpoint (spec §5.5.5)
+        await agents.detachAll();
+        acp.closeTransports(); // keeper-acp's adapters outlive the daemon; local-fallback adapters die with it (spec §5.7)
+        // Bounded: a graceful host shutdown, then SIGKILL (a hung IO cannot hold the daemon's exit).
+        await filesHost.stop();
     }
 }

package/dist/workstation/daemonctl.js

@@ -1,10 +1,17 @@
 import os from 'node:os';
+import { BindingStore } from './control/bindingStore.js';
+import { stopRuntime } from './control/runtimeClient.js';
+import { LocalControlError } from './control/protocol.js';
+import { normalizeWorkstationServer } from './control/serverIdentity.js';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { clientDir, loadClientConfig } from './config.js';
+import { clientDir, loadClientConfig, updateServiceContext } from './config.js';
 import { createServiceManager } from './service/installer.js';
 import { buildServicePath } from './service/types.js';
 import { loginShellPath } from './service/loginShell.js';
+import { KeeperLauncher } from './keepers/kit/launcher.js';
+import { stopKeepers } from './keepers/stop.js';
+import { assertRuntimeRestartSafe } from './control/restartGuard.js';
 const __filename = fileURLToPath(import.meta.url);
 /**
  * The package's real npm bin entry (`package.json`'s `bin.axom`), given the directory a compiled
@@ -34,24 +41,41 @@ export function serviceContext() {
         throw new Error('Axomwork Workstation user service supervision is supported only on macOS and Linux.');
     }
     const directory = path.dirname(__filename);
-    const nodeDirectory = path.dirname(process.execPath);
+    const managed = updateServiceContext();
+    const nodeDirectory = path.dirname(managed.nodePath);
     return {
         platform: process.platform,
         username: os.userInfo().username,
         userId: process.getuid?.() ?? os.userInfo().uid,
         homeDir: os.homedir(),
-        nodePath: process.execPath,
+        nodePath: managed.nodePath,
         cliPath: CLI_PATH,
-        npmPath: process.env.AXOM_WORKSTATION_NPM_PATH ?? path.join(nodeDirectory, 'npm'),
+        npmPath: managed.npmPath,
         // dist/workstation/ is nested under lib/node_modules/@platless/axom-cli; climb to npm's prefix.
-        npmPrefix: process.env.AXOM_WORKSTATION_NPM_PREFIX ?? path.resolve(directory, '../../../../../..'),
+        npmPrefix: managed.npmPrefix,
         configDir: clientDir(),
-        pathEnv: buildServicePath(process.env.PATH, nodeDirectory),
+        pathEnv: buildServicePath(managed.env?.PATH ?? process.env.PATH, nodeDirectory),
+        ...(managed.managed ? { npmConfigPrefix: managed.managed.prefix } : {}),
     };
 }
+/** The workstation's keepers stopped (see {@link DaemonControllerDeps.stopKeepers}); an unregistered client has none. */
+async function stopRegisteredKeepers() {
+    const configDir = clientDir();
+    const config = await loadClientConfig(configDir).catch(() => null);
+    if (!config?.workstationId || !config.server)
+        return;
+    await stopKeepers(new KeeperLauncher({ configDir, workstationId: config.workstationId, server: config.server }), {
+        log: (line) => console.error(line),
+    });
+}
 const defaultDeps = {
+    identity: () => new BindingStore(clientDir()).inspect(),
+    runtime: async () => (await (await import('./control/inspect.js')).inspectWorkstation(clientDir())).runtime,
+    shutdown: generation => stopRuntime(clientDir(), generation),
+    restartSafe: generation => assertRuntimeRestartSafe(clientDir(), generation),
     service: (context) => createServiceManager(context ?? serviceContext()),
     config: () => loadClientConfig(clientDir()),
+    stopKeepers: stopRegisteredKeepers,
 };
 /**
  * User services own the daemon lifecycle. Deliberately no PID-file fallback remains: a stale
@@ -59,6 +83,22 @@ const defaultDeps = {
  */
 export function createDaemonController(overrides = {}) {
     const deps = { ...defaultDeps, ...overrides };
+    async function checked(options) {
+        const runtime = await deps.runtime();
+        if (runtime.state === 'unknown')
+            throw new LocalControlError('OUTCOME_UNKNOWN', 'Cannot verify the running workstation');
+        if (options) {
+            const identity = await deps.identity();
+            if (identity.revision !== options.guard.revision || runtime.generation !== options.guard.runtimeGeneration)
+                throw new LocalControlError('BINDING_CONFLICT', 'Workstation changed; check it again');
+        }
+        if (runtime.state === 'running') {
+            const config = await deps.config();
+            if (!runtime.binding || runtime.binding.server !== normalizeWorkstationServer(config.server) || runtime.binding.workstationId !== config.workstationId)
+                throw new LocalControlError('INSTANCE_OCCUPIED', 'Another workstation binding is running');
+        }
+        return runtime;
+    }
     return {
         async install() {
             // The definition is written from the login shell's PATH when one can be had, unioned with
@@ -73,16 +113,65 @@ export function createDaemonController(overrides = {}) {
                 : base;
             await deps.service(context).install({ interactive: true });
         },
-        async uninstall() { await deps.service().uninstall(); },
-        async start() { await deps.service().start(); },
-        async stop() { await deps.service().stop(); },
-        async restart() { await deps.service().restart(); },
+        // The workstation is stopped by the user: what its keepers host ends too (the daemon first, so nothing relaunches them).
+        // In a `finally`: a service that is not installed (or fails to stop) must not leave the keepers running.
+        async uninstall() { try {
+            await deps.service().uninstall();
+        }
+        finally {
+            await deps.stopKeepers();
+        } },
+        async start(options) { if ((await checked(options)).state === 'running')
+            return; await deps.service().start(); },
+        async stop(options) { const runtime = await checked(options); try {
+            if (runtime.mode === 'foreground' && runtime.generation)
+                await deps.shutdown(runtime.generation);
+            else
+                await deps.service().stop();
+        }
+        finally {
+            await deps.stopKeepers();
+        } },
+        // A restart keeps the keepers: terminals, commands and agent sessions go on under the next daemon.
+        async restart(options) {
+            const runtime = await checked(options);
+            if (runtime.state === 'running' && runtime.generation)
+                await deps.restartSafe(runtime.generation);
+            if (runtime.mode === 'foreground' && runtime.generation)
+                await deps.shutdown(runtime.generation);
+            await deps.service().restart();
+        },
+        async setEnabled(enabled, options) {
+            const runtime = await checked(options);
+            const service = deps.service();
+            if (!service.setEnabled)
+                throw new LocalControlError('UNSUPPORTED_PROTOCOL', 'Service enablement is unavailable');
+            if (enabled)
+                await service.setEnabled(true);
+            else {
+                try {
+                    await service.setEnabled(false);
+                    if (runtime.mode === 'foreground' && runtime.generation) {
+                        const current = await deps.runtime();
+                        if (current.state === 'running' && current.generation === runtime.generation)
+                            await deps.shutdown(runtime.generation);
+                        else if (current.state !== 'stopped')
+                            throw new LocalControlError('OUTCOME_UNKNOWN', 'The running workstation changed during shutdown');
+                    }
+                }
+                finally {
+                    await deps.stopKeepers();
+                }
+            }
+        },
         async status() {
+            const runtime = await deps.runtime();
+            if (runtime.state === 'running' && runtime.binding)
+                return { running: true, server: runtime.binding.server, workstationId: runtime.binding.workstationId };
+            if (runtime.state === 'unknown')
+                return { running: false, uncertain: true };
             const state = await deps.service().status();
-            if (!state.running)
-                return { running: false };
-            const config = await deps.config().catch(() => null);
-            return { running: true, server: config?.server, workstationId: config?.workstationId };
+            return state.running ? { running: true, uncertain: true } : { running: false };
         },
     };
 }