@vincemakes/kiso-runtime 0.1.36 → 0.1.37

package/dist/recovery-plan.d.ts

@@ -0,0 +1,74 @@
+/**
+ * R-F 0.1.46 — the recovery plan: recovery as pure projection. From the
+ * durable event prefix the plan derives THE unique safe next step — never
+ * the adjudication itself (the approval pipeline stays in the runtime driver
+ * layer, run.ts). Purity: no I/O, no ID generation, no time — the same
+ * prefix always derives the same plan. The driver consumes one action at a
+ * time and re-derives after every append: the recovery is a loop over this
+ * projection, not a second state machine (the R-F thesis — fresh execution
+ * and resume walk the same ordinary program).
+ *
+ * The action vocabulary (the R-F directive):
+ *   COMPLETED              — no open run: nothing to recover
+ *   TERMINAL               — the open run reached its terminal
+ *   WAIT_PERMISSION(seq)   — a stored request awaits the human
+ *   DECIDE_PERMISSION(seq) — a committed call re-enters the approval pipeline
+ *   EXECUTE(seq)           — a durable approval authorizes the persisted call
+ *   RESOLVE_UNCERTAIN(id)  — a started execution with no receipt: the crash
+ *                            window — the human decides (never auto-rerun)
+ *   REPAIR_RESULT(id|seq)  — the model-facing result is missing: complete it
+ *                            from the durable fact (the receipt or the denial)
+ *   FILL_RESOLUTION(id)    — a resolution's model-facing fill is missing
+ *   ABANDON_DRAFT(from)    — a text-bearing no-stop suffix: void it (the
+ *                            driver appends the marker AND expires the voided
+ *                            requests — one deterministic step, sentence 3)
+ *   CONTINUE_MODEL         — nothing left to repair: drive the loop
+ *
+ * The derivation order is the R-E recovery's phase order (the zero-behavior
+ * proof: the prefix-table gate and the healing fixtures run unchanged):
+ * terminal > completed > uncertain > draft > invocations (the Gap A calls,
+ * then the stored requests) > receipt repairs > resolution fills > continue.
+ *
+ * Inputs: `events` — the session's full event prefix (the log); `scope` —
+ * the open run's stored events at resume start (the run boundaries). Both
+ * are pure inputs; the caller loads them.
+ */
+import type { Event } from "@vincemakes/kiso-core";
+export type RecoveryAction = {
+    readonly kind: "COMPLETED";
+} | {
+    readonly kind: "TERMINAL";
+} | {
+    readonly kind: "WAIT_PERMISSION";
+    readonly invocationSeq: number;
+} | {
+    readonly kind: "DECIDE_PERMISSION";
+    readonly invocationSeq: number;
+} | {
+    readonly kind: "EXECUTE";
+    readonly invocationSeq: number;
+}
+/** The receipt repair (executionId) or the durable-denial repair (invocationSeq). */
+ | {
+    readonly kind: "REPAIR_RESULT";
+    readonly executionId?: string;
+    readonly invocationSeq?: number;
+} | {
+    readonly kind: "RESOLVE_UNCERTAIN";
+    readonly executionId: string;
+} | {
+    readonly kind: "FILL_RESOLUTION";
+    readonly executionId: string;
+} | {
+    readonly kind: "ABANDON_DRAFT";
+    readonly voidFromSeq: number;
+} | {
+    readonly kind: "CONTINUE_MODEL";
+};
+/** A request's framework identity: its own invocationSeq, or the old-log
+ *  fallback (the last same-callId call before the request, in the scope). */
+export declare function invocationSeqOf(request: Event & {
+    type: "permission_requested";
+}, scope: readonly Event[]): number | undefined;
+/** The one safe next step for the durable prefix (derivation order above). */
+export declare function deriveRecoveryPlan(events: readonly Event[], scope: readonly Event[]): RecoveryAction;

package/dist/recovery-plan.js

