@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/daemon.js

@@ -1,3 +1,5 @@
+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';
@@ -12,7 +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 { 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';
 /**
  * The path `runDaemon` hands `createUpdateCoordinator` as `cliPath`, used to re-provision the OS
  * service after an update (see runUpdate.ts's `provisionService`).
@@ -106,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 () => {
@@ -157,6 +212,74 @@ 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 = {}) {
     // 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 —
@@ -170,7 +293,7 @@ export async function runDaemon(options = {}) {
     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 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
@@ -196,15 +319,132 @@ 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,
-        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();
@@ -212,17 +452,46 @@ export async function runDaemon(options = {}) {
         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: () => 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
@@ -231,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);
@@ -242,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/exec/attach.js

@@ -0,0 +1,126 @@
+import { ExecWireText } from './shaping.js';
+/** Spec §4.3: `exec_output` waits while the socket holds more than the high mark, until it drains below the low mark. */
+export const EXEC_WINDOW_HIGH_BYTES = 1024 * 1024;
+export const EXEC_WINDOW_LOW_BYTES = 256 * 1024;
+const WINDOW_POLL_MS = 20;
+/** Records per `exec.read` page (the keeper also caps a page at 1.5 MiB). */
+const PAGE_RECORDS = 1024;
+/** Re-read cadence when nothing new arrived and no progress was signalled. */
+const IDLE_POLL_MS = 500;
+const RETRY_MS = 1000;
+/** The v5 `exec_exit` of an ended durable exec (`exitFrame` is the today-shaped frame, exec/policy.ts `durableExitFrame`). */
+export function wireExitFrame(exitFrame, outcome, gapBytes) {
+    const signal = outcome.state === 'exited' ? outcome.exit.signal : null;
+    return { ...exitFrame, cancelled: outcome.cancelled, ...(signal ? { signal } : {}), ...(gapBytes > 0 ? { gaps: gapBytes } : {}) };
+}
+const sleep = (ms, signal) => new Promise((resolve) => {
+    if (signal.aborted) {
+        resolve();
+        return;
+    }
+    const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener('abort', done, { once: true });
+});
+/** Resolves once the socket has room for more output: at once below the high mark, else when it drained below the low mark. */
+export async function waitForWindow(bufferedAmount, signal, pollMs = WINDOW_POLL_MS) {
+    if (bufferedAmount() <= EXEC_WINDOW_HIGH_BYTES)
+        return;
+    while (!signal.aborted && bufferedAmount() > EXEC_WINDOW_LOW_BYTES)
+        await sleep(pollMs, signal);
+}
+/**
+ * Streams `exec` to `channel`: reads its records from keeper-terminal from the commit point on (decoding silently up to
+ * `fromOffset`), sends one `exec_output` per chunk at or after `fromOffset`, honouring the socket window, then the final
+ * `exec_status` and `exec_exit` once the exec ended. A non-streaming exec sends only the final two. `stop()` ends it silently
+ * (the channel closed, or a newer attach replaced it); the exec itself is untouched.
+ */
+export class ExecAttachment {
+    exec;
+    channel;
+    options;
+    abort = new AbortController();
+    done;
+    constructor(exec, channel, options) {
+        this.exec = exec;
+        this.channel = channel;
+        this.options = options;
+        this.done = this.run().catch((error) => { this.options.log?.(`exec ${options.id}: attachment failed: ${error instanceof Error ? error.message : String(error)}`); });
+    }
+    stop() { this.abort.abort(); }
+    get stopped() { return this.abort.signal.aborted; }
+    async run() {
+        const { exec } = this;
+        if (exec.wire?.streaming !== false)
+            await this.stream();
+        if (this.stopped)
+            return;
+        const outcome = await Promise.race([exec.outcome, new Promise((resolve) => this.abort.signal.addEventListener('abort', () => resolve(null), { once: true }))]);
+        if (outcome === null || this.stopped)
+            return;
+        const id = this.options.id;
+        this.channel.send({ t: 'exec_status', id, state: 'exited', headOffset: exec.finalHead, committedOffset: exec.committedOffset });
+        this.channel.send(this.options.exitFrame(outcome));
+    }
+    /** Waits for more records: a progress signal from the exec's own follower, a stop, or the idle poll. */
+    wait(ms) {
+        return new Promise((resolve) => {
+            const unsubscribe = this.exec.onProgress(() => { unsubscribe(); resolve(); });
+            void sleep(ms, this.abort.signal).then(() => { unsubscribe(); resolve(); });
+        });
+    }
+    async stream() {
+        const { exec, channel } = this;
+        const { id, fromOffset } = this.options;
+        const text = new ExecWireText();
+        let cursor = exec.commitFloor + 1;
+        const hold = exec.hold(cursor);
+        try {
+            while (!this.stopped) {
+                const exitAt = exec.exitRecordOffset;
+                if (exitAt !== undefined && cursor > exitAt)
+                    return;
+                let page;
+                try {
+                    page = await exec.read(cursor, PAGE_RECORDS);
+                }
+                catch (error) {
+                    if (exec.finished)
+                        return; // deleted, reclaimed or unreachable: the outcome says so
+                    this.options.log?.(`exec ${id}: read failed: ${error instanceof Error ? error.message : String(error)}`);
+                    await this.wait(RETRY_MS);
+                    continue;
+                }
+                if (this.stopped)
+                    return;
+                if (page.records.length === 0) {
+                    if (exec.finished)
+                        return;
+                    await this.wait(this.options.idleMs ?? IDLE_POLL_MS);
+                    continue;
+                }
+                for (const record of page.records) {
+                    if (record.o < cursor)
+                        continue;
+                    cursor = record.o + 1;
+                    hold.at = cursor;
+                    if (record.k === 'exit')
+                        return;
+                    if (record.k !== 'out' && record.k !== 'err')
+                        continue;
+                    const stream = record.k === 'out' ? 'stdout' : 'stderr';
+                    const chunk = text.push(stream, record.so, Buffer.from(record.b, 'base64'));
+                    if (!chunk || record.o < fromOffset)
+                        continue;
+                    await waitForWindow(() => channel.bufferedAmount(), this.abort.signal);
+                    if (this.stopped)
+                        return;
+                    channel.send({ t: 'exec_output', id, stream, chunk, offset: record.o, recvAtMs: record.t });
+                }
+            }
+        }
+        finally {
+            exec.unhold(hold);
+        }
+    }
+}

package/dist/workstation/exec/command.js

@@ -0,0 +1,40 @@
+// What the daemon decides about one `exec_request` before anything runs (spec §4.2 "daemon (policy)" column; analysis E §6.3–6.4):
+// the exact argv, the complete environment and the absolute deadline. Shared by the durable (keeper-terminal) path and the
+// in-process fallback, so both run the same command line in the same environment.
+import path from 'node:path';
+/**
+ * `[shell, '-lc', command]`, element by element what the daemon has always spawned (`spawn(req.shell, ['-lc', req.command])`):
+ * a login, non-interactive shell of the user's choice reading the command string exactly. Never wrapped (`sh -c`, `; echo $?`, …):
+ * any wrapping would go through the user's shell dialect (zsh EQUALS, fish quoting).
+ */
+export function execArgv(req) {
+    return [req.shell, '-lc', req.command];
+}
+/** The daemon's credential for its own server: never visible to a command (commands/workstation.ts drops it already; again here). */
+export const ACCESS_TOKEN_ENV = 'AXOM_ACCESS_TOKEN';
+/**
+ * The complete environment of the command: the daemon's environment without the access token, then the request's `env`, then
+ * `pathPrepend` in front of PATH (exactly as the daemon always did). keeper-terminal gets this whole map and never falls back to its
+ * own environment (under a systemd transient unit that would be the user manager's, frozen at the keeper's start).
+ */
+export function execEnvironment(daemonEnv, req) {
+    const env = {};
+    for (const [name, value] of Object.entries(daemonEnv))
+        if (value !== undefined && name !== ACCESS_TOKEN_ENV)
+            env[name] = value;
+    Object.assign(env, req.env);
+    if (req.pathPrepend.length > 0)
+        env.PATH = [...req.pathPrepend, env.PATH ?? ''].filter(Boolean).join(path.delimiter);
+    return env;
+}
+/**
+ * The absolute deadline, from `timeoutSeconds` and the DAEMON's clock at the moment it first received the request (never the
+ * server's clock). No timeout (absent, null, 0 or negative: today's rule) means no deadline.
+ */
+export function execDeadline(req, receivedAtMs) {
+    return req.timeoutSeconds && req.timeoutSeconds > 0 ? receivedAtMs + req.timeoutSeconds * 1000 : undefined;
+}
+/** keeper-terminal wants an absolute cwd; a relative one resolves against the daemon's cwd, as `spawn` always resolved it. */
+export function execCwd(req) {
+    return path.resolve(req.cwd || '.');
+}