@platless/axom-cli 0.1.0 → 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,14 +73,20 @@ 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() });
                 }
                 continue;
             }
-            await dispatchAgentFrame(agents, frame);
+            // Start handlers in wire order, but keep receiving while their RPCs / disk I/O wait.
+            // A probe can take longer than an open's 30s or a config change's 10s deadline; awaiting it
+            // here makes every unrelated session time out while heartbeats still report a healthy socket.
+            // The manager owns open deduplication, close-during-open tombstones and per-session journal
+            // ordering. Answers, interrupts and closes must also reach it while an earlier RPC is pending.
+            // dispatchAgentFrame catches rejections, including for these detached handlers.
+            void dispatchAgentFrame(agents, frame);
         }
     }
     catch (error) {

package/dist/workstation/channels/computer.js

@@ -1,20 +1,35 @@
+import { DesktopBridge } from '../desktop/bridge.js';
+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 { 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()) {
+export async function dispatchComputerFrames(messages, send, execute, tasks = new TaskRegistry(), files = {}, tools, desktop, durable = {}) {
     const active = new Map();
-    const safeSend = (frame) => { try {
+    const activeTools = new Set();
+    let open = true;
+    let wireVersion = 1;
+    const safeSend = (frame) => { if (!open)
+        return; try {
         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 });
@@ -25,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) => {
@@ -33,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);
                     }
                 });
@@ -51,15 +77,175 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
             }
         })();
     };
+    const runFile = (request) => {
+        // Read/write landed in wire v2; directory listing and creation arrived with v3.
+        const minWireVersion = request.t === 'file_ls_request' || request.t === 'file_mkdir_request' ? 3 : 2;
+        const fail = (code, message) => {
+            if (request.t === 'file_read_request')
+                safeSend({ t: 'file_read_result', id: request.id, error: { code, message } });
+            else if (request.t === 'file_write_request')
+                safeSend({ t: 'file_write_result', id: request.id, error: { code, message } });
+            else if (request.t === 'file_ls_request')
+                safeSend({ t: 'file_ls_result', id: request.id, error: { code, message } });
+            else
+                safeSend({ t: 'file_mkdir_result', id: request.id, error: { code, message } });
+        };
+        if (wireVersion < minWireVersion) {
+            fail('unsupported_protocol', `Computer file operations require wire v${minWireVersion}`);
+            return;
+        }
+        if (!tasks.accepting) {
+            fail('workstation_offline', 'Workstation is not accepting new work');
+            return;
+        }
+        active.get(request.id)?.abort();
+        const controller = new AbortController();
+        active.set(request.id, controller);
+        void (async () => {
+            try {
+                const data = await tasks.withShellTask(async (shutdown) => {
+                    const onShutdown = () => controller.abort();
+                    if (shutdown.aborted)
+                        controller.abort();
+                    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 ?? 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 ?? 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 ?? requestRootFileExecutors.listDir)({ root: request.root, path: request.path, startAfter: request.startAfter, maxEntries: request.maxEntries }, controller.signal);
+                        }
+                        return await (files.createDir ?? requestRootFileExecutors.createDir)({ root: request.root, path: request.path, parents: request.parents }, controller.signal);
+                    }
+                    finally {
+                        shutdown.removeEventListener('abort', onShutdown);
+                    }
+                });
+                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')
+                    safeSend({ t: 'file_write_result', id: request.id, data: data });
+                else if (request.t === 'file_ls_request')
+                    safeSend({ t: 'file_ls_result', id: request.id, data: data });
+                else
+                    safeSend({ t: 'file_mkdir_result', id: request.id, data: data });
+            }
+            catch (error) {
+                if (active.get(request.id) !== controller)
+                    return;
+                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'
+                        : request.t === 'file_mkdir_request' ? 'Directory creation outcome is unknown after cancellation'
+                            : 'Read was cancelled');
+                }
+                else
+                    fail(mapped.code, mapped.message);
+            }
+            finally {
+                if (active.get(request.id) === controller)
+                    active.delete(request.id);
+            }
+        })();
+    };
+    const runTool = (request) => {
+        const fail = (error) => safeSend({ t: 'tool_result', id: request.id, ok: false, result: {}, error: (error || 'Workstation tool failed').slice(0, 1024) });
+        if (wireVersion < 3) {
+            fail('Workstation tools require computer wire v3');
+            return;
+        }
+        // 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 are not configured');
+            return;
+        }
+        if (activeTools.has(request.id)) {
+            fail('Duplicate tool request id');
+            return;
+        }
+        if (activeTools.size >= 16) {
+            fail('Too many simultaneous tool requests');
+            return;
+        }
+        activeTools.add(request.id);
+        void (async () => {
+            let timer;
+            try {
+                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 });
+            }
+            catch (error) {
+                fail(error instanceof Error ? error.message : 'Workstation tool failed');
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                activeTools.delete(request.id);
+            }
+        })();
+    };
     try {
         for await (const frame of messages) {
-            if (frame.t === 'exec_request')
-                run(frame);
-            else if (frame.t === 'exec_cancel')
+            if (frame.t.startsWith('desktop_'))
+                desktop?.onFrame(frame);
+            else if (frame.t === 'tool_request')
+                runTool(frame);
+            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);
+            }
+            else if (frame.t === 'file_read_request' || frame.t === 'file_write_request' || frame.t === 'file_ls_request' || frame.t === 'file_mkdir_request')
+                runFile(frame);
         }
     }
     finally {
+        open = false;
+        desktop?.close();
+        execWire.close();
         for (const controller of active.values())
             controller.abort();
     }
@@ -68,9 +254,16 @@ export async function dispatchComputerFrames(messages, send, execute, tasks = ne
 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();
+        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) {
@@ -86,6 +279,9 @@ export class ComputerChannel {
         return { closed: channel.closed, close: () => channel.close() };
     }
     async dispatch(channel) {
-        await dispatchComputerFrames(channel.messages, (frame) => channel.send(frame), this.options.runExec ?? runExec, this.tasks);
+        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();
+    }
+}