@@ -0,0 +1,209 @@
+/**
+ * R-F 0.1.46 — the recovery plan: recovery as pure projection. From the
+ * durable event prefix the plan derives THE unique safe next step — never
+ * the adjudication itself (the approval pipeline stays in the runtime driver
+ * layer, run.ts). Purity: no I/O, no ID generation, no time — the same
+ * prefix always derives the same plan. The driver consumes one action at a
+ * time and re-derives after every append: the recovery is a loop over this
+ * projection, not a second state machine (the R-F thesis — fresh execution
+ * and resume walk the same ordinary program).
+ *
+ * The action vocabulary (the R-F directive):
+ *   COMPLETED              — no open run: nothing to recover
+ *   TERMINAL               — the open run reached its terminal
+ *   WAIT_PERMISSION(seq)   — a stored request awaits the human
+ *   DECIDE_PERMISSION(seq) — a committed call re-enters the approval pipeline
+ *   EXECUTE(seq)           — a durable approval authorizes the persisted call
+ *   RESOLVE_UNCERTAIN(id)  — a started execution with no receipt: the crash
+ *                            window — the human decides (never auto-rerun)
+ *   REPAIR_RESULT(id|seq)  — the model-facing result is missing: complete it
+ *                            from the durable fact (the receipt or the denial)
+ *   FILL_RESOLUTION(id)    — a resolution's model-facing fill is missing
+ *   ABANDON_DRAFT(from)    — a text-bearing no-stop suffix: void it (the
+ *                            driver appends the marker AND expires the voided
+ *                            requests — one deterministic step, sentence 3)
+ *   CONTINUE_MODEL         — nothing left to repair: drive the loop
+ *
+ * The derivation order is the R-E recovery's phase order (the zero-behavior
+ * proof: the prefix-table gate and the healing fixtures run unchanged):
+ * terminal > completed > uncertain > draft > invocations (the Gap A calls,
+ * then the stored requests) > receipt repairs > resolution fills > continue.
+ *
+ * Inputs: `events` — the session's full event prefix (the log); `scope` —
+ * the open run's stored events at resume start (the run boundaries). Both
+ * are pure inputs; the caller loads them.
+ */
+import { executionLedger } from "./ledger.js";
+/** The committed boundaries of a run's events (Gap B's boundary list). */
+const isBoundary = (e) => e.type === "stop" ||
+    e.type === "user_input" ||
+    e.type === "terminal" ||
+    e.type === "microcompacted" ||
+    e.type === "compacted" ||
+    e.type === "summarized" ||
+    e.type === "model_output_abandoned";
+/** A request's framework identity: its own invocationSeq, or the old-log
+ *  fallback (the last same-callId call before the request, in the scope). */
+export function invocationSeqOf(request, scope) {
+    if (request.invocationSeq !== undefined)
+        return request.invocationSeq;
+    let seq;
+    for (const e of scope) {
+        if (e.type === "tool_call_end" && e.callId === request.callId && e.seq < request.seq)
+            seq = e.seq;
+    }
+    return seq;
+}
+/** The events of the open run INCLUDING the recovery's own appends — the
+ *  scope plus everything the driver appended after it (seq is global and
+ *  monotonic, so the tail is exactly the appends). */
+function openRunEvents(events, scope) {
+    if (scope.length === 0)
+        return events;
+    const lastScopeSeq = scope[scope.length - 1].seq;
+    const tail = events.filter((e) => e.seq > lastScopeSeq);
+    return [...scope, ...tail];
+}
+/** The one safe next step for the durable prefix (derivation order above). */
+export function deriveRecoveryPlan(events, scope) {
+    // 1. the open run reached its terminal → done. The terminal may be in the
+    //    scope (a resume adopted a run the loop completed in a previous
+    //    process) or in the driver's own tail (the continuation's terminal).
+    if (openRunEvents(events, scope).some((e) => e.type === "terminal"))
+        return { kind: "TERMINAL" };
+    // 2. nothing open → nothing to recover.
+    if (scope.length === 0)
+        return { kind: "COMPLETED" };
+    // 3. the crash window: a started execution with no receipt is the human's
+    //    (never auto-rerun — the prefix-table gate's row 7). The FIRST in log
+    //    order blocks; the driver throws with the full list. A receipted
+    //    execution is an outcome (ruling #12 / the α ruling: the audit keeps
+    //    it) — never uncertain.
+    const uncertain = [...executionLedger(events).values()].filter((r) => r.status === "uncertain");
+    if (uncertain.length > 0)
+        return { kind: "RESOLVE_UNCERTAIN", executionId: uncertain[0].executionId };
+    // 4. Gap B: a text-bearing no-stop suffix is an abandoned draft — void it.
+    //    Text-only detection (the 0.1.44 verification): a bare tool-call
+    //    suffix is the legal approval-panel pause, never a draft. The
+    //    boundary/draft scans run over the OPEN RUN's events INCLUDING the
+    //    driver's own appends — the driver re-derives after every append,
+    //    and the marker IT appended must already be the last boundary (the
+    //    old one-pass Gap B never needed this: it ran before any append).
+    const openEvents = openRunEvents(events, scope);
+    const boundary = [...openEvents].reverse().find(isBoundary);
+    if (boundary !== undefined) {
+        const afterBoundary = openEvents.some((e) => (e.type === "text_delta" || e.type === "thinking") && e.seq > boundary.seq);
+        // The approval-panel pause: a suffix that carries a pending ask of the
+        // LIVE turn — the last boundary is the user_input, no stop since — is
+        // the human's pause, never a draft: the call was extracted and asked,
+        // the request is durable, the WAIT_PERMISSION step re-announces it.
+        // (The loop persists the stream's tail AFTER the pause resolves, so a
+        // crash mid-pause leaves exactly this shape.) A request AFTER a STOP
+        // is different: it is the draft's own ask (0143's shape) — the marker
+        // voids it and the request expires with the draft.
+        const liveAsk = afterBoundary &&
+            boundary.type === "user_input" &&
+            openEvents.some((e) => e.type === "permission_requested" && e.seq > boundary.seq);
+        if (afterBoundary && !liveAsk)
+            return { kind: "ABANDON_DRAFT", voidFromSeq: boundary.seq };
+    }
+    // 5. the invocations: the Gap A calls first (scope order), then the
+    //    stored requests (scope order, then this recovery's own asks). Each:
+    //    undecided → the pipeline must decide; decided-approved without an
+    //    execution → execute the persisted call; decided-denied without a
+    //    model-facing result → repair it from the denial.
+    const hasRequest = (callId, after) => events.some((e) => e.type === "permission_requested" && e.callId === callId && e.seq > after);
+    const hasExecution = (callId, after) => events.some((e) => e.type === "tool_execution_started" && e.callId === callId && e.seq > after);
+    const hasResult = (callId, after) => events.some((e) => e.type === "tool_result" && e.callId === callId && e.seq > after);
+    const decidedForCall = (callId, after) => {
+        for (const e of events) {
+            if (e.type !== "permission_decided")
+                continue;
+            // a durable POLICY verdict binds the call (E1); a human verdict
+            // binds its request, never the call (the requests pass owns it)
+            if (e.decidedBy !== undefined && e.callId === callId && e.seq > after)
+                return e;
+        }
+        return undefined;
+    };
+    const decidedForRequest = (decisionId) => {
+        for (const e of events) {
+            if (e.type === "permission_decided" && e.decisionId === decisionId)
+                return e;
+        }
+        return undefined;
+    };
+    for (const call of scope) {
+        if (call.type !== "tool_call_end")
+            continue;
+        // the boundary clause: a call whose turn has no legal stop is a
+        // DRAFT's call — Gap B voids it; this pass never touches it.
+        const turnEnd = scope.find((e) => e.type === "user_input" && e.seq > call.seq)?.seq ?? Number.POSITIVE_INFINITY;
+        if (!scope.some((e) => e.type === "stop" && e.seq > call.seq && e.seq < turnEnd))
+            continue;
+        // a stored request owns the invocation (the requests pass below) —
+        // "only a durable permission_decided authorizes an effect"; Gap A
+        // must never re-decide over a stored request.
+        if (hasRequest(call.callId, call.seq))
+            continue;
+        if (hasResult(call.callId, call.seq))
+            continue; // closed — nothing to fill
+        const decided = decidedForCall(call.callId, call.seq);
+        if (decided === undefined)
+            return { kind: "DECIDE_PERMISSION", invocationSeq: call.seq };
+        if (decided.decision === "approved") {
+            if (!hasExecution(call.callId, call.seq))
+                return { kind: "EXECUTE", invocationSeq: call.seq };
+        }
+        else if (!hasResult(call.callId, call.seq)) {
+            return { kind: "REPAIR_RESULT", invocationSeq: call.seq };
+        }
+    }
+    const lastScopeSeq = scope.length > 0 ? scope[scope.length - 1].seq : -1;
+    const requests = [
+        ...scope.filter((e) => e.type === "permission_requested"),
+        // this recovery's own asks (the Gap A ask appends) — the log tail
+        ...events.filter((e) => e.type === "permission_requested" && e.seq > lastScopeSeq),
+    ];
+    for (const pending of requests) {
+        const invocationSeq = invocationSeqOf(pending, scope);
+        // a voided request was expired by the ABANDON_DRAFT step (sentence 3:
+        // never re-presented, never executed) — skip it here.
+        if (invocationSeq !== undefined &&
+            events.some((e) => e.type === "model_output_abandoned" && invocationSeq > e.voidFromSeq && invocationSeq <= e.seq)) {
+            continue;
+        }
+        const decided = decidedForRequest(pending.decisionId);
+        if (decided === undefined) {
+            return { kind: "WAIT_PERMISSION", invocationSeq: invocationSeq ?? pending.seq };
+        }
+        if (decided.decision === "approved") {
+            if (!hasExecution(pending.callId, pending.seq))
+                return { kind: "EXECUTE", invocationSeq: invocationSeq ?? pending.seq };
+        }
+        else if (!hasResult(pending.callId, pending.seq)) {
+            return { kind: "REPAIR_RESULT", invocationSeq: invocationSeq ?? pending.seq };
+        }
+    }
+    // 6. the receipt repairs: an execution that reached a terminal state
+    //    whose model-facing result never landed — complete it FROM THE
+    //    RECEIPT, never re-executed.
+    for (const ev of scope) {
+        if (ev.type !== "tool_execution_succeeded" && ev.type !== "tool_execution_failed")
+            continue;
+        if (!hasResult(ev.callId, ev.seq) && !events.some((e) => e.type === "tool_result" && e.executionId === ev.executionId)) {
+            return { kind: "REPAIR_RESULT", executionId: ev.executionId };
+        }
+    }
+    // 7. the resolution fills: a persisted resolution whose model-facing fill
+    //    never landed — the model must never stare at a dangling tool_use.
+    for (const ev of scope) {
+        if (ev.type !== "tool_execution_resolved")
+            continue;
+        if (!events.some((e) => e.type === "tool_result" && e.executionId === ev.executionId)) {
+            return { kind: "FILL_RESOLUTION", executionId: ev.executionId };
+        }
+    }
+    // 8. nothing left to repair — the loop drives from here.
+    return { kind: "CONTINUE_MODEL" };
+}

