@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/protocol/computer.js

@@ -1,9 +1,67 @@
-import { decodeChannelFrame, hasOptional, hasRequired, isBoolean, isNumber, isString, isStringArray, isStringRecord } from './common.js';
+import { validDesktopFrame } from '../desktop/protocol.js';
+import { decodeChannelFrame, hasOptional, hasRequired, isBoolean, isNumber, isObject, isString, isStringArray, isStringRecord } from './common.js';
+import { TOOL_REQUEST_BYTES, TOOL_RESULT_BYTES } from '../tools/validation.js';
+export const MAX_COMPUTER_FRAME_BYTES = 8 * 1024 * 1024;
 const DISCRIMINATORS = new Set([
+    'desktop_capability', 'desktop_open', 'desktop_opened', 'desktop_data', 'desktop_credit', 'desktop_close',
     'computer_hello', 'computer_ready', 'heartbeat', 'heartbeat_ack',
-    'exec_request', 'exec_output', 'exec_exit', 'exec_cancel',
+    'exec_request', 'exec_output', 'exec_exit', 'exec_cancel', 'tool_request', 'tool_result',
+    'exec_started', 'exec_ack', 'exec_attach', 'exec_status',
+    'file_read_request', 'file_read_result', 'file_write_request', 'file_write_result',
+    'file_ls_request', 'file_ls_result', 'file_mkdir_request', 'file_mkdir_result',
 ]);
