@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/desktop/bridge.js

@@ -0,0 +1,212 @@
+import net from 'node:net';
+import { connectFocusedCdp, insertFocusedText } from './focused-text.js';
+import { WebSocket } from 'ws';
+import { browserCapability, resolveBrowserBinding } from './binding.js';
+import { DesktopFlow } from './flow-control.js';
+import { DESKTOP_LEASE_MS, DESKTOP_MAX_STREAMS, DESKTOP_QUEUE_BYTES, DESKTOP_WINDOW_BYTES } from './protocol.js';
+/** Bridges only explicitly configured live providers; owns no browser or profile lifecycle. */
+export class DesktopBridge {
+    send;
+    bufferedAmount;
+    streams = new Map();
+    generation = '';
+    wireVersion = 1;
+    ended = false;
+    timer;
+    binding;
+    constructor(binding, send, bufferedAmount = () => 0) {
+        this.send = send;
+        this.bufferedAmount = bufferedAmount;
+        this.binding = resolveBrowserBinding(binding, {});
+        this.timer = setInterval(() => { for (const s of this.streams.values())
+            if (Date.now() - s.lease >= DESKTOP_LEASE_MS)
+                this.finish(s, 'lease_expired'); }, 1000);
+        this.timer.unref();
+    }
+    ready(generation, wireVersion) {
+        for (const s of this.streams.values())
+            this.finish(s, 'replaced');
+        this.generation = generation;
+        this.wireVersion = wireVersion;
+        if (wireVersion >= 4)
+            this.send({ t: 'desktop_capability', ...browserCapability(this.binding) });
+    }
+    async insertText(params) {
+        if (!this.binding?.cdpEndpoint)
+            throw Error('Chinese assistance unavailable: CDP is not configured');
+        const stream = this.streams.get(String(params.streamId));
+        const active = () => !this.ended && !!stream && this.streams.get(stream.id) === stream && stream.opened &&
+            this.binding?.bindingId === params.bindingId && stream.generation === params.generation &&
+            this.generation === params.generation && Date.now() - stream.lease < DESKTOP_LEASE_MS;
+        return insertFocusedText(params, active, () => connectFocusedCdp(this.binding.cdpEndpoint));
+    }
+    onFrame(frame) {
+        if (this.ended)
+            return;
+        if (frame.t === 'desktop_open') {
+            this.open(frame);
+            return;
+        }
+        if (frame.t === 'desktop_capability')
+            return;
+        const s = this.streams.get(frame.streamId);
+        if (!s)
+            return;
+        if (frame.generation !== s.generation || frame.generation !== this.generation) {
+            this.finish(s, 'invalid_frame');
+            return;
+        }
+        try {
+            if (frame.t === 'desktop_close') {
+                this.finish(s, frame.code, false);
+                return;
+            }
+            if (frame.t === 'desktop_credit') {
+                s.flow.credit(frame.bytes);
+                s.lease = Date.now();
+                this.schedule(s);
+                return;
+            }
+            if (frame.t === 'desktop_data') {
+                if (!s.opened)
+                    throw new Error('Desktop not opened');
+                const bytes = s.flow.receive(frame.seq, frame.data);
+                const consumed = (error) => {
+                    if (!this.streams.has(s.id))
+                        return;
+                    if (error) {
+                        this.finish(s, 'io_error');
+                        return;
+                    }
+                    try {
+                        s.flow.consumed(bytes.length);
+                        this.send({ t: 'desktop_credit', streamId: s.id, generation: s.generation, bytes: bytes.length });
+                    }
+                    catch {
+                        this.finish(s, 'io_error');
+                    }
+                };
+                if (s.socket instanceof net.Socket)
+                    s.socket.write(bytes, consumed);
+                else {
+                    if (s.socket.bufferedAmount + bytes.length > DESKTOP_QUEUE_BYTES) {
+                        this.finish(s, 'overflow');
+                        return;
+                    }
+                    s.socket.send(bytes, { binary: true }, consumed);
+                }
+            }
+            else
+                this.finish(s, 'invalid_frame');
+        }
+        catch {
+            this.finish(s, 'invalid_frame');
+        }
+    }
+    close() { if (this.ended)
+        return; this.ended = true; clearInterval(this.timer); for (const s of this.streams.values())
+        this.finish(s, 'offline', false); }
+    open(frame) {
+        const refuse = (code) => this.send({ t: 'desktop_close', streamId: frame.streamId, generation: frame.generation, code });
+        if (this.wireVersion < 4) {
+            refuse('unsupported_protocol');
+            return;
+        }
+        if (frame.generation !== this.generation) {
+            refuse('invalid_frame');
+            return;
+        }
+        if (!this.binding || frame.bindingId !== this.binding.bindingId) {
+            refuse('unconfigured');
+            return;
+        }
+        if (this.streams.has(frame.streamId) || this.streams.size >= DESKTOP_MAX_STREAMS || this.streams.size > 0) {
+            refuse('busy');
+            return;
+        }
+        const url = new URL(this.binding.vncEndpoint);
+        const socket = url.protocol === 'tcp:' ? net.createConnection({ host: url.hostname.replace(/^\[|\]$/g, ''), port: Number(url.port) }) : new WebSocket(url, { maxPayload: DESKTOP_QUEUE_BYTES, perMessageDeflate: false });
+        const s = { id: frame.streamId, generation: frame.generation, flow: new DesktopFlow(), socket, opened: false, lease: Date.now(), connectTimer: setTimeout(() => this.finish(s, 'connect_timeout'), 10_000) };
+        this.streams.set(s.id, s);
+        const opened = () => {
+            if (!this.streams.has(s.id))
+                return;
+            clearTimeout(s.connectTimer);
+            s.opened = true;
+            try {
+                this.send({ t: 'desktop_opened', streamId: s.id, bindingId: frame.bindingId, generation: s.generation });
+            }
+            catch {
+                this.finish(s, 'io_error');
+            }
+        };
+        const data = (bytes) => {
+            if (!this.streams.has(s.id))
+                return;
+            try {
+                s.flow.enqueue(bytes);
+                socket.pause();
+                this.schedule(s);
+            }
+            catch {
+                this.finish(s, 'overflow');
+            }
+        };
+        if (socket instanceof net.Socket) {
+            socket.once('connect', opened);
+            socket.on('data', data);
+        }
+        else {
+            socket.once('open', opened);
+            socket.on('message', (raw, binary) => { if (!binary) {
+                this.finish(s, 'invalid_frame');
+                return;
+            } data(Array.isArray(raw) ? Buffer.concat(raw) : Buffer.from(raw)); });
+        }
+        socket.once('error', () => this.finish(s, s.opened ? 'io_error' : 'connect_failed'));
+        socket.once('close', () => this.finish(s, 'io_error'));
+    }
+    schedule(s) {
+        if (s.scheduled || !this.streams.has(s.id))
+            return;
+        // Yield after every raw block so shell/file results and channel heartbeats can run.
+        s.scheduled = setTimeout(() => {
+            s.scheduled = undefined;
+            if (!this.streams.has(s.id))
+                return;
+            try {
+                if (this.bufferedAmount() > DESKTOP_QUEUE_BYTES) {
+                    this.finish(s, 'overflow');
+                    return;
+                }
+                let blocks = 0;
+                s.flow.flush((seq, data) => this.send({ t: 'desktop_data', streamId: s.id, generation: s.generation, seq, data }), () => this.bufferedAmount() < DESKTOP_WINDOW_BYTES && blocks++ === 0);
+                if (s.flow.queuedBytes) {
+                    if (s.flow.canSend)
+                        this.schedule(s);
+                }
+                else if (s.flow.canSend)
+                    s.socket.resume();
+            }
+            catch {
+                this.finish(s, 'io_error');
+            }
+        }, 1);
+    }
+    finish(s, code, notify = true) {
+        if (!this.streams.delete(s.id))
+            return;
+        clearTimeout(s.connectTimer);
+        if (s.scheduled)
+            clearTimeout(s.scheduled);
+        if (s.socket instanceof net.Socket)
+            s.socket.destroy();
+        else
+            s.socket.terminate();
+        if (notify && !this.ended)
+            try {
+                this.send({ t: 'desktop_close', streamId: s.id, generation: s.generation, code });
+            }
+            catch { /* channel closed */ }
+    }
+}