package/dist/run.js

@@ -5,6 +5,7 @@
  */
 import { denialResult, loop } from "@vincemakes/kiso-core";
 import { ABORTED, MergedSignal, abortable, openRunId } from "./recovery.js";
+import { deriveRecoveryPlan, invocationSeqOf } from "./recovery-plan.js";
 import { composeApprovalChain, composeSystemPrompt, composeToolTable, microcompactFor } from "./compose.js";
 import { truncationGuard } from "./truncation-guard.js";
 import { ResumeBlockedError } from "./session.js";
@@ -160,11 +161,9 @@ export class Run {
                         await this.#session.persist(runId, expired);
                     }
                 }
-                // Uncertain executions block until a human decides.
-                const uncertain = this.#session.uncertainExecutions();
-                if (uncertain.length > 0) {
-                    throw new ResumeBlockedError(uncertain.map((u) => ({ executionId: u.executionId, callId: u.callId, name: u.name })));
-                }
+                // Uncertain executions block until a human decides — the
+                // recovery plan derives RESOLVE_UNCERTAIN and the driver
+                // throws below (same list, same order; R-F 0.1.46).
                 // 1. Recovery scoped to the LAST OPEN RUN's events. The recover
                 //    phase re-announces ALREADY-PERSISTED events (the stored
                 //    permission_requested) for the consumer to re-prompt on —
@@ -234,351 +233,392 @@ export class Run {
             this.#session.endRun(this);
         }
     }
-    // ── Area 2: the durable recovery state machine ───────────────────────
+    // ── Area 2: the recovery — a thin driver over the recovery plan ───────
+    // R-F 0.1.46: recovery is a PURE PROJECTION (recovery-plan.ts) consumed
+    // by this driver. The durable prefix derives THE one safe next step;
+    // the driver executes it and re-derives. The old state machine's phases
+    // are now action cases — the prefix-table gate and the healing fixtures
+    // run unchanged (the zero-behavior proof), and each phase's semantics
+    // live in the plan's derivation or in the step below.
     /**
-     * Apply every durable decision and fill every missing receipt, in log
-     * order. A decision with no execution yet EXECUTES the persisted call
-     * (its original name/input/callId — never re-asked of the model, never
-     * re-approved); a denial writes its tool result; a succeeded/failed
-     * execution whose tool_result never landed is completed from the
-     * receipt. Undecided requests pause and await approve().
-     *
-     * R-E 0.1.43 (Gap A): a committed turn's tool_call_end with no durable
-     * decision and no execution is UNDECIDED — recovery re-enters it into
-     * the approval pipeline before anything else (only a durable
-     * permission_decided authorizes an effect).
+     * Consume the recovery plan one action at a time: execute the derived
+     * step, re-derive, stop when nothing is left (CONTINUE_MODEL — the
+     * resume's continuation drives the loop from there). The steps write
+     * only what the plan derived; the NEXT derive applies it (EXECUTE /
+     * REPAIR_RESULT), so the recovery is a loop over the projection, never
+     * a second state machine. An abort that lands mid-step ends the
+     * recovery: re-deriving would re-present the same action forever (the
+     * steps' pre-execution abort guards rely on this).
      */
     async *#recover(log, signal, scope, approvalChain, hooks) {
