@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/daemon.js

@@ -1,7 +1,9 @@
+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 } from './config.js';
+import { clientDir, loadClientConfig, readKeys, updateServiceContext } from './config.js';
 import { AgentSessionManager } from './agentSessions.js';
 import { AcpAgents } from './acp/acpAgents.js';
 import { ConnectionSupervisor } from './connection/supervisor.js';
@@ -12,6 +14,21 @@ import { TaskRegistry } from './update/taskRegistry.js';
 import { createUpdateCoordinator } from './update/runUpdate.js';
 import { resolveCliPath } from './daemonctl.js';
 import { SystemMetricsSampler } from './systemMetrics.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';
 /**
  * The path `runDaemon` hands `createUpdateCoordinator` as `cliPath`, used to re-provision the OS
  * service after an update (see runUpdate.ts's `provisionService`).
@@ -105,6 +122,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 () => {
@@ -140,6 +196,90 @@ export function resolveServiceLifecycle(options) {
     // provision-and-arm would hand that mode to a one-shot, unsupervised debugging invocation.
     return options.supervision === 'container' ? 'container' : 'none';
 }
+/**
+ * Builds the object `ManagementChannelOptions.snapshot` reports on every management heartbeat.
+ *
+ * Lifted out of `runDaemon` into its own function -- rather than staying the closure literal
+ * passed inline to `new ManagementChannel({ snapshot: ... })` -- specifically so a test can drive
+ * it directly. `runDaemon` boots a whole daemon (real config, real keys, a real `ManagementChannel`
+ * with no seam for injecting a socket), so before this extraction the *only* thing that ever
+ * verified `update:` here was the boot-*reconciled* phase (`updates.snapshotAsync()`), rather than
+ * the raw on-disk one (`updates.snapshot()`), was `tsc` accepting the `await`. `tsc` cannot tell
+ * `snapshotAsync()` and `snapshot()` apart by behavior -- both type-check -- so a future edit that
+ * quietly swaps one for the other would compile clean and wedge the server's view of every
+ * workstation the next time one restarts mid-update.
+ */
+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 = {}) {
     // 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 —
@@ -152,6 +292,9 @@ export async function runDaemon(options = {}) {
     const dir = clientDir();
     const cfg = await loadClientConfig(dir);
     const { clientKey, serverPub } = await readKeys(dir);
+    // Repair the first fixed release even when it was installed by an older ignore-scripts updater,
+    // 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
     // the same coordinator assembly — see runUpdate.ts.
@@ -176,31 +319,179 @@ export async function runDaemon(options = {}) {
     });
     // 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, 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 });
+    // 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 management = new ManagementChannel({
         server: cfg.server, workstationId: cfg.workstationId, workstation: cfg.workstationId, clientKey, serverPub,
         bridges: () => bridges,
         workspaces: cfg.workspaces,
+        playgroundCwd,
         metrics: () => metrics.snapshot(),
         allowInsecureWs,
         onReady: (ready) => updates.managementReady(ready.release, ready.generation),
         onUpdate: (command) => updates.handle(command),
         onExternalAgentsScan: async () => {
-            bridges = await acp.roster();
+            bridges = await scanRoster();
             return bridges;
         },
-        snapshot: () => ({ channels: supervisor.channelSnapshot(), ...tasks.snapshot(), update: updates.snapshot() }),
+        snapshot: () => buildManagementSnapshot(supervisor, tasks, updates),
+        keepers: () => buildKeeperStatuses(keeperPolicy, () => tasks.countedKeeperExecs),
+        onKeeperControl: (frame) => keeperPolicy.control(frame),
     });
     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
@@ -209,6 +500,7 @@ export async function runDaemon(options = {}) {
         log: (message) => console.log(`${new Date().toISOString()} ${message}`),
     });
     const stopIdleSweep = startIdleSweep(agents);
+    const stopSwitchUpkeep = startSwitchUpkeep(agents, acp);
     const shutdown = new AbortController();
     const stop = () => shutdown.abort();
     process.once('SIGINT', stop);
