@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/acp/outbox.js

@@ -0,0 +1,330 @@
+/**
+ * ## Subagent relations bypass the window (fix round 1, spec §5.6)
+ *
+ * The server holds back its applied watermark — so its acks — at the first child frame whose subagent relation (`subagent_spawned`,
+ * the server's `TimelineEvent.SubagentSpawned`) it has not received yet (`noteApplied` capped at `nativePendingBefore - 1`,
+ * `ExternalAgentEventApplier.kt`). Every later frame then counts against the window; if the relation comes 256 or more frames after
+ * that first orphan child frame, a window that held it back would stall the session for good (the server waits 30 s, poisons, the
+ * reopen repeats it). So:
+ *
+ * - **producing**: while a child frame whose relation is not recorded yet is unacknowledged ({@link orphanOutstanding}), the record
+ *   loop may run past the window, so the relation can be folded at all. Whatever the branch, this life never holds more than
+ *   {@link RELATION_WAIT_EVENTS} / {@link RELATION_WAIT_BYTES} (1024 frames / 32 MiB) unacknowledged — pinned entries included — plus
+ *   the frames of the one record being folded: that is the daemon's memory bound per session;
+ * - **sending**: once a relation that resolves such a child (a *resolving* relation) is recorded, it and every entry before it stop
+ *   counting against either window ({@link pinnedThrough}): the sender takes them past the window, in seq order (sending the
+ *   relation first would make the server drop the lower seqs as duplicates); the socket gate still applies. They must keep not
+ *   counting after they are sent: the server applied them but wasted its acks while capped (each ack attempt resets its 32-event
+ *   count), so its next ack needs up to 31 more applied frames — a window still full of them would deadlock there. They leave the
+ *   outbox with that ack. A relation that resolves nothing recorded is not what the server waits for and keeps to the window
+ *   (sending past it could overflow a parked server's 512-frame hold-off).
+ *
+ * ## Residual (documented, not fixed)
+ *
+ * While the producing window is full — a server parked on an approval with ≥ 256 root frames held, a connection that is down, an
+ * applier that never acknowledges — the record loop folds nothing: a steer or config RPC waits for the processor's reply and can
+ * time out on the server; an `agent_interrupt` note is folded (and the `session/cancel` written) only once the server unparks.
+ */
+/** Unacknowledged events per session (spec §5.6, `W_EVT`). `ACK_EVERY_EVENTS(32) < W_EVT ≤ HOLD_OFF_CAPACITY(512)`. */
+export const SESSION_WINDOW_EVENTS = 256;
+/** Unacknowledged bytes per session (spec §5.6): a few huge frames cannot hog the window. */
+export const SESSION_WINDOW_BYTES = 8 * 1024 * 1024;
+/** How far production may run past the window while a recorded child frame still waits for its relation (bounds memory). */
+export const RELATION_WAIT_EVENTS = 4 * SESSION_WINDOW_EVENTS;
+export const RELATION_WAIT_BYTES = 4 * SESSION_WINDOW_BYTES;
+/** A frame carrying a subagent relation (the server's `SubagentSpawned`): it bypasses the session window. */
+export function isRelationFrame(frame) {
+    return frame.t === 'agent_event' && frame.eventName === 'subagent_spawned';
+}
+/**
+ * `src.i` of an outbox entry no record produced: a frame this daemon numbered itself (a degraded session's failed `turn_done`,
+ * `src.o` = the last record folded before it) or one imported from a legacy journal (`src.o` = 0). A replay never reproduces it
+ * (T21 skips it when comparing). Far above any per-record frame index.
+ */
+export const DAEMON_FRAME_INDEX = 1 << 24;
+/**
+ * Connection epoch of an entry that may have reached the server on an earlier connection (or in an earlier daemon life): it is not
+ * sent again until the server reopens the ref and says how far it got ({@link SessionOutbox.resendAll} after an `ack` of the open's
+ * `resumeFromSeq`) — resending a frame the server already applied could, for a `turn_done`, end a newer turn (analysis B §3.1).
+ */
+export const SENT_EARLIER = -1;
+const frameBytes = (frame) => Buffer.byteLength(JSON.stringify(frame));
+export function isOutboxTail(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { seq, src } = value;
+    return Number.isSafeInteger(seq) && typeof src === 'object' && src !== null &&
+        Number.isSafeInteger(src.o) && Number.isSafeInteger(src.i);
+}
+export class SessionOutbox {
+    store;
+    items = [];
+    committed;
+    highestSeq = 0;
+    ownEvents = 0;
+    ownBytes = 0;
+    chain = Promise.resolve();
+    roomWaiters = new Set();
+    listeners = new Set();
+    stopped = false;
+    /** Children whose relation frame this outbox recorded. */
+    related = new Set();
+    /** Seq of the latest resolving relation: entries at or below it count against neither window (file comment). */
+    pinned = 0;
+    isRelated;
+    /**
+     * `isRelated`: whether the session already knows a child's relation from elsewhere (the processor's relation graph — a relation
+     * recorded by an earlier life, or replayed by a load). Without it only relations this outbox recorded count.
+     */
+    constructor(store, init = {}) {
+        this.store = store;
+        this.isRelated = init.isRelated ?? (() => false);
+        this.committed = isOutboxTail(init.committedTail) ? { seq: init.committedTail.seq, src: { ...init.committedTail.src } } : null;
+        this.highestSeq = this.committed?.seq ?? 0;
+        for (const record of init.leftovers ?? []) {
+            // Read back past the watermark only; a record at or below it is acknowledged (truncation is by whole segments).
+            if (this.committed && record.seq <= this.committed.seq)
+                continue;
+            this.items.push({ o: record.o, seq: record.seq, src: { ...record.src }, frame: record.frame, bytes: frameBytes(record.frame), leftover: true,
+                ...this.classify(record.seq, record.frame), sentOn: SENT_EARLIER });
+            this.highestSeq = Math.max(this.highestSeq, record.seq);
+        }
+    }
+    /**
+     * Resolving relation / orphan frame, in record order (a relation relates its child for every later frame). An orphan is a frame
+     * the server retains until a relation it has not received: a child frame (`acpSessionId`) whose child is unrelated, and — Task
+     * 22 — a `subagent_state_update` (any origin) naming an unrelated child (`payload.subagentSessionId`): the server's
+     * `receiveNativeEventLocked` holds it, and with it its acks, until that child's `subagent_spawned` exactly as it holds a child
+     * frame. The state update's own child is the key: a root-origin one would otherwise not be an orphan at all, its relation would
+     * keep to the window, and the session would stall where Task 20 fixed it for child frames.
+     */
+    classify(seq, frame) {
+        const unrelated = (child) => child !== undefined && !this.related.has(child) && !this.isRelated(child) ? child : undefined;
+        const origin = frame.t === 'agent_event' && typeof frame.acpSessionId === 'string' ? frame.acpSessionId : undefined;
+        const stateChild = frame.t === 'agent_event' && frame.eventName === 'subagent_state_update'
+            ? frame.payload?.subagentSessionId
+            : undefined;
+        const orphanOf = unrelated(typeof stateChild === 'string' ? stateChild : undefined) ?? unrelated(origin);
+        let resolving = false;
+        if (isRelationFrame(frame)) {
+            const child = frame.payload?.subagentSessionId;
+            if (typeof child === 'string') {
+                resolving = this.items.some((item) => item.orphanOf === child);
+                this.related.add(child);
+                if (resolving)
+                    this.pinned = Math.max(this.pinned, seq);
+            }
+        }
+        return { resolving, ...(orphanOf !== undefined ? { orphanOf } : {}) };
+    }
+    /** Entries at or below this seq count against neither window (the latest resolving relation; 0: none). */
+    get pinnedThrough() { return this.pinned; }
+    /** An unacknowledged child frame whose relation is still not recorded: the server is (likely) holding its acks for it. */
+    orphanOutstanding() {
+        return this.items.some((item) => item.orphanOf !== undefined && !this.related.has(item.orphanOf) && !this.isRelated(item.orphanOf));
+    }
+    /** Highest seq this outbox ever held (entries, or the acknowledged watermark): a new life numbers after it (§5.5). */
+    get lastSeq() { return this.highestSeq; }
+    /** The acknowledged watermark (`committedTail`), `null` before the first truncating ack. */
+    get committedTail() { return this.committed; }
+    /** Unacknowledged entries, in seq order. */
+    get pending() { return this.items; }
+    /** Unacknowledged entries appended by this life (the producing window), past {@link pinnedThrough}. */
+    get backlog() {
+        if (this.pinned === 0)
+            return { events: this.ownEvents, bytes: this.ownBytes };
+        let events = 0;
+        let bytes = 0;
+        for (const item of this.items)
+            if (!item.leftover && item.seq > this.pinned) {
+                events += 1;
+                bytes += item.bytes;
+            }
+        return { events, bytes };
+    }
+    /**
+     * Entries sent on connection `epoch` and not acknowledged (the sending window). Entries at or below {@link pinnedThrough} are
+     * sent past the window either way (the sender bypasses it for them); once sent they count only when `pinnedCountsWhenSent` —
+     * a server that acknowledges as soon as the relation releases its cap (`AGENT_WIRE_RELATION_ACK_VERSION`, Task 22). An older
+     * server wastes its acks while capped, so its first ack after the relation can need up to 31 more applied frames: counting the
+     * pinned ones there would deadlock right after the relation (fix round 1 of Task 20).
+     */
+    inflight(epoch, pinnedCountsWhenSent = false) {
+        let events = 0;
+        let bytes = 0;
+        for (const item of this.items) {
+            if (item.sentOn === epoch && (pinnedCountsWhenSent || item.seq > this.pinned)) {
+                events += 1;
+                bytes += item.bytes;
+            }
+        }
+        return { events, bytes };
+    }
+    /** Called whenever there may be something new to send (an append, an ack opening the window, a resend). */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    changed() { for (const listener of [...this.listeners])
+        listener(); }
+    run(op) {
+        const result = this.chain.then(op);
+        this.chain = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /** Waits for every stream operation queued so far. */
+    flush() { return this.chain; }
+    /**
+     * Record frames before they are sent. Resolves once they are durable; rejects when the stream refused them (the caller degrades
+     * the session — a frame that could not be recorded is not sent either).
+     */
+    append(frames) {
+        if (frames.length === 0)
+            return this.chain;
+        return this.run(async () => {
+            const entries = frames.map((f) => ({ seq: f.seq, src: { o: f.src.o, i: f.src.i }, frame: { ...f.frame } }));
+            const { first } = await this.store.append(entries);
+            entries.forEach((entry, index) => {
+                const bytes = frameBytes(entry.frame);
+                this.items.push({ o: first + index, seq: entry.seq, src: entry.src, frame: entry.frame, bytes, leftover: false, ...this.classify(entry.seq, entry.frame), sentOn: null });
+                this.highestSeq = Math.max(this.highestSeq, entry.seq);
+                this.ownEvents += 1;
+                this.ownBytes += bytes;
+            });
+            this.wakeRoom(); // a resolving relation unpins the producing window
+            this.changed();
+        });
+    }
+    /**
+     * The server applied everything through `throughSeq` (`agent_event_ack`, or an open's `resumeFromSeq`): forget those entries and
+     * truncate the stream through the last of them, persisting `{seq, src}` of that entry as the watermark. Nothing held at or below
+     * it: nothing changes. A failed commit is reported (`onError`) — the entries are acknowledged either way; the stream keeps them
+     * until a later commit passes them.
+     */
+    ack(throughSeq, onError) {
+        return this.run(async () => {
+            let k = -1;
+            for (let i = 0; i < this.items.length && this.items[i].seq <= throughSeq; i++)
+                k = i;
+            if (k < 0)
+                return;
+            const last = this.items[k];
+            const removed = this.items.splice(0, k + 1);
+            for (const item of removed)
+                if (!item.leftover) {
+                    this.ownEvents -= 1;
+                    this.ownBytes -= item.bytes;
+                }
+            this.committed = { seq: last.seq, src: { ...last.src } };
+            this.wakeRoom();
+            this.changed();
+            try {
+                await this.store.commit({ outbox: { through: last.o, tail: { seq: last.seq, src: { ...last.src } } } });
+            }
+            catch (error) {
+                onError?.(error);
+            }
+        });
+    }
+    /**
+     * A processor checkpoint at raw `offset`, and raw truncation through it (the keeper refuses anything past it) unless `truncate` is
+     * false (a marker checkpoint, Task 21).
+     */
+    commitCheckpoint(offset, blob, truncate = true) {
+        return this.run(async () => {
+            await this.store.commit({ checkpoint: { offset, blob }, ...(truncate ? { rawThrough: offset } : {}) });
+        });
+    }
+    /**
+     * The session re-attached to keeper-acp after its connection was lost (Task 21): the stream is the truth again. An append whose
+     * reply was lost may have landed (it is in `leftovers` now) or not (it is gone, and the record loop folds its record again). The
+     * entries are replaced by what the stream holds past its watermark; an entry this object already had keeps whether (and on which
+     * connection) it was sent and whether an earlier life left it; one it never saw was never sent. Call it with no stream operation
+     * in flight ({@link flush} first). Listeners and room waiters are kept.
+     */
+    rebase(init) {
+        const previous = new Map(this.items.map((item) => [item.seq, item]));
+        this.items.length = 0;
+        this.related.clear();
+        this.pinned = 0;
+        this.ownEvents = 0;
+        this.ownBytes = 0;
+        if (isOutboxTail(init.committedTail) && (this.committed === null || init.committedTail.seq >= this.committed.seq)) {
+            this.committed = { seq: init.committedTail.seq, src: { ...init.committedTail.src } };
+        }
+        this.highestSeq = Math.max(this.highestSeq, this.committed?.seq ?? 0);
+        for (const record of init.leftovers) {
+            if (this.committed && record.seq <= this.committed.seq)
+                continue;
+            const before = previous.get(record.seq);
+            const leftover = before?.leftover ?? false;
+            const bytes = frameBytes(record.frame);
+            this.items.push({ o: record.o, seq: record.seq, src: { ...record.src }, frame: record.frame, bytes, leftover,
+                ...this.classify(record.seq, record.frame), sentOn: before ? before.sentOn : null });
+            if (!leftover) {
+                this.ownEvents += 1;
+                this.ownBytes += bytes;
+            }
+            this.highestSeq = Math.max(this.highestSeq, record.seq);
+        }
+        this.wakeRoom();
+        this.changed();
+    }
+    /** Mark every unacknowledged entry unsent: the sender resends them in order (a reopen's replay, after the ack of its watermark). */
+    resendAll() {
+        for (const item of this.items)
+            item.sentOn = null;
+        this.changed();
+    }
+    /**
+     * A new connection: everything recorded so far — sent on an earlier connection or produced while none was bound — is held until
+     * the server reopens the ref and says how far it got ({@link SENT_EARLIER}); what is recorded from now on is sent at once. (The
+     * journal's semantics: frames produced while unbound were replayed by the reopen, never sent on their own.)
+     */
+    connectionChanged() {
+        for (const item of this.items)
+            item.sentOn = SENT_EARLIER;
+    }
+    /** The first entry never sent (the sender's next candidate), in seq order. */
+    nextUnsent() {
+        return this.items.find((item) => item.sentOn === null);
+    }
+    /** Resolves when this life's unacknowledged backlog is below the window (immediately once {@link stopWaiting} ran). */
+    room() {
+        if (this.hasRoom())
+            return undefined;
+        return new Promise((resolve) => { this.roomWaiters.add(resolve); });
+    }
+    hasRoom() {
+        if (this.stopped)
+            return true;
+        // A hard bound on everything this life holds unacknowledged, pinned or not: chained resolving relations each reset `backlog`,
+        // but pinned entries leave memory only with an ack.
+        if (this.ownEvents >= RELATION_WAIT_EVENTS || this.ownBytes >= RELATION_WAIT_BYTES)
+            return false;
+        const { events, bytes } = this.backlog;
+        if (events < SESSION_WINDOW_EVENTS && bytes < SESSION_WINDOW_BYTES)
+            return true;
+        // Past the window only while a relation is awaited: the server cannot acknowledge before it, so it must be folded.
+        return this.orphanOutstanding();
+    }
+    wakeRoom() {
+        if (!this.hasRoom())
+            return;
+        for (const resolve of [...this.roomWaiters])
+            resolve();
+        this.roomWaiters.clear();
+    }
+    /** The session is closing or degraded: nobody waits for room any more. */
+    stopWaiting() {
+        this.stopped = true;
+        this.wakeRoom();
+    }
+}
+/** An outbox store over a transport session (`acp.outbox.append` / `acp.commit`). */
+export function transportOutboxStore(transport, sessionKey) {
+    return {
+        append: (entries) => transport.appendOutbox(sessionKey, entries),
+        commit: (params) => transport.commit(sessionKey, params),
+    };
+}

package/dist/workstation/acp/patchAssets.js

@@ -20,9 +20,10 @@ function validateCondition(id, when, until, whenKey, untilKey) {
 export function validateOverride(entry) {
     validateCondition(entry.id, entry.when_registry_version, entry.until_registry_version, 'when_registry_version', 'until_registry_version');
     const until = entry.until_registry_version;
-    // A pin at or past its own bound would be replaced by the registry the moment it applied.
-    if (until !== undefined && entry.distribution && !(semver.valid(entry.distribution.version) && semver.lt(entry.distribution.version, until))) {
-        throw new Error(`Axom patch ${entry.id}: pinned ${entry.distribution.version} must sort below ${until}`);
+    // A catch-up pin may equal its bound: use it until the registry publishes that release.
+    // A pin above the bound would instead let the registry replace it with an older release.
+    if (until !== undefined && entry.distribution && !(semver.valid(entry.distribution.version) && semver.lte(entry.distribution.version, until))) {
+        throw new Error(`Axom patch ${entry.id}: pinned ${entry.distribution.version} must not sort above ${until}`);
     }
 }
 export function validatePackagePatch(recipe) {
@@ -61,3 +62,19 @@ export const packagePatches = runtime.package_patches.map((file) => {
     validatePackagePatch(recipe);
     return recipe;
 });
+/** The declared native wrappers, for the catalog↔patch consistency guard in `catalog.test.ts`. */
+export const nativeExtensions = runtime.native_extensions ?? [];
+/** The bundled overrides, for the same catalog↔patch consistency guard. */
+export const runtimeOverrides = runtime.overrides;
+/** Native wrappers are declared in the patch inventory, never selected by agent-specific launch branches. */
+export function nativeExtensionFor(agent, version) {
+    const extension = runtime.native_extensions?.find(entry => entry.agent === agent && entry.versions.includes(version));
+    if (!extension)
+        return undefined;
+    if (extension.entry.startsWith('/') || extension.entry.split('/').includes('..'))
+        throw new Error('Invalid native extension path');
+    return new URL(extension.entry, patchAssetRoot);
+}
+export function nativeAccountLimitsVersionFor(agent, version) {
+    return runtime.native_extensions?.find(entry => entry.agent === agent && entry.versions.includes(version))?.accountLimitsVersion ?? 2;
+}

package/dist/workstation/acp/permission.js

@@ -78,7 +78,6 @@
  * complete it, so `authenticate` remembers every id it handed out and retracts what is left when
  * the login settles.
  */
-import { randomUUID } from 'node:crypto';
 import { methods } from '@agentclientprotocol/sdk';
 import { validateWireEvent } from './validate.js';
 /** A value guaranteed not to equal any real `optionId` in `input.options` for a given call — used to purge a pending entry without accidentally supplying a matchable answer. Regenerated per call rather than a fixed literal, for the same anti-collision reasoning as `AcpSession`'s own abandonment sentinel (review finding, task-5 item 6). */
@@ -123,8 +122,9 @@ function toolCallPayload(toolCall) {
  * ACP `RequestPermissionRequest` (`types.gen.d.ts:108`) on Axom's wire: `{toolCall, options}` plus
  * `requestId`.
  *
- * `requestId` is a host-generated resolver token. The raw JSON-RPC ID stays local to its
- * connection; exact `sessionId` travels in the wire event's `acpSessionId` origin field.
+ * `requestId` is a host-derived resolver token — {@link permissionRequestId}, the same on the live
+ * path and in the ACP processor. The raw JSON-RPC ID stays local to its connection; exact `sessionId`
+ * travels in the wire event's `acpSessionId` origin field.
  *
  * **`toolCall` is nested, not flattened.** The flattened version lifted the tool's
  * `name`/`title`/`kind`/`arguments` to the top level, which put `name` (the tool's programmatic name,
@@ -135,7 +135,7 @@ function toolCallPayload(toolCall) {
  * `toolCall.title`, and the renderer computes it from the same field now
  * (`WorkTimelineInteractions.foldPermission`) instead of storing a second, drifting copy.
  */
-function buildPermissionRequestedEvent(input) {
+export function buildPermissionRequestedEvent(input) {
     return {
         eventName: 'permission_request',
         ...(input.sessionId !== undefined ? { acpSessionId: input.sessionId } : {}),
@@ -164,7 +164,7 @@ function buildPermissionRequestedEvent(input) {
  * `sink.answer` — the agent gave up on this specific request, so nothing should still expect an
  * answer for it. Session-level abandonment (the session closing, or the connection dying) is instead
  * `AcpSession`'s own job (`registerPendingApproval` resolving immediately when already closed, and
- * `runReadLoop` draining on an aborted connection) — see `acpSession.ts`.
+ * `runReadLoop` draining on an aborted connection) — see the old `acpSession.ts` (deleted in Task 29).
  *
  * The eventual answer is whatever string reaches `sink`'s registered resolver: normally one of
  * `input.options`' own `optionId`s (relayed from the user through `AcpSession.answer`), but both
@@ -320,7 +320,7 @@ function isFoldedCompanionKey(key, properties) {
  * each return `null` from `elicitationRequestFromPayload`, because `MODE_FORM` requires
  * `fields.isNotEmpty()`. Everything else it now decodes (see {@link handleFormElicitation}).
  */
-function elicitationFieldKeys(requestedSchema) {
+export function elicitationFieldKeys(requestedSchema) {
     const properties = requestedSchema?.properties;
     if (properties === null || typeof properties !== 'object' || Array.isArray(properties))
         return [];
@@ -336,7 +336,7 @@ function elicitationFieldKeys(requestedSchema) {
  * request is dropped server-side, which is why this check survived Task 9's removal of the
  * per-property profile predicate (see the ruling-R24 block below).
  */
-function isBlank(value) {
+export function isBlank(value) {
     return value.trim().length === 0;
 }
 /**
@@ -406,7 +406,7 @@ function isBlank(value) {
  * event always carries exactly what the agent asked; {@link handleFormElicitation} is what decides,
  * from that same schema, whether to wait for an answer or decline right after raising the card.
  */
-function buildElicitationRequestedEvent(request, requestId) {
+export function buildElicitationRequestedEvent(request, requestId) {
     return {
         eventName: 'elicitation_request',
         payload: {
@@ -521,6 +521,35 @@ async function handleFormElicitation(request, ctx, sink) {
 export function handleElicitationComplete(notification, deps) {
     deps.dismiss(notification.elicitationId);
 }
+/**
+ * The card id of one `session/request_permission`: `perm:<hostGeneration>:<JSON agent id>` (spec
+ * 2026-10-11 §5.4).
+ *
+ * ## Why derived, not random
+ *
+ * It used to be `randomUUID()` per invocation. A card id the server is already showing must still
+ * resolve after the daemon restarts underneath a live adapter, and a random id cannot: the re-presented
+ * request would get a new one, `settleApproval` ignores unknown ids, and the user's answer to the
+ * visible card would be lost (analysis A §4). Derived from the request itself, the same request gets
+ * the same id in every daemon generation, and the ACP processor — which may not draw randomness at
+ * all (`processor/guard.test.ts`) — computes it with this very function.
+ *
+ * ## Why it is still unique
+ *
+ * - `hostGeneration` identifies one adapter process: the keeper's `spawnId` on the processor path,
+ *   `AgentRuntimeDiagnostics.generation` (fresh per `connectAgent`) on today's live path — the same
+ *   value published as `callbackContext.hostGeneration`. A reconnect is a new process, so a new
+ *   generation: the agent's ids restart at 0 there without colliding with an earlier card.
+ * - Within one process the agent never reuses a pending JSON-RPC id. `JSON.stringify` keeps the
+ *   number `1` and the string `"1"` apart.
+ *
+ * Kept short enough for `AcpSession.registerPendingApproval`'s 256-byte rule for every id a real
+ * adapter sends; a pathological id longer than ~200 bytes is refused there, as an overlong
+ * `rpcRequestId` already was.
+ */
+export function permissionRequestId(hostGeneration, agentRequestId) {
+    return `perm:${hostGeneration}:${JSON.stringify(agentRequestId)}`;
+}
 /**
  * Register this module's three handlers onto `app`. Must run inside `connectAgent`'s `configure`
  * hook — see the file doc comment for why a post-connect `.onRequest`/`.onNotification` would compile
@@ -534,15 +563,18 @@ export function handleElicitationComplete(notification, deps) {
  * the call site instead. Its own `present` may still be omitted (see {@link PresentElicitationUrl}) —
  * that is `acpAgents.ts`'s session connection saying, on purpose, that a `url` elicitation raised
  * outside a login has nowhere to go, and it declines rather than accepting into nothing.
+ *
+ * `connection.generation` is the adapter process's generation — `connectAgent` hands it to its
+ * `configure` hook — and scopes the card ids {@link permissionRequestId} derives.
  */
-export function registerPermissionHandlers(app, sink, elicitationDeps) {
+export function registerPermissionHandlers(app, sink, elicitationDeps, connection) {
     app
         .onRequest(methods.client.session.requestPermission, async (ctx) => {
         if (typeof ctx.params.sessionId !== 'string' || !ctx.params.sessionId.trim()) {
             console.error(JSON.stringify({ component: 'acp', error: 'invalid_permission_origin', rpcRequestId: String(ctx.requestId) }));
             return { outcome: { outcome: 'cancelled' } };
         }
-        const decision = await handleRequestPermission({ requestId: randomUUID(), rpcRequestId: String(ctx.requestId), sessionId: ctx.params.sessionId, toolCall: ctx.params.toolCall, options: ctx.params.options, signal: ctx.signal }, sink);
+        const decision = await handleRequestPermission({ requestId: permissionRequestId(connection.generation, ctx.requestId), rpcRequestId: String(ctx.requestId), sessionId: ctx.params.sessionId, toolCall: ctx.params.toolCall, options: ctx.params.options, signal: ctx.signal }, sink);
         return {
             outcome: decision.outcome === 'answered' ? { outcome: 'selected', optionId: decision.optionId } : { outcome: 'cancelled' },
         };

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

@@ -0,0 +1,87 @@
+/**
+ * Processor checkpoints (spec 2026-10-11 §5.5): the state after record `offset`, as JSON.
+ *
+ * ## Two versions, two questions
+ *
+ * - `schema` answers "can this daemon **read** it?". An unknown schema throws
+ *   {@link CheckpointUnreadableError}; the caller then replays from the session's start (outbox and
+ *   watermark cover the frames already sent), or, if the log was truncated, marks the session
+ *   degraded and switches it at the next open (§5.5.6). Readability of older schemas is a test-guarded
+ *   promise: never change the meaning of an existing field without bumping `schema` and adding a
+ *   reader for the old one.
+ * - `processorVersion` answers "would **this** code have produced the same frames?". Bump it whenever
+ *   `step` can emit different output for the same records. A readable checkpoint from another
+ *   processor version is still restored — that is the whole point of cutting a head checkpoint at
+ *   upgrade — but the caller must not count replay-vs-outbox differences as divergence then.
+ *
+ * Checkpoints are cut only on record boundaries (a synchronous `step` leaves no half-processed record)
+ * and carry no secrets (`state.ts`).
+ */
+import { PROCESSOR_STATE_SCHEMA } from './state.js';
+/**
+ * Bump when `step`'s output for the same records changes. 2: Task 17a (turns, cards, `seq`; prompt
+ * methods refused by `rpc.request`). 3: Task 17b (`session/update` mapped, the open session bound
+ * from its response, config/steer/levels; events validated before numbering). 4: commands carry
+ * their `spawnId`; `processor.history_end` carries `droppedCount`; a prompt closes open history.
+ * 5: Task 17c (the callback snapshot in the runtime diagnostics and its revision bumps; Qoder SDK
+ * cards carry a `callbackContext`; the Qoder adapter boundaries; side-channel notes). 6: a process call's
+ * result waits for its child's first status; ended/delivered calls keep no dead data.
+ * 7: Task 20 — the `agent_install_outcome` note becomes a `step` event (it was an unknown note).
+ * 8: Task 21 — a level update after a load's response is folded live, not as history; the `agent_output_gap` note is a `step`.
+ */
+export const PROCESSOR_VERSION = 8;
+export const CHECKPOINT_SCHEMA = 1;
+export class CheckpointUnreadableError extends Error {
+}
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/** A detached copy of `state`, so later steps cannot reach into a checkpoint already handed out. */
+export function checkpointOf(state) {
+    return { schema: CHECKPOINT_SCHEMA, processorVersion: PROCESSOR_VERSION, offset: state.offset, state: clone(state) };
+}
+export function encodeCheckpoint(checkpoint) {
+    return JSON.stringify(checkpoint);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Parse and check a checkpoint blob (string or already-parsed JSON). */
+export function decodeCheckpoint(blob) {
+    let value = blob;
+    if (typeof blob === 'string') {
+        try {
+            value = JSON.parse(blob);
+        }
+        catch {
+            throw new CheckpointUnreadableError('checkpoint is not JSON');
+        }
+    }
+    if (!isRecord(value))
+        throw new CheckpointUnreadableError('checkpoint is not an object');
+    if (value.schema !== CHECKPOINT_SCHEMA)
+        throw new CheckpointUnreadableError(`unknown checkpoint schema ${JSON.stringify(value.schema)}`);
+    const { processorVersion, offset, state } = value;
+    if (typeof processorVersion !== 'number' || !Number.isInteger(processorVersion))
+        throw new CheckpointUnreadableError('checkpoint has no processorVersion');
+    if (typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < -1)
+        throw new CheckpointUnreadableError('checkpoint offset is invalid');
+    if (!isRecord(state) || state.schema !== PROCESSOR_STATE_SCHEMA)
+        throw new CheckpointUnreadableError('checkpoint state schema is unknown');
+    if (state.offset !== offset)
+        throw new CheckpointUnreadableError('checkpoint offset disagrees with its state');
+    for (const key of ['process', 'initialize', 'outbound', 'inbound', 'diagnostics', 'permissions', 'elicitations',
+        'permissionOrigins', 'permissionParents', 'unresolvedPermissionOrigins', 'open', 'mapperScopes', 'message', 'steers',
+        'asyncTasks', 'runtime', 'callbacks', 'boundaries']) {
+        if (!isRecord(state[key]))
+            throw new CheckpointUnreadableError(`checkpoint state has no ${key}`);
+    }
+    if (typeof state.seq !== 'number' || !Array.isArray(state.turns) || !Array.isArray(state.settledPermissions)) {
+        throw new CheckpointUnreadableError('checkpoint state has no session layer (seq/turns)');
+    }
+    if (!Array.isArray(state.steered) || !('configOptions' in state) || !('delegation' in state) || !('history' in state)
+        || !('activity' in state)) {
+        throw new CheckpointUnreadableError('checkpoint state has no open-session layer (Task 17b)');
+    }
+    return { schema: CHECKPOINT_SCHEMA, processorVersion, offset, state: clone(state) };
+}

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

@@ -0,0 +1,35 @@
+/** The line to write for `command`: `fill`ed from `resolve`, or `undefined` if its blocks are gone. */
+export function materializeLine(command, resolve) {
+    if (command.fill === undefined)
+        return command.line;
+    const blocks = resolve?.(command.fill.blocksRef);
+    if (blocks === undefined)
+        return undefined;
+    const message = JSON.parse(command.line);
+    // Assigning an existing key keeps its position: the line keeps the SDK's key order.
+    message.params.prompt = blocks;
+    return JSON.stringify(message);
+}
+export function executeDownCommands(sink, commands, resolve) {
+    const written = [];
+    const dropped = [];
+    const refused = [];
+    const unresolved = [];
+    for (const command of commands) {
+        if (sink.hasDown(command.cause)) {
+            dropped.push(command);
+            continue;
+        }
+        const line = materializeLine(command, resolve);
+        if (line === undefined) {
+            unresolved.push(command);
+            continue;
+        }
+        const { fill: _fill, ...rest } = command;
+        if (sink.writeDown({ ...rest, line }) === 'refused')
+            refused.push(command);
+        else
+            written.push(command);
+    }
+    return { written, dropped, refused, unresolved };
+}