@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/channels/agent.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
 import { AGENT_WIRE_MIN_VERSION, AGENT_WIRE_RESUME_OFFER_VERSION, AGENT_WIRE_VERSION, decodeAgentFrame, encodeAgentFrame, outboundAgentFrameRejection, } from '../protocol/agent.js';
-import { bridgesForWire } from '../protocol/common.js';
+import { bridgesForWire, helloRoster } from '../protocol/common.js';
 import { workstationChannelUrl } from './url.js';
 /** Binds daemon-scoped sessions only to the encrypted agent channel's sender. */
 export class AgentChannel {
@@ -25,7 +25,9 @@ export class AgentChannel {
         // Hoisted rather than inlined twice: `closeAll` compares it by identity to decide whether the
         // binding it is being asked to drop is still this connection's. See AgentSessionManager.closeAll.
         const send = (frame) => channel.send(frame);
-        void dispatchAgentChannelFrames(channel.messages, send, this.options.agents, () => channel.close());
+        // The socket's unsent bytes: the manager's socket gate holds session frames back above 1 MiB so the heartbeat (written by the
+        // channel itself) never queues behind a backlog (spec §5.6).
+        void dispatchAgentChannelFrames(channel.messages, send, this.options.agents, () => channel.close(), () => channel.bufferedAmount);
         void channel.closed.then(() => this.options.agents.closeAll(send));
         return { closed: channel.closed, close: () => channel.close() };
     }
@@ -58,10 +60,10 @@ export function agentHeartbeat(seq, sentAtEpochMs, agents) {
 }
 /** Exported so the roster this hello carries can be asserted without opening a socket. */
 export function buildAgentHelloFrame(ticket, bridges) {
-    return { t: 'agent_hello', ticket, bridges: bridgesForWire(bridges(), 'agent_hello') };
+    return { t: 'agent_hello', ticket, bridges: bridgesForWire(helloRoster(bridges()), 'agent_hello') };
 }
 /** Negotiates one agent connection and emits exactly one reconnect offer when the server supports it. */
-export async function dispatchAgentChannelFrames(messages, send, agents, close = () => { }) {
+export async function dispatchAgentChannelFrames(messages, send, agents, close = () => { }, bufferedAmount) {
     let offered = false;
     try {
         for await (const frame of messages) {
@@ -71,7 +73,7 @@ export async function dispatchAgentChannelFrames(messages, send, agents, close =
                     return;
                 }
                 const negotiated = Math.min(frame.agentWire, AGENT_WIRE_VERSION);
-                agents.bindSend(send, negotiated);
+                agents.bindSend(send, negotiated, bufferedAmount);
                 if (!offered && negotiated >= AGENT_WIRE_RESUME_OFFER_VERSION) {
                     offered = true;
                     send({ t: 'agent_resume_offer', sessions: await agents.resumeOfferSessions() });

package/dist/workstation/channels/computer.js

@@ -3,19 +3,21 @@ import { resolveBrowserBinding } from '../desktop/binding.js';
 import { createHash } from 'node:crypto';
 import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
 import { runExec } from '../exec.js';
+import { ExecPolicy, keeperExecsOutliveTheChannel } from '../exec/policy.js';
+import { ComputerExecWire } from './computerExecs.js';
 import { decodeComputerFrame, encodeComputerFrame } from '../protocol/computer.js';
 import { workstationChannelUrl } from './url.js';
 import { TaskRegistry } from '../update/taskRegistry.js';
-import { createComputerDirSafely, listComputerDirSafely, readComputerFileSafely, writeComputerFileSafely } from '../fileWorkerClient.js';
-import { computerFileError } from '../filePaths.js';
-import { ToolsClient } from '../tools/client.js';
+import { toFileError } from '../files/errors.js';
 import { object } from '../tools/validation.js';
+import { isUnaccountedTool } from '../tools/router.js';
+import { requestRootFileExecutors } from '../files/adapters/computerFileFrames.js';
 /**
  * Consumes computer frames without serializing long-running commands behind one another.
  * All command failures and post-close sends are contained here because this is called detached
  * from the socket connection loop.
  */
-export async function dispatchComputerFrames(messages, send, execute, tasks = new TaskRegistry(), files = {}, tools, desktop) {
+export async function dispatchComputerFrames(messages, send, execute, tasks = new TaskRegistry(), files = {}, tools, desktop, durable = {}) {
     const active = new Map();
     const activeTools = new Set();
     let open = true;
@@ -25,6 +27,9 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
         send(frame);
     }
     catch { /* socket already closed */ } };
+    // Wire ≥ 5 (keeperExecsOutliveTheChannel): exec frames go to the exec policy, which owns the execs (spec §4.3).
+    const execWire = new ComputerExecWire(durable.host ?? new ExecPolicy(), tasks, { send: safeSend, bufferedAmount: durable.bufferedAmount ?? (() => 0) }, durable.log);
+    const durableWire = () => keeperExecsOutliveTheChannel(wireVersion);
     const run = (request) => {
         if (!tasks.accepting) {
             safeSend({ t: 'exec_exit', id: request.id, exitCode: null, stdout: '', stderr: 'Workstation is not accepting new work', timedOut: false, truncated: false });
@@ -35,6 +40,8 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
         // the most recently accepted request while the older promise still cleans up its own entry.
         active.get(request.id)?.abort();
         active.set(request.id, controller);
+        // Wire ≤ 4 (spec §4.3 "compat", §8.2): every exec, in keeper-terminal or not, is a shell task (counted, drained, aborted by a
+        // force update) and is killed when the channel closes: the server reports it ended and an agent may run it again.
         void (async () => {
             try {
                 const exit = await tasks.withShellTask(async (shutdown) => {
@@ -43,10 +50,19 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
                         controller.abort();
                     else
                         shutdown.addEventListener('abort', onShutdown, { once: true });
+                    // A keeper-terminal exec is a shell task here AND in keeper-terminal's execRunning: counted once on the page (minor 7).
+                    let uncount;
                     try {
-                        return await execute(request, request.streaming ? (stream, chunk) => safeSend({ t: 'exec_output', id: request.id, stream, chunk }) : undefined, controller.signal);
+                        return await execute(request, request.streaming ? (stream, chunk) => safeSend({ t: 'exec_output', id: request.id, stream, chunk }) : undefined, controller.signal, {
+                            outlivesChannel: false,
+                            onStarted: (info) => { if (info.durable) {
+                                uncount?.();
+                                uncount = tasks.countKeeperExec();
+                            } },
+                        });
                     }
                     finally {
+                        uncount?.();
                         shutdown.removeEventListener('abort', onShutdown);
                     }
                 });
@@ -94,16 +110,18 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
                     else
                         shutdown.addEventListener('abort', onShutdown, { once: true });
                     try {
+                        if (files.runFrame)
+                            return await files.runFrame(request, controller.signal);
                         if (request.t === 'file_read_request') {
-                            return await (files.readFile ?? readComputerFileSafely)({ root: request.root, path: request.path, startLine: request.startLine, maxLines: request.maxLines }, controller.signal);
+                            return await (files.readFile ?? requestRootFileExecutors.readFile)({ root: request.root, path: request.path, startLine: request.startLine, maxLines: request.maxLines }, controller.signal);
                         }
                         if (request.t === 'file_write_request') {
-                            return await (files.writeFile ?? writeComputerFileSafely)({ root: request.root, path: request.path, content: request.content, mode: request.mode, expectedSha256: request.expectedSha256 }, controller.signal);
+                            return await (files.writeFile ?? requestRootFileExecutors.writeFile)({ root: request.root, path: request.path, content: request.content, mode: request.mode, expectedSha256: request.expectedSha256 }, controller.signal);
                         }
                         if (request.t === 'file_ls_request') {
-                            return await (files.listDir ?? listComputerDirSafely)({ root: request.root, path: request.path, startAfter: request.startAfter, maxEntries: request.maxEntries }, controller.signal);
+                            return await (files.listDir ?? requestRootFileExecutors.listDir)({ root: request.root, path: request.path, startAfter: request.startAfter, maxEntries: request.maxEntries }, controller.signal);
                         }
-                        return await (files.createDir ?? createComputerDirSafely)({ root: request.root, path: request.path, parents: request.parents }, controller.signal);
+                        return await (files.createDir ?? requestRootFileExecutors.createDir)({ root: request.root, path: request.path, parents: request.parents }, controller.signal);
                     }
                     finally {
                         shutdown.removeEventListener('abort', onShutdown);
@@ -111,6 +129,10 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
                 });
                 if (active.get(request.id) !== controller)
                     return;
+                if (files.runFrame) {
+                    safeSend(data);
+                    return;
+                }
                 if (request.t === 'file_read_request')
                     safeSend({ t: 'file_read_result', id: request.id, data: data });
                 else if (request.t === 'file_write_request')
@@ -123,7 +145,7 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
             catch (error) {
                 if (active.get(request.id) !== controller)
                     return;
-                const mapped = computerFileError(error);
+                const mapped = toFileError(error);
                 if (controller.signal.aborted) {
                     const mutation = request.t === 'file_write_request' || request.t === 'file_mkdir_request';
                     fail(mutation ? 'outcome_unknown' : 'workstation_offline', request.t === 'file_write_request' ? 'Write outcome is unknown after cancellation'
@@ -145,12 +167,15 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
             fail('Workstation tools require computer wire v3');
             return;
         }
-        if (!tasks.accepting) {
+        // tools.info (a probe) and terminal.* (PTYs live in their keeper) answer while draining and are not work a restart
+        // would interrupt: no admission gate, no shell-task accounting.
+        const probe = isUnaccountedTool(request.method);
+        if (!probe && !tasks.accepting) {
             fail('Workstation is not accepting new work');
             return;
         }
         if (!tools && request.method !== 'browser.sharedText') {
-            fail('Workstation tools keeper is not configured');
+            fail('Workstation tools are not configured');
             return;
         }
         if (activeTools.has(request.id)) {
@@ -165,10 +190,11 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
         void (async () => {
             let timer;
             try {
-                const result = await tasks.withShellTask(() => Promise.race([
+                const call = () => Promise.race([
                     request.method === 'browser.sharedText' ? (desktop ? desktop.insertText(request.params) : Promise.reject(Error('Shared desktop unavailable'))) : tools(request.method, request.params),
                     new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error('Workstation tool timed out; mutation outcome may be unknown')), 7500); }),
-                ]));
+                ]);
+                const result = probe ? await call() : await tasks.withShellTask(call);
                 if (!object(result))
                     throw new Error('Invalid workstation tool result');
                 safeSend({ t: 'tool_result', id: request.id, ok: true, result, error: null });
@@ -189,10 +215,25 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
                 desktop?.onFrame(frame);
             else if (frame.t === 'tool_request')
                 runTool(frame);
-            else if (frame.t === 'exec_request')
-                run(frame);
-            else if (frame.t === 'exec_cancel')
+            else if (frame.t === 'exec_request') {
+                if (durableWire())
+                    execWire.request(frame);
+                else
+                    run(frame);
+            }
+            else if (frame.t === 'exec_cancel') {
                 active.get(frame.id)?.abort();
+                if (durableWire())
+                    execWire.cancel(frame);
+            }
+            else if (frame.t === 'exec_attach') {
+                if (durableWire())
+                    execWire.attachFrame(frame);
+            }
+            else if (frame.t === 'exec_ack') {
+                if (durableWire())
+                    execWire.ack(frame);
+            }
             else if (frame.t === 'computer_ready') {
                 wireVersion = frame.wireVersion;
                 desktop?.ready(frame.generation, frame.wireVersion);
@@ -204,6 +245,7 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
     finally {
         open = false;
         desktop?.close();
+        execWire.close();
         for (const controller of active.values())
             controller.abort();
     }
@@ -213,11 +255,15 @@ export class ComputerChannel {
     options;
     tasks;
     tools;
+    /** One exec host for every channel this object opens: execs outlive a channel and are re-attached on the next one. */
+    execs;
     constructor(options) {
         this.options = options;
         this.tasks = options.taskRegistry ?? new TaskRegistry();
-        const client = options.toolsConfig ? new ToolsClient(options.toolsConfig) : undefined;
-        this.tools = options.tools ?? (client ? (method, params) => client.request(method, params) : undefined);
+        this.execs = options.execs ?? new ExecPolicy();
+        // Tools only through the caller's router (daemon.ts): no fallback to a terminal-kind ToolsClient, whose request() would start
+        // (or reach) the legacy tools keeper behind the TerminalRouter's back.
+        this.tools = options.tools;
     }
     activeTaskCount() { return this.tasks.snapshot().activeShellTasks; }
     async connect(ticket, signal) {
@@ -233,7 +279,9 @@ export class ComputerChannel {
         return { closed: channel.closed, close: () => channel.close() };
     }
     async dispatch(channel) {
-        const desktop = new DesktopBridge(resolveBrowserBinding(this.options.browserBinding ?? this.options.toolsConfig?.browserBinding), frame => channel.send(frame), () => channel.bufferedAmount);
-        await dispatchComputerFrames(channel.messages, (frame) => channel.send(frame), this.options.runExec ?? runExec, this.tasks, this.options, this.tools, desktop);
+        const desktop = new DesktopBridge(resolveBrowserBinding(this.options.browserBinding), frame => channel.send(frame), () => channel.bufferedAmount);
+        await dispatchComputerFrames(channel.messages, (frame) => channel.send(frame), this.options.runExec ?? ((request, onOutput, signal) => runExec(request, onOutput, signal)), this.tasks, this.options, this.tools, desktop, {
+            host: this.execs, bufferedAmount: () => channel.bufferedAmount, log: this.options.log,
+        });
     }
 }

package/dist/workstation/channels/computerExecs.js

@@ -0,0 +1,200 @@
+// COMPUTER wire v5 exec frames of ONE computer channel (spec §4.3, §8.2): exec_request / exec_attach / exec_ack / exec_cancel in,
+// exec_started / exec_output (with offsets) / exec_status / exec_exit out. The execs themselves belong to the exec policy
+// (exec/policy.ts `DurableExecHost`), not to this channel: a channel close only stops this channel's attachments.
+//
+// - A keeper exec (durable) is never a shell task: not counted in `activeShellTasks`, admitted while an update drains, untouched by
+//   a force update (`stopAll`) and by a channel close.
+// - A fallback exec (in this process, `durable:false`) keeps today's semantics: a shell task, refused while draining, killed by a
+//   force update and by a channel close.
+// - An exec_request for an id the policy already knows is an attach (exec_started again, then its output from offset 0): never a
+//   second run.
+import { ExecAttachment, wireExitFrame } from '../exec/attach.js';
+import { durableExitFrame } from '../exec/policy.js';
+export const NOT_ACCEPTING_MESSAGE = 'Workstation is not accepting new work';
+/** How soon an `exec_attach` whose exec's state could not be decided asks the policy again. */
+export const ATTACH_UNDECIDED_RETRY_MS = 2000;
+/** A v5 `exec_exit` that is not the outcome of a durable exec (refused, limit, fallback): today's fields plus `cancelled`. */
+function plainExit(exit, cancelled) {
+    return { ...exit, cancelled };
+}
+export class ComputerExecWire {
+    host;
+    tasks;
+    channel;
+    log;
+    options;
+    /** This channel's attachment per server exec id (one at a time: a newer attach replaces the older). */
+    attachments = new Map();
+    /** In-process (fallback) execs started by this channel: they die with it. */
+    fallbacks = new Map();
+    /** Requests between receipt and knowing where they run, with an exec_cancel received meanwhile. */
+    pending = new Map();
+    closed = false;
+    constructor(host, tasks, channel, log = () => { }, options = {}) {
+        this.host = host;
+        this.tasks = tasks;
+        this.channel = channel;
+        this.log = log;
+        this.options = options;
+    }
+    send(frame) { if (!this.closed)
+        this.channel.send(frame); }
+    request(frame) {
+        if (this.fallbacks.has(frame.id) || this.pending.has(frame.id))
+            return; // the same request again on this channel: already running
+        const pending = { cancelled: false };
+        this.pending.set(frame.id, pending);
+        // Counted (not gated, not stoppable) from here until the exec has its first checkpoint: a drain admits a v5 exec, but a restart
+        // inside this window would leave keeper-terminal with an exec the next daemon can only identify by its id (spec §8.2).
+        const release = this.tasks.holdShellTask();
+        void (async () => {
+            try {
+                const started = await this.host.startOrFind(frame);
+                if (started.kind !== 'durable')
+                    release();
+                if (started.kind === 'exit') {
+                    this.send(plainExit(started.exit, false));
+                    return;
+                }
+                if (started.kind === 'durable') {
+                    const { exec } = started;
+                    const uncount = this.tasks.countKeeperExec(); // held in activeShellTasks AND running in keeper-terminal (minor 7)
+                    void exec.firstCheckpoint.finally(() => { uncount(); release(); });
+                    this.send({ t: 'exec_started', id: frame.id, durable: true, ...(exec.pid !== null ? { pid: exec.pid } : {}), startedAtMs: exec.startedAtMs });
+                    this.attach(frame.id, exec, 0);
+                    if (pending.cancelled)
+                        void this.host.cancel(frame.id).catch(() => { }); // cancelled before the policy knew the id
+                    return;
+                }
+                // Not durable: today's rules (spec §8.2): refused while an update drains, counted, killed by a force update or a close.
+                if (!this.tasks.accepting || this.closed) {
+                    this.send(plainExit({ t: 'exec_exit', id: frame.id, exitCode: null, stdout: '', stderr: NOT_ACCEPTING_MESSAGE, timedOut: false, truncated: false }, false));
+                    return;
+                }
+                await this.runFallback(frame, started.run, pending.cancelled);
+            }
+            catch (error) {
+                release();
+                this.send(plainExit({ t: 'exec_exit', id: frame.id, exitCode: null, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: false, truncated: false }, false));
+            }
+            finally {
+                if (this.pending.get(frame.id) === pending)
+                    this.pending.delete(frame.id);
+            }
+        })();
+    }
+    async runFallback(frame, run, cancelledEarly) {
+        const entry = { controller: new AbortController(), cancelled: cancelledEarly };
+        if (cancelledEarly)
+            entry.controller.abort();
+        this.fallbacks.set(frame.id, entry);
+        let offset = 0;
+        const onOutput = frame.streaming
+            ? (stream, chunk) => this.send({ t: 'exec_output', id: frame.id, stream, chunk, offset: offset++, recvAtMs: Date.now() })
+            : undefined;
+        try {
+            const exit = await this.tasks.withShellTask(async (shutdown) => {
+                const onShutdown = () => entry.controller.abort();
+                if (shutdown.aborted)
+                    onShutdown();
+                else
+                    shutdown.addEventListener('abort', onShutdown, { once: true });
+                try {
+                    return await run(onOutput, entry.controller.signal, (info) => {
+                        this.send({ t: 'exec_started', id: frame.id, durable: false, ...(info.pid !== undefined ? { pid: info.pid } : {}), startedAtMs: info.startedAtMs });
+                    });
+                }
+                finally {
+                    shutdown.removeEventListener('abort', onShutdown);
+                }
+            });
+            this.send(plainExit(exit, entry.cancelled));
+        }
+        catch (error) {
+            this.send(plainExit({ t: 'exec_exit', id: frame.id, exitCode: null, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: false, truncated: false }, entry.cancelled));
+        }
+        finally {
+            if (this.fallbacks.get(frame.id) === entry)
+                this.fallbacks.delete(frame.id);
+        }
+    }
+    /** Streams `exec` to this channel from `fromOffset` (replacing an older attachment of the same id). */
+    attach(id, exec, fromOffset) {
+        if (this.closed)
+            return;
+        this.attachments.get(id)?.stop();
+        const attachment = new ExecAttachment(exec, { send: (frame) => this.send(frame), bufferedAmount: () => this.channel.bufferedAmount() }, {
+            id, fromOffset, log: this.log,
+            exitFrame: (outcome) => wireExitFrame(durableExitFrame(id, outcome), outcome, exec.gapBytes),
+        });
+        this.attachments.set(id, attachment);
+        void attachment.done.finally(() => { if (this.attachments.get(id) === attachment)
+            this.attachments.delete(id); });
+    }
+    /** `exec_attach`: `exec_status` now, then the output from `fromOffset` and, once ended, the final status and the exit. */
+    attachFrame(frame) {
+        void (async () => {
+            if (this.fallbacks.has(frame.id)) { // in this process on this very channel: nothing to re-attach, it is still streaming here
+                this.send({ t: 'exec_status', id: frame.id, state: 'running', headOffset: -1, committedOffset: -1 });
+                return;
+            }
+            // It ran in this process for another channel (its exec_started{durable:false} may never have reached the server): `running` /
+            // `exited` and, once it ended, its exit — never `unknown`, which would make the server send the request again (Task 26).
+            const fallback = this.host.fallbackOf?.(frame.id);
+            if (fallback) {
+                this.send({ t: 'exec_status', id: frame.id, state: fallback.done ? 'exited' : 'running', headOffset: -1, committedOffset: -1 });
+                const exit = await fallback.exit;
+                this.send({ t: 'exec_status', id: frame.id, state: 'exited', headOffset: -1, committedOffset: -1 });
+                this.send({ ...exit, id: frame.id });
+                return;
+            }
+            // `unknown` only when the policy PROVED nobody runs it (the server then gives the exec up, or sends its request again). When
+            // keeper-terminal could not be asked (slow after a restart, not answering) the answer waits: asked again until it is decided or
+            // this channel closes (the next channel's attach asks anew). The server's own wait limit bounds it.
+            let exec;
+            while (exec === undefined) {
+                try {
+                    exec = await this.host.find(frame.id);
+                }
+                catch (error) {
+                    if (this.closed)
+                        return;
+                    this.log(`exec ${frame.id}: attach deferred: ${error instanceof Error ? error.message : String(error)}`);
+                    await new Promise((resolve) => setTimeout(resolve, this.options.undecidedRetryMs ?? ATTACH_UNDECIDED_RETRY_MS));
+                    if (this.closed)
+                        return;
+                }
+            }
+            if (!exec) {
+                this.send({ t: 'exec_status', id: frame.id, state: 'unknown', headOffset: -1, committedOffset: -1 });
+                return;
+            }
+            const status = await exec.wireStatus();
+            this.send({ t: 'exec_status', id: frame.id, ...status });
+            this.attach(frame.id, exec, frame.fromOffset);
+        })().catch((error) => this.log(`exec ${frame.id}: attach failed: ${error instanceof Error ? error.message : String(error)}`));
+    }
+    ack(frame) { this.host.acknowledge(frame.id, frame.throughOffset); }
+    /** `exec_cancel`: idempotent, silent for an unknown or ended exec. */
+    cancel(frame) {
+        const pending = this.pending.get(frame.id);
+        if (pending)
+            pending.cancelled = true;
+        const fallback = this.fallbacks.get(frame.id);
+        if (fallback) {
+            fallback.cancelled = true;
+            fallback.controller.abort();
+            return;
+        }
+        void this.host.cancel(frame.id, frame.signal).catch((error) => this.log(`exec ${frame.id}: cancel failed: ${error instanceof Error ? error.message : String(error)}`));
+    }
+    /** The channel closed: stop streaming (durable execs keep running for the next channel) and kill this channel's fallback execs. */
+    close() {
+        this.closed = true;
+        for (const attachment of this.attachments.values())
+            attachment.stop();
+        this.attachments.clear();
+        for (const fallback of this.fallbacks.values())
+            fallback.controller.abort();
+    }
+}

package/dist/workstation/channels/management.js

@@ -1,14 +1,15 @@
 import { deriveSessionKey, randomBytes } from '../crypto.js';
 import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
 import { CLIENT_PACKAGE_NAME, CLIENT_VERSION } from '../version.js';
-import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_DRAINING_VERSION, MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION, MANAGEMENT_WIRE_METRICS_VERSION, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_PRESSURE_VERSION, MANAGEMENT_WIRE_VERSION, } from '../protocol/management.js';
-import { bridgesForWire } from '../protocol/common.js';
+import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_DRAINING_VERSION, MANAGEMENT_WIRE_GPU_VERSION, MANAGEMENT_WIRE_KEEPERS_VERSION, MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION, MANAGEMENT_WIRE_METRICS_VERSION, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_PRESSURE_VERSION, MANAGEMENT_WIRE_VERSION, } from '../protocol/management.js';
+import { bridgesForWire, helloRoster } from '../protocol/common.js';
 import { AGENT_WIRE_MIN_VERSION, AGENT_WIRE_VERSION } from '../protocol/agent.js';
 import { osInfo } from '../osinfo.js';
 import { workstationChannelUrl } from './url.js';
 const protocols = {
     MANAGEMENT: { min: MANAGEMENT_WIRE_MIN_VERSION, max: MANAGEMENT_WIRE_VERSION },
-    COMPUTER: { min: 1, max: 4 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION },
+    // COMPUTER v5: durable exec frames (exec_started/attach/status/ack, offsets on exec_output; spec §4.3).
+    COMPUTER: { min: 1, max: 5 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION },
 };
 /** Exported so tests can assert the wire frame's `clientPackage` without opening a socket. */
 export function buildHelloFrame(options, clientNonce) {
@@ -24,7 +25,7 @@ export function buildHelloFrame(options, clientNonce) {
  */
 function helloBridges(bridges) {
     const roster = bridges?.();
-    return roster === undefined ? undefined : bridgesForWire(roster, 'management_hello');
+    return roster === undefined ? undefined : bridgesForWire(helloRoster(roster), 'management_hello');
 }
 /** Exported so the roster this answer carries can be asserted without driving a whole channel. */
 export function buildScanResultFrame(commandId, bridges) {
@@ -57,6 +58,10 @@ export function metricsForManagementWire(metrics, serverManagementWire) {
     if (!metrics)
         return metrics;
     const selectedWire = serverManagementWire ?? 0;
+    if (selectedWire < MANAGEMENT_WIRE_GPU_VERSION && metrics.gpus !== undefined) {
+        const { gpus: _gpus, ...withoutGpus } = metrics;
+        return metricsForManagementWire(withoutGpus, selectedWire);
+    }
     if (selectedWire >= MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION) {
         const { cpuLoadNormalized: _cpuLoadNormalized, ...rawLoad } = metrics;
         return rawLoad;
@@ -98,6 +103,51 @@ export function dispatchUpdateCommand(channel, command, onUpdate, serverManageme
     })
         .catch(() => { });
 }
+/**
+ * The most a heartbeat waits for its `keepers` sample. The channel builds the next heartbeat only after this one went out, so a sample
+ * that hangs (a wedged `ps`, a stuck file read) must never hold the frame: past this it goes out with `keepers: null`.
+ */
+export const KEEPERS_SAMPLE_CAP_MS = 1500;
+/**
+ * Heartbeat `keepers` for the negotiated wire: absent below 8 (an older server does not know the field), the sampled list from 8 on,
+ * `null` when sampling failed or did not answer within `capMs`. Never rejects, never waits longer than `capMs`. Exported for tests.
+ */
+export async function keepersForManagementWire(sample, serverManagementWire, capMs = KEEPERS_SAMPLE_CAP_MS) {
+    if (!sample || (serverManagementWire ?? 0) < MANAGEMENT_WIRE_KEEPERS_VERSION)
+        return {};
+    let timer;
+    const capped = new Promise((resolve) => { timer = setTimeout(() => resolve(null), capMs); timer.unref?.(); });
+    try {
+        const sampled = Promise.resolve().then(sample);
+        sampled.catch(() => undefined); // a late rejection after the cap must not be unhandled
+        return { keepers: await Promise.race([sampled, capped]) };
+    }
+    catch {
+        return { keepers: null };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Runs one `keeper_control` and sends its result if the channel is still open. Detached from the frame loop (a replace-now stops
+ * keeper processes, which takes seconds). Exported for tests.
+ */
+export function dispatchKeeperControl(channel, frame, onKeeperControl) {
+    return onKeeperControl(frame)
+        .catch((error) => ({
+        t: 'keeper_control_result', commandId: frame.commandId, kind: frame.kind, action: frame.action, ok: false, affected: [],
+        error: error instanceof Error ? error.message : String(error),
+    }))
+        .then((result) => {
+        if (channel.state !== 'OPEN')
+            return;
+        try {
+            channel.send(result);
+        }
+        catch { /* the channel closed meanwhile; the server asks again with the same commandId */ }
+    });
+}
 /**
  * The server nonce to derive this session's key from.
  *
@@ -125,9 +175,29 @@ export class ManagementChannel {
     options;
     /** Undefined until this connection receives management_ready; reset for every reconnect. */
     serverManagementWire;
+    /** The open channel of the current connection, for frames this client sends unprompted ({@link pushRoster}). */
+    channel;
     constructor(options) {
         this.options = options;
     }
+    /**
+     * Tell the server about a roster that changed without a scan asking (adapter builds moved by Axom,
+     * spec §6.1): the same `external_agents_scan_result` frame a scan answers with, under a client-made
+     * command id no scan is waiting on — the server records the roster and completes nothing. `false`
+     * when there is no open connection; the next `management_hello` carries {@link ManagementChannelOptions.bridges} then.
+     */
+    pushRoster(bridges) {
+        const channel = this.channel;
+        if (!channel || channel.state !== 'OPEN')
+            return false;
+        try {
+            channel.send(buildScanResultFrame(`roster-push-${randomBytes(8).toString('hex')}`, bridges));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     async connect(signal) {
         this.serverManagementWire = undefined;
         const nonce = randomBytes(16);
@@ -161,6 +231,10 @@ export class ManagementChannel {
         // is never driven by the local browser/device-authorization flow.
         await this.options.onReady?.({ generation: ready.generation, release: ready.release });
         const pending = new Map();
+        this.channel = channel;
+        void channel.closed.then(() => { if (this.channel === channel)
+            this.channel = undefined; }, () => { if (this.channel === channel)
+            this.channel = undefined; });
         void this.routeMessages(channel, pending);
         return {
             generation: ready.generation,
@@ -184,6 +258,7 @@ export class ManagementChannel {
         const snapshot = await this.options.snapshot();
         return {
             t: 'heartbeat', seq, sentAtEpochMs, clientVersion: CLIENT_VERSION,
+            ...(this.options.playgroundCwd ? { playgroundCwd: this.options.playgroundCwd } : {}),
             channels: {
                 MANAGEMENT: snapshot.channels.management,
                 COMPUTER: snapshot.channels.computer,
@@ -195,6 +270,7 @@ export class ManagementChannel {
                 ? { metrics: metricsForManagementWire(this.options.metrics(), this.serverManagementWire) }
                 : {}),
             ...(snapshot.update ? { update: statusForManagementWire(snapshot.update, this.serverManagementWire) } : {}),
+            ...await keepersForManagementWire(this.options.keepers, this.serverManagementWire, this.options.keepersCapMs),
         };
     }
     async nextReady(channel) {
@@ -217,6 +293,10 @@ export class ManagementChannel {
                     void dispatchUpdateCommand(channel, frame, this.options.onUpdate, this.serverManagementWire);
                     continue;
                 }
+                if (frame.t === 'keeper_control' && this.options.onKeeperControl) {
+                    void dispatchKeeperControl(channel, frame, this.options.onKeeperControl);
+                    continue;
+                }
                 if (frame.t === 'external_agents_scan' && this.options.onExternalAgentsScan) {
                     channel.send(buildScanResultFrame(frame.commandId, await this.options.onExternalAgentsScan()));
                 }