package/dist/workstation/desktop/flow-control.js

@@ -0,0 +1,52 @@
+import { desktopBytes, DESKTOP_BLOCK_BYTES, DESKTOP_WINDOW_BYTES, DESKTOP_QUEUE_BYTES } from './protocol.js';
+export { DESKTOP_WINDOW_BYTES, DESKTOP_QUEUE_BYTES } from './protocol.js';
+/** Independent raw-byte windows; byte queues never discard or replay an RFB block. */
+export class DesktopFlow {
+    queue = [];
+    queuedBytes = 0;
+    sendAvailable = DESKTOP_WINDOW_BYTES;
+    receiveAvailable = DESKTOP_WINDOW_BYTES;
+    sendSeq = 0;
+    receiveSeq = 0;
+    get canSend() { return this.sendAvailable > 0; }
+    enqueue(bytes) {
+        if (this.queuedBytes + bytes.length > DESKTOP_QUEUE_BYTES || this.queue.length + Math.ceil(bytes.length / DESKTOP_BLOCK_BYTES) > 1024)
+            throw new Error('Desktop queue overflow');
+        for (let i = 0; i < bytes.length; i += DESKTOP_BLOCK_BYTES)
+            this.queue.push(Buffer.from(bytes.subarray(i, i + DESKTOP_BLOCK_BYTES)));
+        this.queuedBytes += bytes.length;
+    }
+    flush(send, writable = () => true) {
+        // One block per event-loop turn at the adapter keeps tool/control frames schedulable.
+        while (this.queue.length && this.sendAvailable && writable()) {
+            const head = this.queue[0];
+            const size = Math.min(head.length, this.sendAvailable);
+            const bytes = head.subarray(0, size);
+            if (size === head.length)
+                this.queue.shift();
+            else
+                this.queue[0] = head.subarray(size);
+            this.queuedBytes -= size;
+            this.sendAvailable -= size;
+            send(this.sendSeq++, bytes.toString('base64'));
+        }
+    }
+    credit(bytes) {
+        if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > DESKTOP_WINDOW_BYTES - this.sendAvailable)
+            throw new Error('Invalid desktop credit');
+        this.sendAvailable += bytes;
+    }
+    receive(seq, data) {
+        const bytes = desktopBytes(data);
+        if (seq !== this.receiveSeq || !Number.isSafeInteger(seq) || bytes.length > this.receiveAvailable)
+            throw new Error('Invalid desktop sequence/window');
+        this.receiveSeq++;
+        this.receiveAvailable -= bytes.length;
+        return bytes;
+    }
+    consumed(bytes) {
+        if (!Number.isSafeInteger(bytes) || bytes <= 0 || bytes > DESKTOP_WINDOW_BYTES - this.receiveAvailable)
+            throw new Error('Invalid desktop consumption');
+        this.receiveAvailable += bytes;
+    }
+}