+const fileErrorCodes = new Set([
+    'invalid_argument', 'invalid_path', 'unsupported_workstation', 'unsupported_protocol',
+    'workstation_offline', 'not_found', 'not_regular_file', 'invalid_encoding', 'line_too_long',
+    'too_large', 'conflict', 'permission_denied', 'io_error', 'outcome_unknown',
+]);
+const isNonnegativeInteger = (value) => Number.isSafeInteger(value) && value >= 0;
+const isPositiveInteger = (value) => Number.isSafeInteger(value) && value >= 1;
+/** A record offset, or -1 for "none" (exec_status / exec_ack). */
+const isOffsetOrNone = (value) => Number.isSafeInteger(value) && value >= -1;
+const EXEC_STATES = new Set(['running', 'exited', 'unknown']);
+const isSha256 = (value) => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
+const onlyKeys = (value, keys) => Object.keys(value).every(key => keys.includes(key));
+function isFileError(value) {
+    return isObject(value) && hasRequired(value, { code: isString, message: isString })
+        && fileErrorCodes.has(value.code) && onlyKeys(value, ['code', 'message']);
+}
+function isReadData(value) {
+    return isObject(value) && hasRequired(value, {
+        path: isString, content: isString, startLine: isPositiveInteger, endLine: isNonnegativeInteger,
+        truncated: isBoolean, sizeBytes: isNonnegativeInteger, sha256: isSha256,
+    }) && hasOptional(value, { nextLine: isPositiveInteger })
+        && onlyKeys(value, ['path', 'content', 'startLine', 'endLine', 'nextLine', 'truncated', 'sizeBytes', 'sha256']);
+}
+function isWriteData(value) {
+    return isObject(value) && hasRequired(value, { path: isString, sizeBytes: isNonnegativeInteger, sha256: isSha256, created: isBoolean })
+        && onlyKeys(value, ['path', 'sizeBytes', 'sha256', 'created']);
+}
+const dirEntryKinds = new Set(['file', 'directory', 'symlink', 'other']);
+function isLsData(value) {
+    return isObject(value) && hasRequired(value, { path: isString, truncated: isBoolean })
+        && hasOptional(value, { nextAfter: isString })
+        && onlyKeys(value, ['path', 'entries', 'truncated', 'nextAfter'])
+        && Array.isArray(value.entries)
+        && value.entries.every((entry) => isObject(entry) && hasRequired(entry, { name: isString, kind: isString })
+            && dirEntryKinds.has(entry.kind)
+            && hasOptional(entry, { sizeBytes: isNonnegativeInteger })
+            && onlyKeys(entry, ['name', 'kind', 'sizeBytes']));
+}
+function isMkdirData(value) {
+    return isObject(value) && hasRequired(value, { path: isString, created: isBoolean })
+        && onlyKeys(value, ['path', 'created']);
+}
+function isFileResult(value, validData) {
+    if (!hasRequired(value, { id: isString }) || !onlyKeys(value, ['t', 'id', 'data', 'error']))
+        return false;
+    const hasData = Object.hasOwn(value, 'data');
+    const hasError = Object.hasOwn(value, 'error');
+    return hasData !== hasError && (hasData ? validData(value.data) : isFileError(value.error));
+}
 function isComputerFrame(value) {
+    if (typeof value.t === 'string' && value.t.startsWith('desktop_'))
+        return validDesktopFrame(value);
     switch (value.t) {
         case 'computer_hello': return hasRequired(value, { ticket: isString });
         case 'computer_ready': return hasRequired(value, { generation: isString, wireVersion: isNumber });
@@ -12,20 +70,62 @@ function isComputerFrame(value) {
         case 'exec_request': return hasRequired(value, {
             id: isString, command: isString, shell: isString, cwd: isString, env: isStringRecord,
             pathPrepend: isStringArray, streaming: isBoolean,
-        }) && hasOptional(value, { timeoutSeconds: isNullableNumber });
-        case 'exec_output': return hasRequired(value, { id: isString, stream: isString, chunk: isString });
+        }) && hasOptional(value, { timeoutSeconds: isNullableNumber, label: isString, jobId: isString });
+        case 'exec_started': return hasRequired(value, { id: isString, durable: isBoolean, startedAtMs: isNumber })
+            && hasOptional(value, { pid: isNonnegativeInteger });
+        case 'exec_output': return hasRequired(value, { id: isString, stream: isString, chunk: isString })
+            && hasOptional(value, { offset: isNonnegativeInteger, recvAtMs: isNumber });
+        case 'exec_ack': return hasRequired(value, { id: isString, throughOffset: isOffsetOrNone });
         case 'exec_exit': return hasRequired(value, {
             id: isString, exitCode: isNullableNumber, stdout: isString, stderr: isString,
             timedOut: isBoolean, truncated: isBoolean,
-        });
-        case 'exec_cancel': return hasRequired(value, { id: isString });
+        }) && hasOptional(value, { signal: isString, cancelled: isBoolean, gaps: isNonnegativeInteger });
+        case 'exec_attach': return hasRequired(value, { id: isString, fromOffset: isNonnegativeInteger });
+        case 'exec_status': return hasRequired(value, { id: isString, state: isString, headOffset: isOffsetOrNone, committedOffset: isOffsetOrNone })
+            && EXEC_STATES.has(value.state);
+        case 'tool_request': return hasRequired(value, { id: isString, method: isString, params: isObject })
+            && value.id.length > 0 && value.id.length <= 128
+            && value.method.length > 0 && value.method.length <= 64
+            && Buffer.byteLength(JSON.stringify(value)) <= TOOL_REQUEST_BYTES
+            && onlyKeys(value, ['t', 'id', 'method', 'params']);
+        case 'tool_result': return hasRequired(value, { id: isString, ok: isBoolean, result: isObject, error: value => value === null || isString(value) })
+            && value.id.length > 0 && value.id.length <= 128
+            && (value.ok ? value.error === null : typeof value.error === 'string' && value.error.length > 0)
+            && Buffer.byteLength(JSON.stringify(value)) <= TOOL_RESULT_BYTES
+            && onlyKeys(value, ['t', 'id', 'ok', 'result', 'error']);
+        case 'exec_cancel': return hasRequired(value, { id: isString }) && hasOptional(value, { signal: isString });
+        case 'file_read_request': return hasRequired(value, {
+            id: isString, root: isString, path: isString, startLine: isPositiveInteger, maxLines: isPositiveInteger,
+        }) && value.maxLines <= 2000 && onlyKeys(value, ['t', 'id', 'root', 'path', 'startLine', 'maxLines']);
+        case 'file_write_request': return hasRequired(value, {
+            id: isString, root: isString, path: isString, content: isString, mode: isString,
+        }) && (value.mode === 'create' || value.mode === 'replace')
+            && hasOptional(value, { expectedSha256: isSha256 })
+            && onlyKeys(value, ['t', 'id', 'root', 'path', 'content', 'mode', 'expectedSha256']);
+        case 'file_ls_request': return hasRequired(value, {
+            id: isString, root: isString, path: isString, maxEntries: isPositiveInteger,
+        }) && value.maxEntries <= 2000
+            && hasOptional(value, { startAfter: isString })
+            && onlyKeys(value, ['t', 'id', 'root', 'path', 'startAfter', 'maxEntries']);
+        case 'file_mkdir_request': return hasRequired(value, {
+            id: isString, root: isString, path: isString, parents: isBoolean,
+        }) && onlyKeys(value, ['t', 'id', 'root', 'path', 'parents']);
+        case 'file_read_result': return isFileResult(value, isReadData);
+        case 'file_write_result': return isFileResult(value, isWriteData);
+        case 'file_ls_result': return isFileResult(value, isLsData);
+        case 'file_mkdir_result': return isFileResult(value, isMkdirData);
         default: return false;
     }
 }
 function isNullableNumber(value) { return value === null || isNumber(value); }
 export function encodeComputerFrame(frame) {
-    return JSON.stringify(frame);
+    const encoded = JSON.stringify(frame);
+    if (Buffer.byteLength(encoded, 'utf8') > MAX_COMPUTER_FRAME_BYTES)
+        throw new TypeError('Computer frame too large');
+    return encoded;
 }
 export function decodeComputerFrame(text) {
+    if (Buffer.byteLength(text, 'utf8') > MAX_COMPUTER_FRAME_BYTES)
+        throw new TypeError('Computer frame too large');
     return decodeChannelFrame(text, DISCRIMINATORS, isComputerFrame);
 }

