@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/acp/processor/session.js

@@ -0,0 +1,525 @@
+/**
+ * The session layer of the ACP processor (Task 17a): turns, interrupt, permission and elicitation
+ * cards, and the permission-origin graph — `AcpSession` + `permission.ts` + the turn half of
+ * `agentSessions.ts`, re-expressed as a synchronous fold over the raw log (spec 2026-10-11 §5.4).
+ *
+ * ## Turns
+ *
+ * - An `agent_prompt` note asks for a turn. Admission (`TaskRegistry.tryAdmitTurn`, a daemon-wide
+ *   decision) arrives **in** the note (`admitted: false`), so a refusal lands on the note's offset and
+ *   replays identically; so do the processor's own refusals (no connection, an overlapping exact
+ *   turn). Those are the three daemon-initiated `turn_done`s of `agentSessions.ts`'s `agent_prompt`
+ *   branch, with the same two frame shapes (see {@link refuseTurn} / {@link finishTurn}).
+ * - An admitted prompt becomes one `session/prompt` command. The note carries no blocks — only a
+ *   `blocksRef` the executor resolves (`DownCommand.fill`), so the blocks appear once in the log, in
+ *   that `down` record (§5.4). `platformTurnId` rides in the command's annotation and is **read back
+ *   from the `down` record** when the processor folds it: that record is what started the turn on the
+ *   agent.
+ * - A turn ends exactly on the record that settles its request — the agent's response line, a
+ *   `proc exit`, or an `agent_prompt_failed` note (the executor could not write the line). There is no
+ *   `settleUpdates` heuristic: log order is the truth (analysis B A4). One consequence, recorded
+ *   rather than hidden: an update the agent writes **after** its `session/prompt` response belongs to
+ *   whatever follows, not to the finished turn (analysis B §1.5).
+ * - Turns are matched to their response by request id, not FIFO: two overlapping prompts the agent
+ *   answers out of order keep their own results (`AcpSession.inFlightTurns` documents the swap the
+ *   FIFO rule had).
+ *
+ * ## Cards
+ *
+ * `session/request_permission` and `'form'` `elicitation/create` follow `permission.ts` step for step
+ * (the same builders and `validateWireEvent`), with ids derived from the log: a permission card is
+ * `perm:<spawnId>:<JSON agent id>` ({@link permissionRequestId}, shared with the live path), an
+ * elicitation card keeps the agent's id. A card the user has not answered stays in state with the
+ * JSON-RPC id it came on, so after a restore it is still pending under the same id
+ * ({@link pendingRequestIds}, spec §5.5.3/4) and the answer is written back on the original id.
+ *
+ * ## Task 17b
+ *
+ * `session/update` mapping and `agent_message` synthesis live in `updates.ts` (a turn's end flushes
+ * the streaming message before its own frame, and a turn's start closes a message that began
+ * outside any turn); the open session, config, steering and delegation in `control.ts`.
+ *
+ * ## Task 17c: callbacks and the adapter boundaries
+ *
+ * Every change to the pending/settled permission cards publishes the callback snapshot
+ * (`runtime.ts` `publishCallbacks`), at the points `AcpSession` does: a registration (accepted, or
+ * refused for its fields/capacity/a reused id — which also makes the snapshot incomplete), a
+ * settlement (`answered` by a note, `canceled` by the agent or for want of a callback context), a
+ * drain (interrupt, an interrupted turn, the connection closing — incomplete from then on). A Qoder
+ * SDK adapter's root card carries its `callbackContext` (`qoderAdapter/callbackContext.ts`, the
+ * function `AcpSession.emitEvent` uses), computed from that snapshot and the runtime profile — log
+ * data only; without one the card is settled `canceled` and answered `cancelled`, as today. Cards are
+ * emitted through the same boundaries as any other event (`updates.ts` `emitSessionEvent`).
+ */
+import { buildElicitationRequestedEvent, buildPermissionRequestedEvent, elicitationFieldKeys, isBlank, permissionRequestId, } from '../permission.js';
+import { validateWireEvent } from '../validate.js';
+import { isSdkCallbackCard, permissionCallbackContext } from '../../qoderAdapter/callbackContext.js';
+import { isRecord, nextSeq } from './emit.js';
+import { inboundKey, settlementErrorCode } from './jsonrpc.js';
+import { sameCause } from './record.js';
+import { callbackSnapshot, publishCallbacks, resetRuntime } from './runtime.js';
+import { getOwn, initialBoundaries, initialCallbacks, initialMessage, PENDING_PERMISSION_LIMIT, SETTLED_PERMISSION_LIMIT, } from './state.js';
+import { emitSessionEvent, endForegroundTurn, endHistory, flushMessage, flushOutOfTurnMessage } from './updates.js';
+/** `agentSessions.ts`'s admission refusal text, verbatim. */
+export const ADMISSION_REFUSED = 'Workstation is not accepting new work';
+/** `AcpSession.prompt`'s overlap refusal text, verbatim. */
+export const OVERLAPPING_TURN = 'An exact platform turn is still running; overlapping prompts are unavailable';
+/** What the SDK rejects pending requests with when the adapter's stdout ends (`jsonrpc.js` `close()`). */
+export const CONNECTION_CLOSED = 'ACP connection closed';
+/** A prompt for a connection with no bound session (Task 17b binds it from the open response). */
+export const NO_SESSION = 'No ACP session is open on this connection';
+/** `ClientApp` closes the connection on a batch; that reason is kept as the turn's error. */
+export const BATCH_CLOSE_REASON = 'JSON-RPC batches are not supported on this connection';
+/** Pending `'form'` elicitations kept at once (new bound, mirrors permissions' 64). */
+export const PENDING_ELICITATION_LIMIT = 64;
+const PERMISSION_CANCELLED = { outcome: { outcome: 'cancelled' } };
+const ELICITATION_DECLINE = { action: 'decline' };
+const ELICITATION_CANCEL = { action: 'cancel' };
+/** Connected = a running process whose JSON-RPC connection has not closed. */
+export function connected(state) {
+    return state.process.status === 'running' && state.closed === undefined;
+}
+/** The one setter of `rootSessionId` — `control.ts` calls it on the `session/new|load|resume` response. */
+export function bindRootSession(state, sessionId) {
+    state.rootSessionId = sessionId;
+}
+/** Every unanswered card id — `agent_opened.pendingRequestIds` (spec §5.5.4). */
+export function pendingRequestIds(state) {
+    return [...Object.keys(state.permissions), ...Object.keys(state.elicitations)];
+}
+/**
+ * A new adapter process is a new connection: today's per-connection, per-`AcpSession` and
+ * per-`LiveSession` fields start fresh (a respawn is a new session there too). `seq` is not reset.
+ */
+export function resetForSpawn(state) {
+    state.rootSessionId = null;
+    state.open = { status: 'idle' };
+    state.configOptions = null;
+    state.delegation = null;
+    state.history = null;
+    state.mapperScopes = {};
+    state.message = initialMessage();
+    state.steers = {};
+    state.steered = [];
+    state.asyncTasks = {};
+    resetRuntime(state);
+    state.turns = [];
+    state.exactExecutionUnconfirmed = false;
+    state.backgroundWriterUnconfirmed = false;
+    state.permissionsInterrupted = false;
+    state.permissions = {};
+    state.elicitations = {};
+    state.settledPermissions = [];
+    state.callbacks = initialCallbacks();
+    state.boundaries = initialBoundaries();
+    state.permissionOrigins = {};
+    state.permissionParents = {};
+    state.unresolvedPermissionOrigins = {};
+}
+/**
+ * The connection closed: unanswered cards can no longer be answered (nothing to write them to) — the
+ * read loop's `drainPendingApprovals`, so the callback snapshot goes incomplete and is published.
+ */
+export function dropCards(state, out) {
+    state.permissions = {};
+    state.elicitations = {};
+    state.callbacks.complete = false;
+    publishCallbacks(state, out);
+}
+export function closeErrorText(state) {
+    return state.closed === BATCH_CLOSE_REASON ? BATCH_CLOSE_REASON : CONNECTION_CLOSED;
+}
+// ---- turns ------------------------------------------------------------------------------------
+/**
+ * The short `agent_turn_done` `agentSessions.ts` builds itself for a prompt that never reached the
+ * session (admission refused, `prompt()` threw): no `nativeSessionId`, no `stopReason`.
+ */
+function refuseTurn(state, out, error, platformTurnId) {
+    out.frame({
+        t: 'agent_turn_done',
+        seq: nextSeq(state),
+        status: 'failed',
+        error,
+        ...(platformTurnId !== undefined ? { platformTurnId } : {}),
+    });
+}
+const STOP_REASONS = {
+    end_turn: 'end_turn',
+    max_tokens: 'max_tokens',
+    max_turn_requests: 'max_turns',
+    refusal: 'refusal',
+};
+/**
+ * End turn `index` — `AcpSession.finishTurn` + `agentSessions.ts`'s `onAgentTurnDone` frame, in one.
+ * The frame keeps that method's key order (`agent_turn_done` minus `sessionRef`); `agentRefused` and
+ * `errorCode` are carried for the projection, which turns them into `refusalFields` (Task 17b).
+ */
+function finishTurn(state, out, index, status, finish) {
+    const [turn] = state.turns.splice(index, 1);
+    if (!turn)
+        return;
+    if (state.turns.length === 0)
+        endForegroundTurn(state);
+    // Before the turn's own frame, on every path that ends a turn (`flushMessageCompleted`).
+    flushMessage(state, out);
+    const resolved = turn.interrupted ? 'interrupted' : status;
+    if (resolved === 'interrupted') {
+        state.permissionsInterrupted = true;
+        drainCards(state, out);
+    }
+    const frame = { t: 'agent_turn_done', seq: nextSeq(state), status: resolved };
+    if (turn.platformTurnId !== undefined)
+        frame.platformTurnId = turn.platformTurnId;
+    if (finish.executionEnded && state.turns.length === 0 && !state.backgroundWriterUnconfirmed) {
+        frame.executionEnded = true;
+        state.exactExecutionUnconfirmed = false;
+    }
+    const stopReason = typeof finish.stopReason === 'string' ? STOP_REASONS[finish.stopReason] : undefined;
+    if (resolved === 'completed' && stopReason !== undefined)
+        frame.stopReason = stopReason;
+    frame.nativeSessionId = state.rootSessionId !== null && state.rootSessionId.length > 0 ? state.rootSessionId : null;
+    frame.error = resolved === 'failed' && finish.error ? finish.error : null;
+    if (resolved === 'failed' && finish.agentRefused) {
+        frame.agentRefused = true;
+        if (finish.errorCode !== undefined)
+            frame.errorCode = finish.errorCode;
+    }
+    out.frame(frame);
+}
+/** `agent_prompt{blocksRef, platformTurnId?, admitted?}`. */
+export function onPromptNote(state, note, out) {
+    const { blocksRef, platformTurnId, admitted } = note;
+    if (typeof blocksRef !== 'string' || blocksRef === '' || (platformTurnId !== undefined && typeof platformTurnId !== 'string')
+        || (admitted !== undefined && typeof admitted !== 'boolean')) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    if (admitted === false) {
+        refuseTurn(state, out, ADMISSION_REFUSED, platformTurnId);
+        return;
+    }
+    if (!connected(state) || state.rootSessionId === null) {
+        // `AcpSession.prompt`'s `readLoopDead` branch: registered as a turn and finished on the spot, so
+        // "one prompt, one terminal result" holds here too.
+        state.turns.push({ requestId: -1, cause: { o: out.o, i: -1 }, interrupted: false, sent: false,
+            ...(platformTurnId !== undefined ? { platformTurnId } : {}) });
+        finishTurn(state, out, state.turns.length - 1, 'failed', { error: connected(state) ? NO_SESSION : closeErrorText(state) });
+        return;
+    }
+    if (state.exactExecutionUnconfirmed || (state.turns.length > 0 && (platformTurnId !== undefined
+        || state.turns.some((turn) => turn.platformTurnId !== undefined)))) {
+        refuseTurn(state, out, OVERLAPPING_TURN, platformTurnId);
+        return;
+    }
+    state.permissionsInterrupted = false;
+    // A turn ends any load history still open: its output is live, never history (T19 writes
+    // `historyEnd` before admitting a prompt; this is the backstop).
+    endHistory(state, out, true);
+    flushOutOfTurnMessage(state, out);
+    const { id, cause } = out.request('session/prompt', { sessionId: state.rootSessionId, prompt: [] }, {
+        fill: { blocksRef },
+        ...(platformTurnId !== undefined ? { annotation: { platformTurnId } } : {}),
+    });
+    const pending = { id, method: 'session/prompt', kind: 'prompt', cause };
+    state.outbound[String(id)] = pending;
+    state.turns.push({ requestId: id, cause, interrupted: false, sent: false, ...(platformTurnId !== undefined ? { platformTurnId } : {}) });
+    if (platformTurnId !== undefined)
+        state.exactExecutionUnconfirmed = true;
+}
+/**
+ * A `down` record: if it is a queued prompt's line, the turn is now on the agent, and its
+ * `platformTurnId` is the one the record's annotation carries.
+ */
+export function onDown(state, record) {
+    const annotation = record.annotation;
+    if (!annotation)
+        return;
+    const turn = state.turns.find((candidate) => sameCause(annotation.cause, candidate.cause));
+    if (!turn || turn.sent)
+        return;
+    turn.sent = true;
+    if (typeof annotation.platformTurnId === 'string')
+        turn.platformTurnId = annotation.platformTurnId;
+    else
+        delete turn.platformTurnId;
+}
+/** A `session/prompt` request settled: its turn ends on this record. */
+export function settlePrompt(state, entry, settlement, out) {
+    const index = state.turns.findIndex((turn) => turn.requestId === entry.id);
+    if (index < 0)
+        return;
+    switch (settlement.outcome) {
+        case 'result': {
+            const stopReason = isRecord(settlement.result) ? settlement.result.stopReason : undefined;
+            // ACP's own `cancelled` forces `interrupted` even when no interrupt was sent (a backstop).
+            finishTurn(state, out, index, stopReason === 'cancelled' ? 'interrupted' : 'completed', { stopReason, executionEnded: true });
+            return;
+        }
+        case 'error': {
+            // The one exit where the agent itself answered (`TurnResult.agentRefused`).
+            const errorCode = settlementErrorCode(settlement);
+            finishTurn(state, out, index, 'failed', {
+                error: settlement.error.message, agentRefused: true, errorCode, executionEnded: errorCode !== undefined,
+            });
+            return;
+        }
+        case 'closed':
+            finishTurn(state, out, index, 'failed', { error: closeErrorText(state) });
+            return;
+    }
+}
+/**
+ * `agent_prompt_failed{requestId, error}` — the executor could not write a prompt's line (its blocks
+ * were gone after a restart, or the write failed). Ignored once the line is in raw: then the agent
+ * has it and its response ends the turn. The prompt never reached the agent, which is proof its
+ * execution ended (`TurnResult.executionEnded`).
+ */
+export function onPromptFailedNote(state, note, out) {
+    const { requestId, error } = note;
+    const entry = typeof requestId === 'number' ? state.outbound[String(requestId)] : undefined;
+    const index = entry ? state.turns.findIndex((turn) => turn.requestId === entry.id) : -1;
+    if (!entry || entry.kind !== 'prompt' || index < 0 || state.turns[index].sent || typeof error !== 'string') {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    delete state.outbound[String(entry.id)];
+    finishTurn(state, out, index, 'failed', { error, executionEnded: true });
+}
+/**
+ * `agent_interrupt{}` — `AcpSession.interrupt`: every turn is marked interrupted (its result will say
+ * so whatever the agent answers), later permission requests are refused until the next prompt, every
+ * pending card is answered "cancelled", then `session/cancel` goes out.
+ */
+export function onInterruptNote(state, out) {
+    for (const turn of state.turns)
+        turn.interrupted = true;
+    state.permissionsInterrupted = true;
+    drainCards(state, out);
+    if (connected(state) && state.rootSessionId !== null)
+        out.notify('session/cancel', { sessionId: state.rootSessionId });
+}
+/** The connection is gone: every turn left ends `failed` (`finishAllTurns`). */
+export function finishAllTurns(state, out) {
+    while (state.turns.length > 0)
+        finishTurn(state, out, 0, 'failed', { error: closeErrorText(state) });
+}
+// ---- cards ------------------------------------------------------------------------------------
+function respond(state, out, rpcKey, result) {
+    const inbound = state.inbound[rpcKey];
+    if (!inbound)
+        return;
+    delete state.inbound[rpcKey];
+    if (connected(state))
+        out.result(inbound.id, result);
+}
+/** `AcpSession.settleApproval`'s bookkeeping: remembered with its reason, or — past the bound — the snapshot goes incomplete. */
+function rememberSettledPermission(state, requestId, reason) {
+    if (state.settledPermissions.length < SETTLED_PERMISSION_LIMIT)
+        state.settledPermissions.push({ requestId, reason });
+    else
+        state.callbacks.complete = false;
+}
+/** Settle one card and answer the agent; `publish: false` inside a drain, which publishes once for all. */
+function settlePermission(state, out, requestId, result, reason, publish = true) {
+    const entry = state.permissions[requestId];
+    if (!entry)
+        return;
+    delete state.permissions[requestId];
+    rememberSettledPermission(state, requestId, reason);
+    if (publish)
+        publishCallbacks(state, out);
+    respond(state, out, entry.rpcKey, result);
+}
+function settleElicitation(state, out, requestId, result) {
+    const entry = state.elicitations[requestId];
+    if (!entry)
+        return;
+    delete state.elicitations[requestId];
+    respond(state, out, entry.rpcKey, result);
+}
+/**
+ * `drainPendingApprovals` + `drainPendingElicitations`: nobody will answer these any more. The
+ * callback snapshot goes incomplete and is published once (`drainPendingApprovals` publishes before
+ * it resolves the cards).
+ */
+function drainCards(state, out) {
+    state.callbacks.complete = false;
+    publishCallbacks(state, out);
+    for (const requestId of Object.keys(state.permissions))
+        settlePermission(state, out, requestId, PERMISSION_CANCELLED, 'canceled', false);
+    for (const requestId of Object.keys(state.elicitations))
+        settleElicitation(state, out, requestId, ELICITATION_CANCEL);
+}
+/** A request answered without a card. */
+function refuseRequest(state, out, id, result) {
+    state.diagnostics.refusedRequests += 1;
+    out.result(id, result);
+    return undefined;
+}
+/** `AcpSession.registerPendingApproval`'s field rule. */
+function badCardField(value) {
+    // `Buffer.byteLength` without `Buffer`: UTF-8 length of a JS string.
+    let bytes = 0;
+    for (const char of value) {
+        const code = char.codePointAt(0);
+        bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+    }
+    return !value.trim() || bytes > 256 || /[\x00-\x1f\x7f]/.test(value);
+}
+/**
+ * `session/request_permission` (params already through the SDK's zod schema) — `registerPermissionHandlers`
+ * → `handleRequestPermission` → `registerPendingApproval` → `emitEvent`, in their order. Returns the
+ * card id if a card now waits for the user (the request stays held), `undefined` if it was answered.
+ */
+export function onPermissionRequest(state, id, params, out) {
+    const sessionId = params.sessionId;
+    if (typeof sessionId !== 'string' || !sessionId.trim())
+        return refuseRequest(state, out, id, PERMISSION_CANCELLED);
+    const options = Array.isArray(params.options) ? params.options : [];
+    if (options.length === 0)
+        return refuseRequest(state, out, id, PERMISSION_CANCELLED);
+    if (state.process.status !== 'running')
+        return refuseRequest(state, out, id, PERMISSION_CANCELLED);
+    const requestId = permissionRequestId(state.process.spawn.spawnId, id);
+    const rpcRequestId = String(id);
+    const event = buildPermissionRequestedEvent({
+        requestId, rpcRequestId, sessionId, toolCall: params.toolCall, options: options,
+    });
+    if (validateWireEvent(event))
+        return refuseRequest(state, out, id, PERMISSION_CANCELLED);
+    const origin = sessionId;
+    // Inside a load's history window the root is not bound yet, but the session being loaded is it
+    // (today's attached session already knows its id).
+    const root = state.rootSessionId ?? state.history?.rootSessionId ?? null;
+    if (origin !== root && !getOwn(state.permissionOrigins, origin))
+        return refuseRequest(state, out, id, PERMISSION_CANCELLED);
+    if (state.permissionsInterrupted)
+        return refuseRequest(state, out, id, PERMISSION_CANCELLED);
+    if ([requestId, origin, rpcRequestId].some(badCardField) || Object.keys(state.permissions).length >= PENDING_PERMISSION_LIMIT
+        || state.permissions[requestId] !== undefined || state.settledPermissions.some((settled) => settled.requestId === requestId)) {
+        // `registerPendingApproval`'s refusal: the snapshot can no longer vouch for every card.
+        state.callbacks.complete = false;
+        publishCallbacks(state, out);
+        return refuseRequest(state, out, id, PERMISSION_CANCELLED);
+    }
+    const rpcKey = inboundKey(id);
+    state.permissions[requestId] = { requestId, rpcKey, origin, rpcRequestId, optionIds: options.map((option) => option.optionId) };
+    publishCallbacks(state, out);
+    let payload = event.payload;
+    const toolCall = payload.toolCall;
+    if (isSdkCallbackCard(toolCall)) {
+        // `AcpSession.emitEvent`: an SDK callback card is shown only with the evidence the server needs
+        // to route its answer back (`callbackContext`); without it, it is cancelled.
+        const spawnId = state.process.spawn.spawnId;
+        const callbackContext = root === null ? undefined : permissionCallbackContext({
+            rootSessionId: root, origin, requestId, toolCall, pendingRpcRequestId: rpcRequestId,
+            diagnostics: { generation: spawnId, available: state.runtime.available, profile: state.runtime.profile, callbacks: callbackSnapshot(state) },
+        });
+        if (!callbackContext) {
+            settlePermission(state, out, requestId, PERMISSION_CANCELLED, 'canceled');
+            state.diagnostics.refusedRequests += 1;
+            return undefined;
+        }
+        payload = { ...payload, callbackContext };
+    }
+    emitSessionEvent(state, out, { eventName: event.eventName, payload, acpSessionId: origin });
+    return requestId;
+}
+/**
+ * `elicitation/create` — `handleCreateElicitation` on a session connection (no `present`, so `'url'`
+ * declines) → `handleFormElicitation` → `registerPendingElicitation`. Returns the card id, as
+ * {@link onPermissionRequest} does.
+ */
+export function onElicitationRequest(state, id, params, out) {
+    if (params.mode !== 'form')
+        return refuseRequest(state, out, id, ELICITATION_DECLINE);
+    const requestId = String(id);
+    if (!requestId)
+        return refuseRequest(state, out, id, ELICITATION_DECLINE);
+    const request = params;
+    if (elicitationFieldKeys(request.requestedSchema).length === 0)
+        return refuseRequest(state, out, id, ELICITATION_DECLINE);
+    const event = buildElicitationRequestedEvent(request, requestId);
+    if (validateWireEvent(event))
+        return refuseRequest(state, out, id, ELICITATION_DECLINE);
+    if (typeof request.message === 'string' && isBlank(request.message)) {
+        // Legible, just not collectible: raise it, then decline (`handleFormElicitation`).
+        emitSessionEvent(state, out, event);
+        return refuseRequest(state, out, id, ELICITATION_DECLINE);
+    }
+    if (state.elicitations[requestId] === undefined && Object.keys(state.elicitations).length >= PENDING_ELICITATION_LIMIT) {
+        return refuseRequest(state, out, id, ELICITATION_DECLINE);
+    }
+    // Same id twice replaces the earlier card, as `pendingElicitations.set` does.
+    state.elicitations[requestId] = { requestId, rpcKey: inboundKey(id) };
+    emitSessionEvent(state, out, event);
+    return requestId;
+}
+/**
+ * The agent sent `$/cancel_request` for one of its requests: a card waiting on it is settled the way
+ * the handler's abort listener settles it (permission → cancelled, elicitation → `cancel`). The card
+ * the server shows is not retracted, as today.
+ */
+export function onInboundCancelled(state, rpcKey, out) {
+    const card = state.inbound[rpcKey]?.card;
+    if (card === undefined)
+        return;
+    if (state.permissions[card]?.rpcKey === rpcKey)
+        settlePermission(state, out, card, PERMISSION_CANCELLED, 'canceled');
+    else if (state.elicitations[card]?.rpcKey === rpcKey)
+        settleElicitation(state, out, card, ELICITATION_CANCEL);
+}
+/** A low-level `rpc.respond` answered a carded request: the card goes with it (settled as answered). */
+export function forgetCard(state, rpcKey, card, out) {
+    if (card === undefined)
+        return;
+    if (state.permissions[card]?.rpcKey === rpcKey) {
+        delete state.permissions[card];
+        rememberSettledPermission(state, card, 'answered');
+        publishCallbacks(state, out);
+    }
+    else if (state.elicitations[card]?.rpcKey === rpcKey) {
+        delete state.elicitations[card];
+    }
+}
+/** `agent_answer{requestId, outcome}` — `AcpSession.answer`; an unknown id is ignored (counted). */
+export function onAnswerNote(state, note, out) {
+    const { requestId, outcome } = note;
+    const entry = typeof requestId === 'string' ? state.permissions[requestId] : undefined;
+    if (!entry || typeof outcome !== 'string' || !connected(state)) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    settlePermission(state, out, entry.requestId, entry.optionIds.includes(outcome)
+        ? { outcome: { outcome: 'selected', optionId: outcome } }
+        : PERMISSION_CANCELLED, 'answered');
+}
+/**
+ * `agent_answer_undeliverable{requestId}` — a permission card the server cannot be shown: the send-time
+ * projection dropped it (a child session's card for a peer older than `AGENT_WIRE_SCOPED_ORIGIN_VERSION`),
+ * so the daemon logs this note and the agent is answered "cancelled", as `onAgentEvent` answers it
+ * today. Driven by a note, so a replay answers it again from the log, never from the connection.
+ */
+export function onUndeliverableNote(state, note, out) {
+    const { requestId } = note;
+    const entry = typeof requestId === 'string' ? getOwn(state.permissions, requestId) : undefined;
+    if (!entry || !connected(state)) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    settlePermission(state, out, entry.requestId, PERMISSION_CANCELLED, 'answered');
+}
+/**
+ * `agent_elicitation_answer{requestId, action, content?}` — `agentSessions.ts`'s narrowing (an action
+ * other than accept/decline/cancel declines) + `AcpSession.answerElicitation`.
+ */
+export function onElicitationAnswerNote(state, note, out) {
+    const { requestId, action, content } = note;
+    const entry = typeof requestId === 'string' ? state.elicitations[requestId] : undefined;
+    if (!entry || typeof action !== 'string' || !connected(state) || (content !== undefined && !isRecord(content))) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    const known = action === 'accept' || action === 'decline' || action === 'cancel';
+    settleElicitation(state, out, entry.requestId, known ? { action, ...(content ? { content } : {}) } : ELICITATION_DECLINE);
+}

package/dist/workstation/acp/processor/sideChannel.js

@@ -0,0 +1,80 @@
+/**
+ * Side channels as notes (Task 17c, spec 2026-10-11 §5.4: "一切输入都进日志" — Qoder side-file events
+ * included).
+ *
+ * Qoder's certified background terminal repair reads the agent's transcript files. The processor
+ * never does: a file can change between the live run and a replay. The daemon reads them
+ * (`qoderAdapter/backgroundTerminal.ts` `BackgroundSideNotes`, run by T19) and appends what it
+ * derived as notes; the processor folds a fact only when it reads its note, with the pure fold
+ * (`qoderAdapter/backgroundTerminalFold.ts`) over checkpointed state. A replay therefore gives the same
+ * frames whatever the files say by then, or if they are gone.
+ *
+ * - `qoder_terminal_repair{nativeSessionId, restoreCalls?}` — the daemon enabled the repair where
+ *   today's path calls `enableBackgroundTerminalRepair`: after the open note for a load (so the
+ *   history is observed), after the open result for new/resume (`restoreCalls: true` on resume).
+ *   Refused (`droppedNotes`) unless connected, the runtime is the certified one, the id is the root
+ *   (or the session being loaded) and no repair is on yet. `includeProcess` follows the subwork
+ *   boundary (`supportsSubworkMeta`), as `AcpSession` decides it.
+ * - `qoder_side{fact}` / `qoder_side{chunk}` — one derived fact (or the consecutive chunks of one too
+ *   large for a note). Its events — a child transcript row's, or the results a poll's end publishes —
+ *   are emitted the way `AcpSession.emitEvent` emits the repair's (`updates.ts` `emitSessionEvent`).
+ *   Facts are idempotent by their own fields (ids, row uuids), so a reader that restarted from the
+ *   start of a file repeats nothing. Dropped while no repair is on or the connection is closed.
+ */
+import { certifiedRuntime } from '../../qoderAdapter/foregroundOutput.js';
+import { supportsSubworkMeta } from '../../qoderAdapter/subwork.js';
+import { newTerminalRepairData, readSideNote, TerminalRepairFold } from '../../qoderAdapter/backgroundTerminalFold.js';
+import { connected } from './session.js';
+import { emitSessionEvent } from './updates.js';
+function agentInfo(state) {
+    return state.initialize.status === 'ready' ? state.initialize.facts.agentInfo : undefined;
+}
+/** `qoder_terminal_repair{nativeSessionId, restoreCalls?}`. */
+export function onRepairNote(state, note) {
+    const { nativeSessionId, restoreCalls } = note;
+    const root = state.rootSessionId ?? state.history?.rootSessionId ?? null;
+    if (!connected(state) || state.boundaries.repair !== null || !certifiedRuntime(agentInfo(state)) || typeof nativeSessionId !== 'string'
+        || nativeSessionId !== root || (restoreCalls !== undefined && typeof restoreCalls !== 'boolean')) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    state.boundaries.repair = newTerminalRepairData({
+        nativeSessionId, restoreCalls: restoreCalls === true, includeProcess: supportsSubworkMeta(agentInfo(state)),
+    });
+}
+/** `qoder_side{fact | chunk}`. */
+export function onSideNote(state, note, out) {
+    const repair = state.boundaries.repair;
+    if (repair === null || !connected(state)) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    const read = readSideNote(state.boundaries.sideChunk, note);
+    state.boundaries.sideChunk = read.buffer;
+    if (read.malformed) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    if (!read.fact)
+        return;
+    for (const event of new TerminalRepairFold(repair).apply(read.fact))
+        emitSessionEvent(state, out, event);
+}
+/** The connection or the session is gone: the repair stops (`BackgroundTerminalRepair.close`). */
+export function closeRepair(state) {
+    state.boundaries.repair = null;
+    state.boundaries.sideChunk = null;
+}
+/**
+ * What the daemon's reader asks before it reads (`BackgroundSideNotes.poll(demand)`), answered from the
+ * processor's **current** state, or `undefined` while no repair is on (stop the reader). The answers
+ * only steer which files are read; what was read reaches the processor through the notes alone.
+ */
+export function sideDemand(state) {
+    if (state.boundaries.repair === null)
+        return undefined;
+    return {
+        active: () => state.boundaries.repair !== null && new TerminalRepairFold(state.boundaries.repair).active(),
+        wantsProcess: (toolUseId) => state.boundaries.repair !== null && new TerminalRepairFold(state.boundaries.repair).wantsProcess(toolUseId),
+    };
+}

package/dist/workstation/acp/processor/state.js

@@ -0,0 +1,74 @@
+/**
+ * 2: Task 17b's open-session layer. 3: Task 17c (`boundaries`, `callbacks`, settled permissions with
+ * their reason, `rpcRequestId` on a pending permission). 4: the repair's `polledProcesses`. An older
+ * checkpoint is refused, never half-read.
+ */
+export const PROCESSOR_STATE_SCHEMA = 4;
+export const SETTLED_HISTORY_LIMIT = 16;
+export const SETTLED_PERMISSION_LIMIT = 64;
+export const PENDING_PERMISSION_LIMIT = 64;
+export const UNRESOLVED_ORIGIN_LIMIT = 1024;
+export const PENDING_PROFILE_LIMIT = 8;
+export const STEERED_HISTORY_LIMIT = 64;
+/** Unfinished async tasks tracked per connection, all sessions together. */
+export const ASYNC_TASK_LIMIT = 1024;
+export function initialRuntime() {
+    return { revision: 0, available: true, adapterRevision: 0, pendingProfiles: {} };
+}
+export function initialBoundaries() {
+    return { foreground: { pending: {} }, subwork: { calls: {}, count: 0 }, repair: null, sideChunk: null };
+}
+export function initialCallbacks() {
+    return { complete: true, rootSessionId: null };
+}
+export function initialMessage() {
+    return { open: false, messageId: null, outOfTurn: false };
+}
+export function initialState() {
+    return {
+        schema: PROCESSOR_STATE_SCHEMA,
+        offset: -1,
+        t: 0,
+        process: { status: 'none' },
+        initialize: { status: 'idle' },
+        outbound: {},
+        inbound: {},
+        rootSessionId: null,
+        seq: 0,
+        turns: [],
+        exactExecutionUnconfirmed: false,
+        backgroundWriterUnconfirmed: false,
+        permissionsInterrupted: false,
+        permissions: {},
+        elicitations: {},
+        settledPermissions: [],
+        callbacks: initialCallbacks(),
+        permissionOrigins: {},
+        permissionParents: {},
+        unresolvedPermissionOrigins: {},
+        open: { status: 'idle' },
+        configOptions: null,
+        delegation: null,
+        history: null,
+        mapperScopes: {},
+        message: initialMessage(),
+        steers: {},
+        steered: [],
+        asyncTasks: {},
+        activity: null,
+        runtime: initialRuntime(),
+        boundaries: initialBoundaries(),
+        diagnostics: {
+            orphanResponses: 0, protocolErrors: 0, ignoredLines: 0, unknownNotes: 0, droppedNotes: 0, refusedRequests: 0,
+            rejectedRelations: 0, droppedUpdates: 0, invalidEvents: 0, untrackedAsyncTasks: 0, settled: [],
+        },
+    };
+}
+/** Set `record[key]` as an own property: agent-chosen keys (`__proto__`) stay plain keys. */
+export function putOwn(record, key, value) {
+    Object.defineProperty(record, key, { value, enumerable: true, writable: true, configurable: true });
+}
+/** `record[key]` if it is an own property. */
+export function getOwn(record, key) {
+    return Object.hasOwn(record, key) ? record[key] : undefined;
+}