package/dist/workstation/desktop/focused-text.js

@@ -0,0 +1,130 @@
+import { WebSocket } from 'ws';
+import { keys, string } from '../tools/validation.js';
+// activeElement on the outer document is the iframe or shadow host, not the
+// actual input. Follow only the current focus chain; never search for another
+// editor or force focus. Opaque cross-origin/closed roots remain noneditable.
+const focusExpression = `(() => {
+  let e=document.activeElement;
+  for(let depth=0;e && depth<32;depth++) {
+    let child=e.shadowRoot?.activeElement;
+    if(!child && (e.tagName==='IFRAME' || e.tagName==='FRAME')) {
+      try { child=e.contentDocument?.activeElement; } catch {}
+    }
+    if(!child) break;
+    e=child;
+  }
+  return {focused:document.hasFocus(),editable:!!e && !e.disabled && !e.readOnly &&
+    (e.isContentEditable || e.tagName==='TEXTAREA' || e.tagName==='INPUT' && /^(text|search|email|url|tel|password|number)$/.test(e.type))};
+})()`;
+export async function connectFocusedCdp(endpoint) {
+    const response = await fetch(new URL('/json/version', endpoint), { signal: AbortSignal.timeout(1000), redirect: 'error' });
+    if (!response.ok)
+        throw Error('CDP unavailable');
+    const version = await response.json();
+    const url = new URL(version.webSocketDebuggerUrl ?? '');
+    const configured = new URL(endpoint);
+    if (!['ws:', 'wss:'].includes(url.protocol) || url.hostname !== configured.hostname || url.port !== configured.port || url.username || url.password)
+        throw Error('Invalid local CDP address');
+    const socket = new WebSocket(url, { maxPayload: 1024 * 1024, perMessageDeflate: false });
+    let counter = 0;
+    const pending = new Map();
+    const fail = () => { for (const p of pending.values()) {
+        clearTimeout(p.timer);
+        p.reject(Error('CDP unavailable'));
+    } pending.clear(); };
+    socket.on('error', fail);
+    socket.on('close', fail);
+    socket.on('message', raw => { try {
+        const value = JSON.parse(raw.toString());
+        const p = pending.get(value.id);
+        if (!p)
+            return;
+        pending.delete(value.id);
+        clearTimeout(p.timer);
+        value.error ? p.reject(Error('CDP operation refused')) : p.resolve(value.result);
+    }
+    catch {
+        socket.terminate();
+    } });
+    await new Promise((resolve, reject) => { const timer = setTimeout(() => { socket.terminate(); reject(Error('CDP unavailable')); }, 1000); socket.once('open', () => { clearTimeout(timer); resolve(); }); socket.once('error', () => { clearTimeout(timer); reject(Error('CDP unavailable')); }); });
+    function request(method, params = {}, sessionId) {
+        const id = ++counter;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { pending.delete(id); reject(Error('CDP timed out; write outcome may be unknown')); }, 1000);
+            pending.set(id, { resolve, reject, timer });
+            try {
+                socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+            }
+            catch {
+                clearTimeout(timer);
+                pending.delete(id);
+                reject(Error('CDP unavailable'));
+            }
+        });
+    }
+    const sessions = new Map();
+    return {
+        pages: async () => { const { targetInfos } = await request('Target.getTargets'); return targetInfos.filter((t) => t.type === 'page').map((t) => t.targetId); },
+        focus: async (id) => {
+            let session = sessions.get(id);
+            if (!session) {
+                session = (await request('Target.attachToTarget', { targetId: id, flatten: true })).sessionId;
+                sessions.set(id, session);
+            }
+            const r = await request('Runtime.evaluate', { expression: focusExpression, returnByValue: true }, session);
+            if (r.exceptionDetails || typeof r.result?.value?.focused !== 'boolean' || typeof r.result?.value?.editable !== 'boolean')
+                throw Error('CDP focus unavailable');
+            return r.result.value;
+        },
+        insert: (id, text) => request('Input.insertText', { text }, sessions.get(id)).then(() => { }),
+        close: () => socket.terminate(), // Closes this debugger connection only, never Browser.close.
+    };
+}
+export async function insertFocusedText(params, active, connect) {
+    keys(params, ['bindingId', 'streamId', 'generation', 'text']);
+    for (const key of ['bindingId', 'streamId', 'generation'])
+        string(params, key, 128);
+    const text = string(params, 'text', 8192);
+    if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(text) || /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(text))
+        throw Error('Invalid text');
+    const deadline = Date.now() + 6000;
+    const check = () => { if (!active() || Date.now() >= deadline)
+        throw Error('Viewer inactive, replaced or text assistance expired'); };
+    check();
+    const cdp = await connect();
+    try {
+        check();
+        const pages = await cdp.pages();
+        check();
+        if (pages.length > 64)
+            throw Error('Ambiguous focus');
+        const focused = [];
+        for (const id of pages) {
+            const state = await cdp.focus(id);
+            check();
+            if (state.focused)
+                focused.push({ id, ...state });
+        }
+        if (focused.length !== 1)
+            throw Error('Unique document focus unavailable');
+        const target = focused[0];
+        if (!target.editable)
+            throw Error('Focused element is not editable');
+        const final = await cdp.focus(target.id);
+        check();
+        if (!final.focused || !final.editable)
+            throw Error('Editable focus changed');
+        // Once insertion is enqueued, neither a missing reply nor takeover can establish nonexecution.
+        try {
+            await cdp.insert(target.id, text);
+            check();
+            return { ok: true };
+        }
+        catch (cause) {
+            throw new Error('Text outcome unknown; check remote content before sending again', { cause });
+        }
+    }
+    finally {
+        cdp.close();
+    }
+}