package/dist/workstation/protocol/management.js

@@ -8,11 +8,20 @@ export const MANAGEMENT_WIRE_METRICS_VERSION = 4;
 export const MANAGEMENT_WIRE_PRESSURE_VERSION = 5;
 /** Replaces normalized CPU load with raw 1/5/15-minute load averages and CPU capacity. */
 export const MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION = 6;
-export const MANAGEMENT_WIRE_VERSION = MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION;
+/** Adds per-GPU utilization and GPU memory to heartbeat metrics. */
+export const MANAGEMENT_WIRE_GPU_VERSION = 7;
+/** Adds `keepers` to heartbeats and the `keeper_control` / `keeper_control_result` pair (spec §8.1, Task 26). */
+export const MANAGEMENT_WIRE_KEEPERS_VERSION = 8;
+export const MANAGEMENT_WIRE_VERSION = MANAGEMENT_WIRE_KEEPERS_VERSION;
+/** Bounds of one heartbeat's `keepers` (spec §8.1). */
+export const KEEPER_STATUS_MAX_ITEMS = 32;
+export const KEEPER_LABEL_MAX_CHARS = 64;
+export const KEEPER_STATUS_MAX_ENTRIES = 16;
+export const KEEPER_AFFECTED_MAX_ITEMS = 256;
 const DISCRIMINATORS = new Set([
     'management_hello', 'management_ready', 'heartbeat', 'heartbeat_ack',
     'channel_ticket_request', 'channel_ticket', 'client_update', 'client_update_status',
-    'external_agents_scan', 'external_agents_scan_result',
+    'external_agents_scan', 'external_agents_scan_result', 'keeper_control', 'keeper_control_result',
 ]);
 const CHANNEL_KINDS = new Set(['MANAGEMENT', 'COMPUTER', 'AGENT']);
 const CHANNEL_STATES = new Set(['DISCONNECTED', 'CONNECTING', 'CONNECTED', 'RECONNECTING']);
@@ -63,6 +72,15 @@ function isStoragePoolMetrics(value) {
         availableBytes: isNumber,
     });
 }