-        // ── Gap B: the tail draft is abandoned — never committed history ──
-        // "A model output suffix without a committed stop is an incomplete
-        // draft and must never become committed provider history." The
-        // resume appends the abandon marker FIRST: it voids the range after
-        // the last committed boundary (stop / user_input / terminal /
-        // compaction / summarized — or an earlier marker), so the projection
-        // excludes the draft and a call inside it is never executed (the
-        // boundary clause: the two Gaps divide at the stop). The audit bytes
-        // stay; a marker is kernel-exclusive (the AdapterEvent whitelist).
-        // Idempotent: an already-voided draft has a marker as its last
-        // boundary — the detection finds no output after it, and the
-        // recovered events (decided/started/result) are no draft.
-        const boundary = [...scope].reverse().find((e) => e.type === "stop" ||
-            e.type === "user_input" ||
-            e.type === "terminal" ||
-            e.type === "microcompacted" ||
-            e.type === "compacted" ||
-            e.type === "summarized" ||
-            e.type === "model_output_abandoned");
-        if (boundary !== undefined) {
-            // R-E 0.1.44 (verified against sentence 2): the draft detection
-            // stays text-only — a bare tool-call suffix [tool_call_end,
-            // permission_requested] with no text is the legal approval-panel
-            // pause (the Area 2 contract: the pending request binds and
-            // executes, pair-closed — the extensions-e2e gate). The finding's
-            // shapes all carry text, and the VOID SCOPE (what the marker
-            // covers) is the type filter at project.ts: model output dies
-            // with the draft, the framework's facts never do.
-            const draft = scope.some((e) => (e.type === "text_delta" || e.type === "thinking") && e.seq > boundary.seq);
-            if (draft) {
-                yield log.append({
-                    type: "model_output_abandoned",
-                    voidFromSeq: boundary.seq,
-                    reason: "a model output suffix without a committed stop — abandoned on resume",
-                });
+        for (;;) {
+            const action = deriveRecoveryPlan(log.all, scope);
+            switch (action.kind) {
+                case "COMPLETED":
+                case "TERMINAL":
+                    return;
+                case "CONTINUE_MODEL":
+                    // Upgrade-path housekeeping (the old requests pass did it
+                    // at the first resume): a request voided by an EARLIER
+                    // marker whose expiry never landed — the pre-0.1.44 logs,
+                    // where the marker existed but the expiry did not — is
+                    // expired here. Idempotent: only the missing expiry is
+                    // written; the re-derive then skips the expired request.
+                    if (yield* this.#expireStaleVoidedRequests(scope, log))
+                        break;
+                    return;
+                case "RESOLVE_UNCERTAIN": {
+                    // The crash window: uncertain executions block until a
+                    // human decides (never auto-rerun). The full list goes to
+                    // the throw, in log order — the first in the plan's
+                    // derivation is the first in this list (the ledger's
+                    // insertion order).
+                    const uncertain = this.#session.uncertainExecutions();
+                    throw new ResumeBlockedError(uncertain.map((u) => ({ executionId: u.executionId, callId: u.callId, name: u.name })));
+                }
+                case "ABANDON_DRAFT":
+                    yield* this.#abandonDraft(action.voidFromSeq, scope, log);
+                    break;
+                case "DECIDE_PERMISSION":
+                    yield* this.#decidePermission(action.invocationSeq, scope, log, signal, approvalChain, hooks);
+                    break;
+                case "WAIT_PERMISSION":
+                    yield* this.#waitPermission(action.invocationSeq, scope, log, signal);
+                    break;
+                case "EXECUTE":
+                    yield* this.#executeInvocation(action.invocationSeq, scope, log, signal);
+                    break;
+                case "REPAIR_RESULT":
+                    if (action.executionId !== undefined)
+                        yield* this.#repairReceipt(action.executionId, scope, log);
+                    else
+                        yield* this.#repairDenial(action.invocationSeq, scope, log);
+                    break;
+                case "FILL_RESOLUTION":
+                    yield* this.#fillResolution(action.executionId, scope, log);
+                    break;
             }
+            if (signal.aborted)
+                return;
         }
-        // The invocation's framework identity (R-E 0.1.43): the
-        // tool_call_end's seq — carried by new logs, derived by
-        // callId+proximity for old ones (the last such call before the seq).
-        const callSeqOf = (callId, before) => {
-            let seq;
-            for (const e of scope) {
-                if (e.type === "tool_call_end" && e.callId === callId && e.seq < before)
-                    seq = e.seq;
-            }
-            return seq;
-        };
-        // ── Gap A: a committed turn's UNDECIDED invocation ────────────────
-        // A durable stop with a bare tool_call_end (no decision, no
-        // execution) re-enters the approval pipeline: the composed chain
-        // decides — allow → durable permission_decided (decidedBy
-        // faithfully) + the persisted execution; deny → decided + the
-        // denial result; ask/all-abstain → permission_requested (the
-        // requests pass below announces it and waits for the human). No
-        // guessing, no inheriting, no retro-authorization — re-decide.
-        // A durable POLICY verdict (E1: decidedBy set) newer than the call
-        // binds it — the chain never re-runs for a decided invocation.
-        const gapAsks = [];
-        for (const call of scope) {
-            if (call.type !== "tool_call_end")
+    }
+    /** The open run's stored requests PLUS this recovery's own asks — the
+     *  same list the plan's request pass derives over (scope order, then
+     *  the log tail in append order). */
+    #storedRequests(scope, log) {
+        const lastScopeSeq = scope.length > 0 ? scope[scope.length - 1].seq : -1;
+        return [
+            ...scope.filter((e) => e.type === "permission_requested"),
+            ...log.all.filter((e) => e.type === "permission_requested" && e.seq > lastScopeSeq),
+        ];
+    }
+    /** The invocation the plan keyed by seq — a committed call in the scope,
+     *  or a stored request (the old-log identity fallback included). */
+    #invocationFor(invocationSeq, scope, log) {
+        const call = scope.find((e) => e.type === "tool_call_end" && e.seq === invocationSeq);
+        if (call !== undefined)
+            return call;
+        return this.#storedRequests(scope, log).find((e) => (invocationSeqOf(e, scope) ?? e.seq) === invocationSeq);
+    }
+    /**
+     * The ABANDON_DRAFT step (Gap B): the marker voids the draft's range —
+     * model output only, the audit bytes stay, a call inside the range is
+     * never executed (the kernel's type filter keeps the framework's
+     * facts). The SAME step expires every stored request whose invocation
+     * falls in the voided range (sentence 3: never re-presented, never
+     * executed) — the old requests pass appended these later; the fold
+     * makes the void and its expiry ONE deterministic step. Idempotent: an
+     * already-expired request is never re-expired, and an already-voided
+     * draft derives no ABANDON_DRAFT (the marker is the last boundary).
+     */
+    async *#abandonDraft(voidFromSeq, scope, log) {
+        const marker = log.append({
+            type: "model_output_abandoned",
+            voidFromSeq,
+            reason: "a model output suffix without a committed stop — abandoned on resume",
+        });
+        yield marker;
+        for (const pending of scope) {
+            if (pending.type !== "permission_requested")
                 continue;
-            // The boundary clause (the directive): a call whose turn has no
-            // legal stop is a DRAFT's call — Gap B voids it (never executed,
-            // never in the provider projection); this stage never touches it.
-            // The two Gaps divide at the stop; no mixing.
-            const turnEnd = scope.find((e) => e.type === "user_input" && e.seq > call.seq)?.seq ?? Number.POSITIVE_INFINITY;
-            const turnStop = scope.some((e) => e.type === "stop" && e.seq > call.seq && e.seq < turnEnd);
-            if (!turnStop)
+            const invocationSeq = pending.invocationSeq ?? invocationSeqOf(pending, scope);
+            if (invocationSeq === undefined)
                 continue;
-            // The requests pass below owns request-tracked invocations (it
-            // binds the stored request by decisionId, or pauses for the
-            // human) — Gap A must never re-decide over a stored
-            // permission_requested. "Only a durable permission_decided
-            // authorizes an effect": a pending request is not a decision.
-            const hasRequest = log.all.some((e) => e.type === "permission_requested" && e.callId === call.callId && e.seq > call.seq);
-            if (hasRequest)
+            if (!(invocationSeq > voidFromSeq && invocationSeq <= marker.seq))
                 continue;
-            const decided = log.all.find((e) => e.type === "permission_decided" && e.callId === call.callId && e.seq > call.seq && e.decidedBy !== undefined);
-            const hasExecution = log.all.some((e) => e.type === "tool_execution_started" && e.callId === call.callId && e.seq > call.seq);
-            const hasResult = log.all.some((e) => e.type === "tool_result" && e.callId === call.callId && e.seq > call.seq);
-            if (hasResult)
-                continue; // closed — nothing to fill
-            if (decided !== undefined) {
-                // E1: the durable verdict speaks for the call — apply it
-                // without re-running the chain.
-                if (signal.aborted)
-                    return;
-                if (decided.decision === "approved" && !hasExecution) {
-                    yield* this.#executePersisted(call.callId, call.name, call.input ?? {}, call.seq, signal);
-                }
-                else if (!hasResult) {
-                    yield* this.#denialResult(call.callId, decided.reason ?? "denied by user", call.seq);
-                }
+            if (log.all.some((e) => e.type === "permission_expired" && e.decisionId === pending.decisionId))
                 continue;
-            }
-            // UNDECIDED — re-enter the approval pipeline with the LIVE
-            // decision order (loop.ts decideCall): the composed chain
-            // first; only when no chain exists do the hooks' onPreTool
-            // speak (defer → ask, deny → deny, allow → allow); no policies
-            // at all → the kernel's default allow. Same semantics as the
-            // live path — a defer policy must not collapse into an
-            // auto-allow on resume. A throwing chain counts as ask: it
-            // speaks, never silently (the live parity).
-            const payload = { callId: call.callId, name: call.name, input: call.input ?? {} };
-            // The chain's PolicyCall carries name+input only — callId is the
-            // framework's, the hook's is the provider-facing ToolCallPayload.
-            const policyCall = { name: payload.name, input: payload.input };
-            let verdict;
-            try {
-                if (approvalChain !== undefined) {
-                    const chainVerdict = await abortable(Promise.resolve(approvalChain.decide(policyCall, { signal, sessionId: this.#session.id })), signal);
-                    if (chainVerdict === ABORTED)
-                        return;
-                    verdict = chainVerdict;
-                }
-            }
-            catch {
-                verdict = { action: "ask" };
-            }
-            if (verdict === undefined && hooks?.onPreTool !== undefined) {
-                const decision = await abortable(Promise.resolve(hooks.onPreTool(payload, { sessionId: this.#session.id })), signal);
-                if (decision === ABORTED)
-                    return;
-                if (decision.action === "defer")
-                    verdict = { action: "ask" };
-                else if (decision.action !== "allow")
-                    verdict = { action: "deny", reason: decision.reason ?? "denied" };
-                else
-                    verdict = { action: "allow" };
-            }
-            if (verdict === undefined)
-                verdict = { action: "allow" }; // no policies — the kernel's default allow
-            const decisionId = `d-${log.all.length + 1}`;
-            if (verdict.action === "allow") {
-                yield log.append({
-                    type: "permission_decided",
-                    decisionId,
-                    callId: call.callId,
-                    invocationSeq: call.seq,
-                    decision: "approved",
-                    ...("decidedBy" in verdict ? { decidedBy: verdict.decidedBy } : {}),
-                });
-                if (signal.aborted)
+            yield log.append({
+                type: "permission_expired",
+                decisionId: pending.decisionId,
+                reason: "the invocation was abandoned with an incomplete draft — never re-presented, never executed",
+            });
+        }
+    }
+    /**
+     * The DECIDE_PERMISSION step (Gap A, undecided): the committed call
+     * re-enters the approval pipeline with the LIVE decision order
+     * (loop.ts decideCall) — the composed chain first; only when no chain
+     * exists do the hooks' onPreTool speak (defer → ask, deny → deny,
+     * allow → allow); no policies at all → the kernel's default allow. A
+     * throwing chain counts as ask: it speaks, never silently (the live
+     * parity). Only the DECISION is written here — the EXECUTE /
+     * REPAIR_RESULT steps apply it on the next derive. The ask's request
+     * is announced immediately (the consumer may answer; the
+     * WAIT_PERMISSION step re-announces and pauses when it did not).
+     */
+    async *#decidePermission(invocationSeq, scope, log, signal, approvalChain, hooks) {
+        const call = scope.find((e) => e.type === "tool_call_end" && e.seq === invocationSeq);
+        if (call === undefined)
+            throw new Error(`the recovery plan derived a call outside the scope (seq ${invocationSeq})`);
+        // The chain's PolicyCall carries name+input only — callId is the
+        // framework's, the hook's is the provider-facing ToolCallPayload.
+        const payload = { callId: call.callId, name: call.name, input: call.input ?? {} };
+        const policyCall = { name: payload.name, input: payload.input };
+        let verdict;
+        try {
+            if (approvalChain !== undefined) {
+                const chainVerdict = await abortable(Promise.resolve(approvalChain.decide(policyCall, { signal, sessionId: this.#session.id })), signal);
+                if (chainVerdict === ABORTED)
                     return;
-                yield* this.#executePersisted(call.callId, call.name, call.input ?? {}, call.seq, signal);
-            }
-            else if (verdict.action === "deny") {
-                yield log.append({
-                    type: "permission_decided",
-                    decisionId,
-                    callId: call.callId,
-                    invocationSeq: call.seq,
-                    decision: "denied",
-                    ...("reason" in verdict && verdict.reason !== undefined ? { reason: verdict.reason } : {}),
-                    ...("decidedBy" in verdict ? { decidedBy: verdict.decidedBy } : {}),
-                });
-                yield* this.#denialResult(call.callId, ("reason" in verdict && verdict.reason) || "denied", call.seq);
-            }
-            else {
-                // ask / all-abstain — the requests pass below announces the
-                // stored request and waits for the human.
-                const appended = log.append({
-                    type: "permission_requested",
-                    decisionId,
-                    callId: call.callId,
-                    invocationSeq: call.seq,
-                    name: call.name,
-                    input: call.input ?? {},
-                });
-                gapAsks.push(appended);
-                yield appended;
+                verdict = chainVerdict;
             }
         }
-        const requests = [...scope.filter((e) => e.type === "permission_requested"), ...gapAsks];
-        for (const pending of requests) {
-            // R-E 0.1.43: the writes below carry the invocation's framework
-            // identity — the request's own, or the callId+proximity
-            // fallback for old logs (the compat contract).
-            const invocationSeq = pending.invocationSeq ?? callSeqOf(pending.callId, pending.seq);
-            // R-E 0.1.44 (sentence 3): a stored request whose invocation is
-            // VOIDED is expired — never re-presented, never executed (the
-            // dead-run expiry precedent above). The void ranges come from
-            // log.all — the marker THIS recovery appended is included. The
-            // receipt stays in the audit; only the presentation is gone.
-            // An identity-less request (an old log where neither the field nor
-            // the callId+proximity fallback yields a seq) is never proven
-            // voided — it keeps the pre-0.1.44 behavior.
-            const voided = invocationSeq !== undefined &&
-                log.all.some((e) => e.type === "model_output_abandoned" && invocationSeq > e.voidFromSeq && invocationSeq <= e.seq);
-            if (voided) {
+        catch {
+            verdict = { action: "ask" };
+        }
+        if (verdict === undefined && hooks?.onPreTool !== undefined) {
+            const decision = await abortable(Promise.resolve(hooks.onPreTool(payload, { sessionId: this.#session.id })), signal);
+            if (decision === ABORTED)
+                return;
+            if (decision.action === "defer")
+                verdict = { action: "ask" };
+            else if (decision.action !== "allow")
+                verdict = { action: "deny", reason: decision.reason ?? "denied" };
+            else
+                verdict = { action: "allow" };
+        }
+        if (verdict === undefined)
+            verdict = { action: "allow" }; // no policies — the kernel's default allow
+        // The recovery's own decision is a POLICY verdict (the plan's E1
+        // rule: only a decidedBy-carrying decision binds the call — a human
+        // verdict binds its request, never the call). The driver's write
+        // must satisfy its own plan: no decidedBy → the re-derive would
+        // derive DECIDE_PERMISSION again forever (the plan cannot tell the
+        // driver's write from a human's). Stamped "mode:default" when the
+        // verdict carries none — the gates' seeded convention.
+        const decisionId = `d-${log.all.length + 1}`;
+        if (verdict.action === "allow") {
+            yield log.append({
+                type: "permission_decided",
+                decisionId,
+                callId: call.callId,
+                invocationSeq: call.seq,
+                decision: "approved",
+                decidedBy: "decidedBy" in verdict ? verdict.decidedBy : "mode:default",
+            });
+        }
+        else if (verdict.action === "deny") {
+            yield log.append({
+                type: "permission_decided",
+                decisionId,
+                callId: call.callId,
+                invocationSeq: call.seq,
+                decision: "denied",
+                ...("reason" in verdict && verdict.reason !== undefined ? { reason: verdict.reason } : {}),
+                decidedBy: "decidedBy" in verdict ? verdict.decidedBy : "mode:default",
+            });
+        }
+        else {
+            // ask / all-abstain — the WAIT_PERMISSION step announces the
+            // stored request and awaits the human.
+            yield log.append({
+                type: "permission_requested",
+                decisionId,
+                callId: call.callId,
+                invocationSeq: call.seq,
+                name: call.name,
+                input: call.input ?? {},
+            });
+        }
+    }
+    /**
+     * The WAIT_PERMISSION step (a stored request, undecided): the resolver
+     * is registered, the stored request announced, and the human's decision
+     * awaited. An abort during the wait ends the run — the request stays
+     * durable and pending, and a verdict given in the same instant as the
+     * abort is recorded exactly once (the round-4 adversarial path). Only
+     * the DECISION is written here — the EXECUTE / REPAIR_RESULT steps
+     * apply it on the next derive.
+     */
+    async *#waitPermission(invocationSeq, scope, log, signal) {
+        const pending = this.#storedRequests(scope, log).find((e) => (invocationSeqOf(e, scope) ?? e.seq) === invocationSeq);
+        if (pending === undefined)
+            throw new Error(`the recovery plan derived a request outside the log (seq ${invocationSeq})`);
+        const pendingDecision = new Promise((resolve) => {
+            this.#decisionIds.push(pending.decisionId);
+            this.#session.registerResolver(pending.decisionId, resolve);
+        });
+        yield pending;
+        // Area 4: an abort during the resumed approval wait ends the run;
+        // the request stays durable and pending.
+        if (signal.aborted) {
+            // round 5(P1-6): a verdict given in the same instant as the
+            // abort is still recorded — the abort must not bypass the
+            // durable fallback (aligned with the loop's abort path).
+            const verdict = this.#session.approvalVerdict(pending.decisionId);
+            if (verdict !== undefined) {
                 yield log.append({
-                    type: "permission_expired",
+                    type: "permission_decided",
                     decisionId: pending.decisionId,
-                    reason: "the invocation was abandoned with an incomplete draft — never re-presented, never executed",
+                    callId: pending.callId,
+                    decision: verdict ? "approved" : "denied",
+                    ...(verdict ? {} : { reason: "denied by user" }),
                 });
-                continue;
             }
-            const decided = log.all.find((e) => e.type === "permission_decided" && e.decisionId === pending.decisionId);
-            // round 4: paired by events NEWER than the request — a historical
-            // same-callId execution from an earlier run must not count as THIS
-            // request's execution (the provider callId may repeat across runs).
-            const hasExecution = log.all.some((e) => e.type === "tool_execution_started" && e.callId === pending.callId && e.seq > pending.seq);
-            const hasResult = log.all.some((e) => e.type === "tool_result" && e.callId === pending.callId && e.seq > pending.seq);
-            if (decided === undefined) {
-                // Pause: announce the stored request, await the human.
-                const pendingDecision = new Promise((resolve) => {
-                    this.#decisionIds.push(pending.decisionId);
-                    this.#session.registerResolver(pending.decisionId, resolve);
-                });
-                yield pending;
-                // Area 4: an abort during the resumed approval wait ends the
-                // run; the request stays durable and pending.
-                if (signal.aborted) {
-                    // round 5(P1-6): a verdict given in the same instant as the
-                    // abort is still recorded — the abort must not bypass the
-                    // durable fallback (aligned with the loop's abort path).
-                    const verdict = this.#session.approvalVerdict(pending.decisionId);
-                    if (verdict !== undefined) {
-                        yield log.append({
-                            type: "permission_decided",
-                            decisionId: pending.decisionId,
-                            callId: pending.callId,
-                            decision: verdict ? "approved" : "denied",
-                            ...(verdict ? {} : { reason: "denied by user" }),
-                        });
-                    }
-                    return;
-                }
-                const final = await abortable(pendingDecision, signal);
-                if (final === ABORTED) {
-                    // round 4 (adversarial): a verdict given in the same instant as the
-                    // abort is recorded (exactly once), never lost.
-                    const verdict = this.#session.approvalVerdict(pending.decisionId);
-                    if (verdict !== undefined) {
-                        yield log.append({
-                            type: "permission_decided",
-                            decisionId: pending.decisionId,
-                            callId: pending.callId,
-                            decision: verdict ? "approved" : "denied",
-                            ...(verdict ? {} : { reason: "denied by user" }),
-                        });
-                    }
-                    return;
-                }
-                // The decision is written here — exactly one writer per event.
+            return;
+        }
+        const final = await abortable(pendingDecision, signal);
+        if (final === ABORTED) {
+            // round 4 (adversarial): a verdict given in the same instant as
+            // the abort is recorded (exactly once), never lost.
+            const verdict = this.#session.approvalVerdict(pending.decisionId);
+            if (verdict !== undefined) {
                 yield log.append({
                     type: "permission_decided",
                     decisionId: pending.decisionId,
-                    callId: pending.callId, // binds the decision to the invocation (B group)
-                    decision: final.action === "allow" ? "approved" : "denied",
-                    ...(final.action === "deny" && final.reason !== undefined ? { reason: final.reason } : {}),
+                    callId: pending.callId,
+                    decision: verdict ? "approved" : "denied",
+                    ...(verdict ? {} : { reason: "denied by user" }),
                 });
-                if (final.action === "allow") {
-                    if (!hasExecution)
-                        yield* this.#executePersisted(pending.callId, pending.name, pending.input, invocationSeq, signal);
-                }
-                else if (!hasResult) {
-                    yield* this.#denialResult(pending.callId, final.reason ?? "denied by user", invocationSeq);
-                }
-            }
-            else if (decided.decision === "approved") {
-                // Decided while no process was running: apply without pausing.
-                // An abort during recovery must stop the pending executions,
-                // exactly like the live loop's sibling guard (finding 3).
-                if (signal.aborted)
-                    return;
-                if (!hasExecution)
-                    yield* this.#executePersisted(pending.callId, pending.name, pending.input, invocationSeq, signal);
             }
-            else if (!hasResult) {
-                yield* this.#denialResult(pending.callId, decided.reason ?? "denied by user", invocationSeq);
+            return;
+        }
+        // The decision is written here — exactly one writer per event.
+        yield log.append({
+            type: "permission_decided",
+            decisionId: pending.decisionId,
+            callId: pending.callId, // binds the decision to the invocation (B group)
+            decision: final.action === "allow" ? "approved" : "denied",
+            ...(final.action === "deny" && final.reason !== undefined ? { reason: final.reason } : {}),
+        });
+    }
+    /**
+     * The EXECUTE step: a durable approval authorizes the persisted call —
+     * the original name/input/callId (never re-asked of the model, never
+     * re-approved), the full ledgered lifecycle, and the ruling-#12
+     * receipt-as-outcome semantics.
+     */
+    async *#executeInvocation(invocationSeq, scope, log, signal) {
+        const invocation = this.#invocationFor(invocationSeq, scope, log);
+        if (invocation === undefined)
+            throw new Error(`the recovery plan derived an invocation outside the log (seq ${invocationSeq})`);
+        yield* this.#executePersisted(invocation.callId, invocation.name, invocation.input ?? {}, invocationSeq, signal);
+    }
+    /**
+     * The REPAIR_RESULT step for a receipt (executionId): an execution that
+     * reached a terminal state but whose model-facing result never landed
+     * is completed FROM THE RECEIPT — never re-executed. Pairing is by
+     * executionId (round 4) — a same-callId result from a different
+     * execution never suppresses the repair.
+     */
+    async *#repairReceipt(executionId, scope, log) {
+        const ev = scope.find((e) => (e.type === "tool_execution_succeeded" || e.type === "tool_execution_failed") && e.executionId === executionId);
+        if (ev === undefined)
+            throw new Error(`the recovery plan derived a receipt outside the scope (${executionId})`);
+        yield log.append(ev.type === "tool_execution_succeeded"
+            ? {
+                type: "tool_result",
+                callId: ev.callId,
+                content: ev.result.content,
+                isError: false,
+                // round 8: the repaired result reproduces the normal path
+                // losslessly — the tags ride on the durable receipt.
+                ...(ev.tags !== undefined ? { tags: ev.tags } : {}),
+                executionId: ev.executionId,
             }
+            : {
+                type: "tool_result",
+                callId: ev.callId,
+                content: ev.error,
+                isError: true,
+                ...(ev.errorKind !== undefined ? { errorKind: ev.errorKind } : {}),
+                ...(ev.tags !== undefined ? { tags: ev.tags } : {}),
+                executionId: ev.executionId,
+            });
+    }
+    /**
+     * The REPAIR_RESULT step for a durable denial (invocationSeq): the
+     * model-facing result of the denied invocation is completed from its
+     * durable permission_decided — no execution happened. The REQUEST is
+     * looked up first (its decision binds by decisionId — the human's
+     * verdict carries no decidedBy); the call fallback covers the Gap-A
+     * policy-verdict shape, which can only derive when NO request exists
+     * (Gap A never re-decides over a stored request).
+     */
+    async *#repairDenial(invocationSeq, scope, log) {
+        const request = this.#storedRequests(scope, log).find((e) => (invocationSeqOf(e, scope) ?? e.seq) === invocationSeq);
+        const call = scope.find((e) => e.type === "tool_call_end" && e.seq === invocationSeq);
+        const decided = log.all.find((e) => e.type === "permission_decided" &&
+            (request !== undefined
+                ? e.decisionId === request.decisionId
+                : call !== undefined && e.callId === call.callId && e.seq > call.seq && e.decidedBy !== undefined));
+        if (decided === undefined || (request?.callId ?? call?.callId) === undefined) {
+            throw new Error(`the recovery plan derived a denial without its decision (seq ${invocationSeq})`);
         }
-        // Receipt repair: an execution that reached a terminal state but
-        // whose model-facing result never landed is completed FROM THE
-        // RECEIPT — never re-executed. Snapshot the scope first: this phase
-        // appends the repaired results, and iterating a growing array would
-        // re-visit them. round 4: pairing is by executionId — a same-callId result
-        // from a different execution never suppresses the repair.
-        for (const ev of [...scope]) {
-            if (ev.type !== "tool_execution_succeeded" && ev.type !== "tool_execution_failed")
-                continue;
-            const hasResult = log.all.some((e) => e.type === "tool_result" && e.executionId === ev.executionId);
-            if (hasResult)
+        yield* this.#denialResult(request?.callId ?? call.callId, decided.reason ?? "denied by user", invocationSeq);
+    }
+    /**
+     * The FILL_RESOLUTION step: a resolution was persisted but its
+     * model-facing fill never landed — complete it so the model is never
+     * left staring at a dangling tool_use. Keyed by executionId; the fill
+     * carries it, so a same-callId result from another execution is never
+     * confused with this one (round 4).
+     */
+    async *#fillResolution(executionId, scope, log) {
+        const ev = scope.find((e) => e.type === "tool_execution_resolved" && e.executionId === executionId);
+        if (ev === undefined)
+            throw new Error(`the recovery plan derived a resolution outside the scope (${executionId})`);
+        const denial = denialResult(ev.resolution === "rerun"
+            ? "interrupted execution — rerun approved: the attempt is treated as NOT applied; the model may retry"
+            : "abandoned by human decision — the interrupted attempt must not be treated as applied");
+        yield log.append({
+            type: "tool_result",
+            callId: ev.callId,
+            content: denial.content,
+            isError: true,
+            errorKind: denial.errorKind,
+            executionId: ev.executionId,
+        });
+    }
+    /**
+     * The CONTINUE_MODEL housekeeping (called by the driver before the
+     * continuation): a request voided by an EARLIER marker whose expiry
+     * never landed — the pre-0.1.44 upgrade path, where the marker existed
+     * but the expiry did not — is expired here, exactly as the old requests
+     * pass did at the first resume. Returns whether anything was appended
+     * (the driver re-derives once; the plan then skips the expired
+     * request).
+     */
+    async *#expireStaleVoidedRequests(scope, log) {
+        let expired = false;
+        for (const pending of this.#storedRequests(scope, log)) {
+            const invocationSeq = invocationSeqOf(pending, scope);
+            if (invocationSeq === undefined)
                 continue;
-            yield log.append(ev.type === "tool_execution_succeeded"
-                ? {
-                    type: "tool_result",
-                    callId: ev.callId,
-                    content: ev.result.content,
-                    isError: false,
-                    // round 8: the repaired result reproduces the normal path
-                    // losslessly — the tags ride on the durable receipt.
-                    ...(ev.tags !== undefined ? { tags: ev.tags } : {}),
-                    executionId: ev.executionId,
-                }
-                : {
-                    type: "tool_result",
-                    callId: ev.callId,
-                    content: ev.error,
-                    isError: true,
-                    ...(ev.errorKind !== undefined ? { errorKind: ev.errorKind } : {}),
-                    ...(ev.tags !== undefined ? { tags: ev.tags } : {}),
-                    executionId: ev.executionId,
-                });
-        }
-        // B group crash window: a resolution was persisted but its tool_result
-        // fill never landed — complete it so the model is never left staring
-        // at a dangling tool_use. round 4: keyed by executionId, and the fill
-        // carries it, so a same-callId result from another execution is never
-        // confused with this one.
-        for (const ev of [...scope]) {
-            if (ev.type !== "tool_execution_resolved")
+            const voided = log.all.some((e) => e.type === "model_output_abandoned" && invocationSeq > e.voidFromSeq && invocationSeq <= e.seq);
+            if (!voided)
                 continue;
-            const hasResult = log.all.some((e) => e.type === "tool_result" && e.executionId === ev.executionId);
-            if (hasResult)
+            if (log.all.some((e) => e.type === "permission_expired" && e.decisionId === pending.decisionId))
                 continue;
-            const denial = denialResult(ev.resolution === "rerun"
-                ? "interrupted execution — rerun approved: the attempt is treated as NOT applied; the model may retry"
-                : "abandoned by human decision — the interrupted attempt must not be treated as applied");
             yield log.append({
-                type: "tool_result",
-                callId: ev.callId,
-                content: denial.content,
-                isError: true,
-                errorKind: denial.errorKind,
-                executionId: ev.executionId,
+                type: "permission_expired",
+                decisionId: pending.decisionId,
+                reason: "the invocation was abandoned with an incomplete draft — never re-presented, never executed",
             });
+            expired = true;
         }
+        return expired;
     }
     /**
      * Execute a call whose approval is already durable: the original

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-runtime",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "description": "kiso runtime — durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
   "type": "module",
   "license": "MIT",