package/dist/workstation/desktop/protocol.js

@@ -0,0 +1,35 @@
+export const DESKTOP_BLOCK_BYTES = 64 * 1024;
+export const DESKTOP_WINDOW_BYTES = 512 * 1024;
+export const DESKTOP_QUEUE_BYTES = 4 * 1024 * 1024;
+export const DESKTOP_MAX_STREAMS = 4;
+export const DESKTOP_LEASE_MS = 45_000;
+export const DESKTOP_CLOSE_CODES = ['normal', 'unconfigured', 'busy', 'unsupported_protocol', 'invalid_frame', 'connect_failed', 'connect_timeout', 'io_error', 'overflow', 'lease_expired', 'offline', 'replaced'];
+export function desktopBytes(data) {
+    if (!data || data.length > Math.ceil(DESKTOP_BLOCK_BYTES / 3) * 4 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data))
+        throw new Error('Invalid desktop bytes');
+    const bytes = Buffer.from(data, 'base64');
+    if (bytes.length > DESKTOP_BLOCK_BYTES || bytes.toString('base64') !== data)
+        throw new Error('Invalid desktop bytes');
+    return bytes;
+}
+export function validDesktopFrame(frame) {
+    const id = (v) => typeof v === 'string' && v.length > 0 && v.length <= 128;
+    const keys = (allowed) => Object.keys(frame).every(k => allowed.includes(k));
+    if (frame.t === 'desktop_capability')
+        return keys(['t', 'bindingId', 'displayName', 'configured', 'cdp']) && typeof frame.configured === 'boolean' && typeof frame.cdp === 'boolean' && (frame.bindingId === null || id(frame.bindingId)) && (frame.displayName === null || id(frame.displayName)) && (frame.configured ? frame.bindingId !== null && frame.displayName !== null : frame.bindingId === null && frame.displayName === null && frame.cdp === false);
+    if (!id(frame.streamId) || !id(frame.generation))
+        return false;
+    switch (frame.t) {
+        case 'desktop_open':
+        case 'desktop_opened': return id(frame.bindingId) && keys(['t', 'streamId', 'generation', 'bindingId']);
+        case 'desktop_data': try {
+            return keys(['t', 'streamId', 'generation', 'seq', 'data']) && Number.isSafeInteger(frame.seq) && frame.seq >= 0 && typeof frame.data === 'string' && desktopBytes(frame.data).length > 0;
+        }
+        catch {
+            return false;
+        }
+        case 'desktop_credit': return keys(['t', 'streamId', 'generation', 'bytes']) && Number.isSafeInteger(frame.bytes) && frame.bytes >= 0 && frame.bytes <= DESKTOP_WINDOW_BYTES;
+        case 'desktop_close': return keys(['t', 'streamId', 'generation', 'code']) && DESKTOP_CLOSE_CODES.includes(frame.code);
+        default: return false;
+    }
+}

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 || '.');
+}