+function isGpuMetrics(value) {
+    return isObject(value) && hasRequired(value, { id: isString, name: isString })
+        && hasOptional(value, {
+            utilization: isNullable(isNumber),
+            memoryTotalBytes: isNullable(isNumber),
+            memoryUsedBytes: isNullable(isNumber),
+            coreCount: isNullable(isNumber),
+        });
+}
 function isWorkstationMetrics(value) {
     return isObject(value) && hasRequired(value, {
         cpuUtilization: isNullable(isNumber),
@@ -76,8 +94,31 @@ function isWorkstationMetrics(value) {
         cpuLoad15: isNullable(isNumber),
         cpuLogicalCount: isNullable(isNumber),
         memoryPressure: isNullable(isNumber),
+        gpus: isNullable((gpus) => Array.isArray(gpus) && gpus.every(isGpuMetrics)),
     });
 }
+const KEEPER_KINDS = new Set(['terminal', 'acp']);
+const KEEPER_STATES = new Set(['running', 'starting', 'stopped', 'unavailable']);
+const KEEPER_REPLACEMENTS = new Set(['none', 'available', 'required', 'mandatory']);
+const KEEPER_ITEM_TYPES = new Set(['pty', 'exec', 'session']);
+const KEEPER_ACTIONS = new Set(['replace-when-idle', 'replace-now', 'cancel']);
+const oneOf = (set) => (value) => typeof value === 'string' && set.has(value);
+const isPending = (value) => value === null || value === 'when-idle';
+function isKeeperItem(value) {
+    return isObject(value) && hasRequired(value, { type: oneOf(KEEPER_ITEM_TYPES), id: isString, label: isString, state: isString, sinceEpochMs: isNumber })
+        && hasOptional(value, { jobId: isString });
+}
+function isKeeperStatus(value) {
+    return isObject(value) && hasRequired(value, {
+        kind: oneOf(KEEPER_KINDS), gen: isString, state: oneOf(KEEPER_STATES), protocolVersion: isNumber, buildVersion: isString,
+        replacement: oneOf(KEEPER_REPLACEMENTS),
+        metrics: (metrics) => isObject(metrics) && Object.values(metrics).every(isNumber),
+        items: (items) => Array.isArray(items) && items.length <= KEEPER_STATUS_MAX_ITEMS && items.every(isKeeperItem),
+    }) && hasOptional(value, { legacy: isBoolean, pending: isPending });
+}
+function isKeeperAffected(value) {
+    return isObject(value) && hasRequired(value, { type: oneOf(KEEPER_ITEM_TYPES), id: isString, label: isString, gen: isString });
+}
 function isManagementFrame(value) {
     switch (value.t) {
         case 'management_hello': return hasRequired(value, {
@@ -93,10 +134,12 @@ function isManagementFrame(value) {
             channels: (channels) => isObject(channels) && Object.entries(channels).every(([kind, state]) => CHANNEL_KINDS.has(kind) && isChannelState(state)),
             activeShellTasks: isNumber, activeAgentTasks: isNumber,
         }) && hasOptional(value, {
+            playgroundCwd: isString,
             protocols: (protocols) => isProtocolRangeMap(protocols, false),
             os: isNullable(isOsInfo),
             update: isNullable(isUpdateStatus),
             metrics: isNullable(isWorkstationMetrics),
+            keepers: isNullable((keepers) => Array.isArray(keepers) && keepers.every(isKeeperStatus)),
         });
         case 'heartbeat_ack': return hasRequired(value, { seq: isNumber });
         case 'channel_ticket_request': return hasRequired(value, { channel: isChannelKind });
@@ -105,6 +148,11 @@ function isManagementFrame(value) {
         case 'client_update_status': return hasRequired(value, { status: isUpdateStatus });
         case 'external_agents_scan': return hasRequired(value, { commandId: isString });
         case 'external_agents_scan_result': return hasRequired(value, { commandId: isString, bridges: isBridgeInfoArray });
+        case 'keeper_control': return hasRequired(value, { commandId: isString, kind: oneOf(KEEPER_KINDS), action: oneOf(KEEPER_ACTIONS) });
+        case 'keeper_control_result': return hasRequired(value, {
+            commandId: isString, kind: oneOf(KEEPER_KINDS), action: oneOf(KEEPER_ACTIONS), ok: isBoolean,
+            affected: (affected) => Array.isArray(affected) && affected.every(isKeeperAffected),
+        }) && hasOptional(value, { pending: isPending, error: isString, affectedIncomplete: (flag) => flag === true });
         default: return false;
     }
 }

package/dist/workstation/qoderAdapter/backgroundProcess.js

@@ -0,0 +1,118 @@
+/** Native Qoder does not forward background child SDK messages through ACP. Read only the
+ * exact transcript named by a validated root launch receipt; never scan or infer ownership.
+ *
+ * Each accepted row's derived events go to `onRow` (with the row's `uuid`) when it is given — the
+ * side-file reader records them as one `child` fact (`backgroundTerminalFold.ts`) — and otherwise one
+ * by one to `emit`. */
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const id = (value) => typeof value === 'string' && /^[a-zA-Z0-9_-]{1,160}$/.test(value);
+const LIMIT = 2 * 1024 * 1024;
+export class BackgroundProcess {
+    options;
+    offset = 0;
+    tail = Buffer.alloc(0);
+    skipLine = false;
+    seen = new Set();
+    tools = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async poll() {
+        const file = await open(this.options.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile())
+                return true;
+            if (stat.size < this.offset) {
+                this.offset = 0;
+                this.tail = Buffer.alloc(0);
+                this.skipLine = false;
+            }
+            const end = Math.min(stat.size, this.offset + 4 * 1024 * 1024);
+            while (this.offset < end) {
+                const chunk = Buffer.alloc(Math.min(64 * 1024, end - this.offset));
+                const { bytesRead } = await file.read(chunk, 0, chunk.length, this.offset);
+                if (!bytesRead)
+                    break;
+                this.offset += bytesRead;
+                this.consumeBytes(chunk.subarray(0, bytesRead));
+            }
+            return this.offset >= stat.size;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    consumeBytes(bytes) {
+        let start = 0;
+        for (let end = bytes.indexOf(10); end >= 0; end = bytes.indexOf(10, start)) {
+            const part = bytes.subarray(start, end);
+            if (!this.skipLine && this.tail.length + part.length <= LIMIT) {
+                try {
+                    this.consume(object(JSON.parse(Buffer.concat([this.tail, part]).toString('utf8'))));
+                }
+                catch { /* not evidence */ }
+            }
+            this.tail = Buffer.alloc(0);
+            this.skipLine = false;
+            start = end + 1;
+        }
+        const part = bytes.subarray(start);
+        if (!this.skipLine && this.tail.length + part.length <= LIMIT)
+            this.tail = Buffer.concat([this.tail, part]);
+        else {
+            this.tail = Buffer.alloc(0);
+            this.skipLine = true;
+        }
+    }
+    consume(row) {
+        const o = this.options;
+        if (row.sessionId !== o.sessionId || row.cwd !== o.cwd || row.agentId !== o.agentId ||
+            row.parent_tool_use_id !== o.parentToolUseId || row.isSidechain !== true || row.version !== '1.1.61' ||
+            !id(row.uuid) || this.seen.has(row.uuid) || this.seen.size >= 4096)
+            return;
+        this.seen.add(row.uuid);
+        const content = object(row.message).content;
+        if (!Array.isArray(content))
+            return;
+        const events = [];
+        for (const block of content.map(object)) {
+            if (row.type === 'assistant' && block.type === 'tool_use' && id(block.id) && typeof block.name === 'string') {
+                if (this.tools.has(block.id) || this.tools.size >= 4096)
+                    continue;
+                const input = object(block.input);
+                this.tools.set(block.id, { name: block.name, input });
+                this.derive(events, 'tool_call', { toolCallId: block.id, name: block.name, title: block.name,
+                    kind: block.name === 'Read' ? 'read' : block.name === 'Bash' ? 'execute' : block.name === 'Agent' ? 'think' : 'other',
+                    rawInput: input, status: 'pending' }, block.name);
+            }
+            else if (row.type === 'user' && block.type === 'tool_result' && id(block.tool_use_id)) {
+                const tool = this.tools.get(block.tool_use_id);
+                if (!tool)
+                    continue;
+                const raw = row.toolUseResult ?? block.content;
+                const text = typeof block.content === 'string' ? block.content : JSON.stringify(block.content ?? '');
+                this.derive(events, 'tool_call_update', { toolCallId: block.tool_use_id, name: tool.name,
+                    status: block.is_error === true ? 'failed' : 'completed', rawOutput: raw,
+                    content: [{ type: 'content', content: { type: 'text', text } }] }, tool.name);
+            }
+            else if (row.type === 'assistant' && ((block.type === 'text' && typeof block.text === 'string') ||
+                (block.type === 'thinking' && typeof block.thinking === 'string'))) {
+                this.derive(events, block.type === 'text' ? 'agent_message_chunk' : 'agent_thought_chunk', { content: { type: 'text', text: block.type === 'text' ? block.text : block.thinking } });
+            }
+        }
+        if (this.options.onRow) {
+            if (events.length > 0)
+                this.options.onRow(row.uuid, events);
+        }
+        else
+            for (const event of events)
+                this.options.emit(event);
+    }
+    derive(events, eventName, payload, toolName) {
+        events.push({ eventName, payload: { ...payload, _meta: { qoder: { version: 1, source: 'correction',
+                        parentToolUseId: this.options.parentToolUseId, route: 'child', ...(toolName ? { toolName } : {}) } } } });
+    }
+}

package/dist/workstation/qoderAdapter/backgroundTerminal.js

@@ -0,0 +1,193 @@
+/** Qoder 1.1.61 drops native background task notifications from both live ACP and session/load.
+ * This read-only compatibility boundary repairs only a known root Agent tool, never a session.
+ * Lifecycle/removal contract: axom-patch/cli/qoder-background-terminal.md.
+ *
+ * The impure half (Task 17c): this file reads the side files; everything the repair decides is the
+ * pure fold in `backgroundTerminalFold.ts`. {@link BackgroundSideNotes} is the daemon side of the deterministic
+ * processor: a poll returns the facts as `qoder_side` note payloads for the raw log; the processor folds them only when it
+ * reads those notes, so a replay never touches the files. (The old live path's in-process driver, `BackgroundTerminalRepair`,
+ * was deleted with that path in Task 29.)
+ */
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { BackgroundProcess } from './backgroundProcess.js';
+import { address, MAX_TASKS, object, rootRowFacts, sideNotes, } from './backgroundTerminalFold.js';
+export { TerminalRepairFold, newTerminalRepairData, sideNotes } from './backgroundTerminalFold.js';
+const CHUNK = 64 * 1024;
+const MAX_LINE = 2 * 1024 * 1024;
+const MAX_POLL = 4 * 1024 * 1024;
+export function nativeTerminalHistoryPath(identity, sessionId, cwd, historyHome) {
+    if (identity?.name !== 'qoder-cli' || identity.version !== '1.1.61' ||
+        !address(sessionId) || !isAbsolute(cwd) || !isAbsolute(historyHome))
+        return;
+    // Certified ~/.qoder/projects layout. Even a colliding directory name cannot cross session/cwd
+    // identity: every accepted row is checked again against the exact native session and directory.
+    return join(historyHome, '.qoder', 'projects', resolve(cwd).replace(/[^a-zA-Z0-9]/g, '-'), sessionId + '.jsonl');
+}
+/**
+ * Reads the root transcript and the background children's transcripts incrementally (≤ 4 MiB per
+ * poll and file, lines ≤ 2 MiB, `O_NOFOLLOW`, never written) and hands each derived {@link SideFact}
+ * to the sink, in transcript order: root facts, then each followed child's rows and catch-up status,
+ * then `poll_end` — only when the root read completed. Its offsets are its own (not checkpointed): a
+ * new reader starts at 0 and the fold drops what it already has.
+ */
+export class BackgroundSideReader {
+    options;
+    launches = new Map();
+    processes = new Map();
+    offset = 0;
+    fileIdentity = '';
+    pendingLine = Buffer.alloc(0);
+    skipLine = false;
+    closed = false;
+    warned = false;
+    restoring;
+    constructor(options) {
+        this.options = options;
+        this.restoring = options.restoreCalls === true;
+    }
+    /** One poll. Never rejects: a missing, replaced or unreadable file is not evidence. */
+    async read(demand, sink) {
+        if (this.closed || (!this.restoring && !demand.active()))
+            return;
+        try {
+            await this.readIncrement(demand, sink);
+        }
+        catch (error) {
+            const code = object(error).code;
+            if (!['ENOENT', 'ELOOP', 'ENOTDIR', 'EACCES'].includes(String(code)) && !this.warned) {
+                this.warned = true;
+                console.warn('[acp:qoder] background terminal repair unavailable; retaining native ACP state');
+            }
+        }
+    }
+    close() {
+        this.closed = true;
+        this.launches.clear();
+        this.processes.clear();
+        this.pendingLine = Buffer.alloc(0);
+    }
+    async readIncrement(demand, sink) {
+        // O_NOFOLLOW avoids importing a transcript through a replaced symlink. File is never written.
+        const file = await open(this.options.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || this.closed)
+                return;
+            const identity = `${stat.dev}:${stat.ino}`;
+            if (identity !== this.fileIdentity || stat.size < this.offset) {
+                this.offset = 0;
+                this.pendingLine = Buffer.alloc(0);
+                this.skipLine = false;
+                this.fileIdentity = identity;
+            }
+            const end = Math.min(stat.size, this.offset + MAX_POLL);
+            const chunk = Buffer.alloc(CHUNK);
+            while (!this.closed && this.offset < end) {
+                const { bytesRead } = await file.read(chunk, 0, Math.min(CHUNK, end - this.offset), this.offset);
+                if (!bytesRead)
+                    break;
+                this.offset += bytesRead;
+                this.lines(chunk.subarray(0, bytesRead), sink);
+            }
+            if (this.offset >= stat.size)
+                this.restoring = false;
+            if (!this.closed) {
+                await this.pollProcesses(demand, sink);
+                if (!this.closed)
+                    sink({ kind: 'poll_end' });
+            }
+        }
+        finally {
+            await file.close();
+        }
+    }
+    lines(chunk, sink) {
+        let start = 0;
+        for (let end = chunk.indexOf(10); end !== -1; end = chunk.indexOf(10, start)) {
+            if (!this.skipLine && this.pendingLine.length + end - start <= MAX_LINE) {
+                const line = Buffer.concat([this.pendingLine, chunk.subarray(start, end)]).toString('utf8');
+                let row;
+                try {
+                    row = object(JSON.parse(line));
+                }
+                catch { /* partial/corrupt non-evidence */ }
+                if (row)
+                    this.consume(row, sink);
+            }
+            this.pendingLine = Buffer.alloc(0);
+            this.skipLine = false;
+            start = end + 1;
+        }
+        const tail = chunk.subarray(start);
+        if (!this.skipLine && this.pendingLine.length + tail.length <= MAX_LINE) {
+            this.pendingLine = Buffer.concat([this.pendingLine, tail]);
+        }
+        else {
+            this.pendingLine = Buffer.alloc(0);
+            this.skipLine = true;
+        }
+    }
+    consume(row, sink) {
+        const { nativeSessionId, cwd } = this.options;
+        for (const fact of rootRowFacts(row, { nativeSessionId, cwd, restoreCalls: this.options.restoreCalls === true })) {
+            // The reader's own copy of the receipts (same rule as the fold's): which child transcripts exist.
+            if (fact.kind === 'launch' && fact.agentId && this.launches.size < MAX_TASKS && !this.launches.has(fact.toolUseId)) {
+                this.launches.set(fact.toolUseId, fact.agentId);
+            }
+            sink(fact);
+        }
+    }
+    async pollProcesses(demand, sink) {
+        for (const [id, agentId] of this.launches) {
+            if (this.closed || !demand.wantsProcess(id))
+                continue;
+            let process = this.processes.get(id);
+            if (!process) {
+                process = new BackgroundProcess({
+                    path: join(dirname(this.options.path), this.options.nativeSessionId, 'subagents', `agent-${agentId}.jsonl`),
+                    sessionId: this.options.nativeSessionId, cwd: this.options.cwd, agentId, parentToolUseId: id,
+                    emit: () => { },
+                    onRow: (uuid, events) => { if (!this.closed)
+                        sink({ kind: 'child', toolUseId: id, uuid, events }); },
+                });
+                this.processes.set(id, process);
+            }
+            let caughtUp;
+            try {
+                caughtUp = await process.poll();
+            }
+            catch {
+                caughtUp = true; /* missing/corrupt transcript is not execution evidence */
+            }
+            sink({ kind: 'child_status', toolUseId: id, caughtUp });
+        }
+    }
+}
+/**
+ * The daemon side of the processor (T19 runs it on its own timer, for a session whose processor
+ * folded a `qoder_terminal_repair` note): one {@link poll} reads what is new and returns the note
+ * payloads to append to the raw log, in order. `demand` is asked of the processor's current state
+ * (`acp/processor/sideChannel.ts` `sideDemand`); what it answered is recorded only through the facts,
+ * so the processor's fold never depends on when the daemon polled.
+ */
+export class BackgroundSideNotes {
+    reader;
+    /** Facts over `MAX_SIDE_FACT_BYTES` that could not be recorded (diagnostics). */
+    droppedFacts = 0;
+    constructor(options) {
+        this.reader = new BackgroundSideReader(options);
+    }
+    async poll(demand) {
+        const notes = [];
+        await this.reader.read(demand, (fact) => {
+            const encoded = sideNotes(fact);
+            if (encoded.length === 0)
+                this.droppedFacts += 1;
+            notes.push(...encoded);
+        });
+        return notes;
+    }
+    close() { this.reader.close(); }
+}