@@ -220,6 +512,17 @@ export async function runDaemon(options = {}) {
         process.removeListener('SIGINT', stop);
         process.removeListener('SIGTERM', stop);
         stopIdleSweep();
+        stopSwitchUpkeep();
         metrics.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

@@ -5,6 +5,8 @@ import { clientDir, loadClientConfig } 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';
 const __filename = fileURLToPath(import.meta.url);
 /**
  * The package's real npm bin entry (`package.json`'s `bin.axom`), given the directory a compiled
@@ -49,9 +51,20 @@ export function serviceContext() {
         pathEnv: buildServicePath(process.env.PATH, nodeDirectory),
     };
 }
+/** 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 = {
     service: (context) => createServiceManager(context ?? serviceContext()),
     config: () => loadClientConfig(clientDir()),
+    stopKeepers: stopRegisteredKeepers,
 };
 /**
  * User services own the daemon lifecycle. Deliberately no PID-file fallback remains: a stale
@@ -73,9 +86,22 @@ export function createDaemonController(overrides = {}) {
                 : base;
             await deps.service(context).install({ interactive: true });
         },
-        async uninstall() { await deps.service().uninstall(); },
+        // 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() { await deps.service().start(); },
-        async stop() { await deps.service().stop(); },
+        async stop() { try {
+            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() { await deps.service().restart(); },
         async status() {
             const state = await deps.service().status();

package/dist/workstation/desktop/binding.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+function endpoint(text, kind) {
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw new Error('Invalid browser endpoint');
+    }
+    // Require literal loopback authorities, before WHATWG canonicalizes short/hex IPv4.
+    if (!/^(?:tcp|ws|wss|http|https):\/\/(?:127\.0\.0\.1|\[::1\]):\d+(?:\/|$)/.test(text) || url.username || url.password || url.search || url.hash || !url.port || Number(url.port) < 1 || Number(url.port) > 65535)
+        throw new Error('Browser endpoints require an explicit loopback host and port without credentials');
+    if (kind === 'vnc' ? !['tcp:', 'ws:', 'wss:'].includes(url.protocol) : !['http:', 'https:'].includes(url.protocol))
+        throw new Error('Unsupported browser endpoint transport');
+    if (url.protocol === 'tcp:' && url.pathname && url.pathname !== '/')
+        throw new Error('TCP endpoint cannot have a path');
+    return url.toString();
+}
+export function resolveBrowserBinding(config, env = process.env) {
+    if (config && (typeof config !== 'object' || typeof config.vncEndpoint !== 'string' || !config.vncEndpoint))
+        throw new Error('Invalid browser binding config');
+    const vnc = env.AXOM_BROWSER_VNC_URL ?? config?.vncEndpoint;
+    if (!vnc)
+        return undefined;
+    const binding = { bindingId: config?.bindingId ?? 'default', displayName: config?.displayName ?? 'Shared browser', vncEndpoint: endpoint(vnc, 'vnc'), cdpEndpoint: env.AXOM_BROWSER_CDP_URL ?? config?.cdpEndpoint, downloadsRoot: config?.downloadsRoot };
+    if (typeof binding.bindingId !== 'string' || !binding.bindingId || binding.bindingId.length > 128 || typeof binding.displayName !== 'string' || !binding.displayName || binding.displayName.length > 128)
+        throw new Error('Invalid browser binding metadata');
+    if (binding.cdpEndpoint)
+        binding.cdpEndpoint = endpoint(binding.cdpEndpoint, 'cdp');
+    if (binding.downloadsRoot !== undefined && (typeof binding.downloadsRoot !== 'string' || !path.isAbsolute(binding.downloadsRoot) || binding.downloadsRoot.includes('\0')))
+        throw new Error('Browser downloadsRoot must be an explicit absolute directory');
+    return binding;
+}
+export function browserCapability(binding) {
+    return { bindingId: binding?.bindingId ?? null, displayName: binding?.displayName ?? null, configured: !!binding, cdp: !!binding?.cdpEndpoint };
+}