@sema-agent/core 5.33.0 → 5.35.0

package/dist/core/park-selfcheck.d.ts

@@ -0,0 +1,156 @@
+/**
+ * design/252 G-6 — the LIVENESS half the wiring manifest deliberately does not have.
+ *
+ * The manifest's own §0 boundary says it: "this is STATIC ASSEMBLY SELF-DISCLOSURE — seam presence and
+ * shape, as facts. It does NOT prove liveness (a callback bound to the wrong run, a dead queue, an
+ * adapter's internal failure, an answer routed to the wrong instance). Liveness belongs to round-trip
+ * probes, which are a separate obligation." This module is that obligation for the PARK lane, and it
+ * quotes the boundary rather than dissolving it: a manifest reporting `parkLane.effective: true` over a
+ * store declaring `durability: "durable"` says a store is wired and what it CLAIMS. It cannot say the
+ * store accepts a row, returns the same row, and lets the fence win — which is the whole park contract,
+ * and the part a deployment gets wrong (a read-only mount, a serializer that drops a nested field, a
+ * scope column missing from the WHERE).
+ *
+ * TWO CHECKS, DIFFERENT KINDS, DELIBERATELY IN ONE MODULE:
+ *  · {@link probeParkRoundTrip} — the live probe: mint a synthetic parked row, read it back, verify the
+ *    load-bearing fields survived, fence it, confirm the fence landed.
+ *  · {@link durableParkGapOf} — the STATIC two-halves reading: a durable park is a durable checkpoint
+ *    store AND a durable session store, and a deployment with one of them is the configuration whose
+ *    failure mode is a resume that reports a missing session instead of the seat that is missing. One
+ *    module because they are one question asked at two costs, and a second home for "what does a whole
+ *    durable park need" is how the two answers drift.
+ *
+ * WHAT THE PROBE WRITES (read this before wiring it): it PUTs a real checkpoint row into the real
+ * store, under a scope of its own (`{@link PARK_SELFCHECK_SCOPE_PREFIX}<random>`) that no task ever
+ * uses, and fences it to `expired` on EVERY exit — including the failing ones, since a pending row is,
+ * to an approval inbox, an approval waiting for someone.
+ *
+ * The expired row then REMAINS, and remains permanently as far as this interface is concerned: there is
+ * no delete verb on `CheckpointStore`, and `reap` moves PENDING rows to expired rather than removing
+ * expired ones. So each probe run costs one small terminal row under one throwaway scope, and reclaiming
+ * them is the backend's own retention concern (a table TTL, a sweep keyed on the scope prefix). An inbox
+ * does not see them — `listByScope` enumerates pending rows only — but `listScopes` may still report the
+ * scope, and during the probe's own window the row is briefly enumerable and, in principle, resolvable
+ * by anything watching the whole store. Both are the price of probing the real lane rather than a
+ * pretend one; a deployment that cannot pay it should not run the probe, and there is no read-only
+ * variant because a read-only probe would prove exactly what the manifest already discloses.
+ */
+import type { RunnerDeps, TaskSpec } from "./types.js";
+/** The scope prefix every synthetic probe row is filed under — never a task scope, so a probe row can
+ *  never be mistaken for (or resolved as) a real pending approval. */
+export declare const PARK_SELFCHECK_SCOPE_PREFIX = "sema:park-selfcheck:";
+/**
+ * How long any single store call may take before the probe stops waiting and calls it a failure.
+ *
+ * A bound is MANDATORY rather than optional, for the reason this module exists at all: the probe is a
+ * DIAGNOSTIC for storage that may be sick, and the sickness it is most likely to meet — a connection
+ * that neither answers nor errors — is exactly the one an unbounded `await` turns into a wedged
+ * startup. A probe that hangs instead of reporting is worse than no probe: it fails in the shape it was
+ * written to detect, and silently.
+ */
+export declare const PARK_SELFCHECK_STEP_TIMEOUT_MS = 10000;
+/**
+ * How far in the FUTURE the synthetic row's abandonment deadline sits.
+ *
+ * A past deadline would make the row reapable the instant it is filed, and a CORRECT concurrent reaper
+ * could then expire it between the probe's own steps — reporting a healthy deployment as a broken one
+ * (the read that follows would see an expired row, or the enumeration an empty scope). A short future
+ * window keeps the row out of a reaper's reach for the length of the probe while still leaving any
+ * residue from a crashed probe reapable shortly after, without an operator doing anything.
+ */
+export declare const PARK_SELFCHECK_ROW_TTL_MS = 60000;
+/**
+ * The closed set of things a park round-trip can fail at. A machine keys on these; the accompanying
+ * `detail` is prose for a person and is never the discriminator.
+ *
+ * Ordered as the probe walks the contract, which is also the order an operator debugs in: a store that
+ * cannot be written is a different day's work from one that writes and then hands back a row with a
+ * dropped field.
+ */
+export type ParkProbeFindingCode = 
+/** `put` threw — the store did not accept a checkpoint at all. */
+"put_failed"
+/** `get` threw, or answered `null` for a token the store had just accepted. */
+ | "row_not_readable"
+/** The row came back, but a load-bearing field did not survive the round trip (see `detail` for which). */
+ | "row_not_faithful"
+/** The row came back with a status other than `pending` — a park nobody can resolve. */
+ | "row_not_pending"
+/** `listByScope` is implemented and did NOT list the pending row: the inbox enumeration is blind to it. */
+ | "row_not_enumerable"
+/** `expire` threw, or lost a CAS it was the only contender for — the fence the reaper and
+ *  `TaskStream.destroy` both depend on does not close. */
+ | "fence_failed"
+/** The fence reported a win and the row is still `pending` on a re-read: the CAS did not land. */
+ | "fence_not_durable";
+/** One thing that went wrong, with the prose a person needs to act on it. */
+export interface ParkProbeFinding {
+    readonly code: ParkProbeFindingCode;
+    readonly detail: string;
+}
+/**
+ * What one probe run concluded.
+ *
+ * `"round_trip_ok"` is the ONLY affirmative word, and it is only ever reported with an empty
+ * `findings` list — the invariant is asserted rather than assumed, because a probe whose failure can be
+ * read as a pass is worse than no probe (it is the manifest's disclosure wearing a verification's
+ * clothes, which is precisely what the §0 boundary forbids).
+ */
+export interface ParkSelfCheckResult {
+    readonly verdict: "round_trip_ok" | "failed" | "not_probed";
+    /** NON-EMPTY ⟺ `verdict === "failed"`. The two non-failing verdicts carry none: `"round_trip_ok"`
+     *  because nothing went wrong, `"not_probed"` because nothing was attempted (its reason is in
+     *  {@link summary} — a finding there would name a defect in a store that was never touched). */
+    readonly findings: readonly ParkProbeFinding[];
+    /** The scope the synthetic row was filed under, so an operator can find (and reap) the residue.
+     *  Present from the moment a write was ATTEMPTED — including a `put` that threw, because a backend can
+     *  commit and then surface a transport error, so a scope on a failed attempt is exactly where an
+     *  operator has to look. Absent only on `"not_probed"`, where nothing was attempted. */
+    readonly scope?: string;
+    /** A single sentence naming the outcome — for a startup log line. Never the machine discriminator. */
+    readonly summary: string;
+    /** The static two-halves reading taken alongside the probe (see {@link durableParkGapOf}); absent when
+     *  the durable topology is whole or does not apply. A probe can pass every round-trip check on a
+     *  deployment whose parks still cannot be resumed after a restart, and this is that fact. */
+    readonly durableTopologyGap?: string;
+    /** Additive, on `"round_trip_ok"` only: the expire CAS reported a LOSS while the row nonetheless
+     *  closed. From outside this is indistinguishable from the store's own housekeeping getting there
+     *  first — so the verdict stays green — but a backend that transitions the row and then mis-reports
+     *  the CAS win would pass on exactly this arm, and `TaskStream.destroy` trusts that boolean. A
+     *  machine-readable member rather than a summary sentence, so a harness that wants to alert on it
+     *  can (the summary is never the discriminator). */
+    readonly casLossObserved?: true;
+}
+/**
+ * design/252 G-6 (sibling finding, from the G-5 demo) — the DURABLE PARK's two halves, and the sentence
+ * to say when only one of them is wired.
+ *
+ * A park that survives a restart needs BOTH: the checkpoint row (the question) and the session (the
+ * conversation the answer resumes into). A deployment that wires a durable checkpoint store over the
+ * default in-memory session store parks perfectly and then, after a restart, fails the resume with
+ * "session … does not exist" — a SYMPTOM, reported at the seat that is present, naming nothing about
+ * the seat that is missing. Whoever reads that message goes looking for a lost session id.
+ *
+ * Returns the naming sentence, or `undefined` when there is nothing to say: both halves durable (whole),
+ * or no checkpoint store at all (the deployment is not doing durable parks, so there is no gap — the
+ * manifest's `parkLane.capable: false` is the fact there).
+ */
+export declare function durableParkGapOf(halves: {
+    checkpointDurable: boolean;
+    checkpointWired: boolean;
+    sessionDurable: boolean;
+}): string | undefined;
+/** The two-halves reading taken off a deployment's own seats. Split from {@link durableParkGapOf} so the
+ *  sentence can be unit-tested without a Runner and the seat reading has one home. */
+export declare function durableParkGapFor(deps: Pick<RunnerDeps, "checkpointStore" | "sessionStore">, spec?: Pick<TaskSpec, "checkpointStore">): string | undefined;
+/**
+ * design/252 G-6 — drive one synthetic park through the wired store and report what the assembly can
+ * actually DO, as opposed to what it declares.
+ *
+ * Never throws for a store's failure: every step's exception is captured into a {@link ParkProbeFinding}
+ * so a startup self-check can decide for itself whether a dead park lane is fatal. That decision is the
+ * deployment's, deliberately — this module reports, loudly and in a closed vocabulary, and does not
+ * legislate. What it will NOT do is report a pass it did not observe: `"round_trip_ok"` is returned only
+ * with an empty findings list, and the invariant is asserted below rather than left to reading.
+ */
+export declare function probeParkRoundTrip(deps: Pick<RunnerDeps, "checkpointStore" | "sessionStore">, spec?: Pick<TaskSpec, "checkpointStore">): Promise<ParkSelfCheckResult>;

package/dist/core/park-selfcheck.js

@@ -0,0 +1,251 @@
+import { boundInputHashOf, canonicalize } from "./canonical-json.js";
+import { MAX_SUPPORTED_CHECKPOINT_VERSION, mintCheckpointToken, resolveCheckpointStore } from "./checkpoint-store.js";
+import { resolveDeclaredDurability } from "./wiring-manifest.js";
+export const PARK_SELFCHECK_SCOPE_PREFIX = "sema:park-selfcheck:";
+export const PARK_SELFCHECK_STEP_TIMEOUT_MS = 10_000;
+export const PARK_SELFCHECK_ROW_TTL_MS = 60_000;
+async function within(op, step) {
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve()
+                .then(op)
+                .then((ok) => ({ ok }))
+                .catch((threw) => ({ threw })),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve({ timedOut: `${step} did not answer within ${PARK_SELFCHECK_STEP_TIMEOUT_MS}ms — a store that neither answers nor errors is the failure this probe exists to surface, not one it may wait on` }), PARK_SELFCHECK_STEP_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function declaresDurable(store, name) {
+    try {
+        return resolveDeclaredDurability(store, name) === "durable";
+    }
+    catch {
+        return false;
+    }
+}
+export function durableParkGapOf(halves) {
+    if (!halves.checkpointWired)
+        return undefined;
+    if (halves.checkpointDurable && halves.sessionDurable)
+        return undefined;
+    if (halves.checkpointDurable && !halves.sessionDurable) {
+        return ("this deployment wires a checkpoint store that declares durability but a session store that does not " +
+            "(RunnerDeps.sessionStore — absent means the built-in in-memory store): a durable park needs BOTH halves, " +
+            "so a parked approval survives the restart while the conversation it resumes into does not, and a resume " +
+            "arriving afterwards finds the checkpoint and not the session");
+    }
+    if (!halves.checkpointDurable && halves.sessionDurable) {
+        return ("this deployment wires a session store that declares durability but a checkpoint store that does not " +
+            "(RunnerDeps.checkpointStore.durability): a durable park needs BOTH halves, so the conversation survives " +
+            "the restart while the parked approval that was to resume it does not");
+    }
+    return undefined;
+}
+export function durableParkGapFor(deps, spec = {}) {
+    const checkpointStore = resolveCheckpointStore(spec, deps);
+    return durableParkGapOf({
+        checkpointWired: checkpointStore !== undefined,
+        checkpointDurable: declaresDurable(checkpointStore, "checkpointStore"),
+        sessionDurable: declaresDurable(deps.sessionStore, "sessionStore"),
+    });
+}
+function syntheticCheckpoint(scope) {
+    return {
+        token: mintCheckpointToken(),
+        scope,
+        sessionId: `${scope}:session`,
+        leafId: `${scope}:leaf`,
+        gate: { kind: "human", reason: "park wiring self-check (design/252 G-6) — no person is being asked", toolName: "SelfCheck" },
+        pendingAction: {
+            kind: "tool_approval",
+            toolCallId: `${scope}:call`,
+            toolName: "SelfCheck",
+            args: { probe: true, nested: { depth: 2, list: [1, 2, 3] } },
+            boundInputHash: boundInputHashOf({ probe: true, nested: { depth: 2, list: [1, 2, 3] } }),
+            batchToolCallIds: [`${scope}:call`],
+            completedCallIds: [],
+        },
+        state: { activeTools: ["SelfCheck"], nestedStats: { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0, anyUnpriced: false } },
+        status: "pending",
+        createdAt: Date.now(),
+        version: MAX_SUPPORTED_CHECKPOINT_VERSION,
+        suspendCount: 1,
+        suspendedAt: Date.now(),
+        resourceLedger: { spentMicroUsd: 0, spentTokens: 0, spentTurns: 0, sliceCount: 1 },
+        humanReview: { count: 1, totalWaitMs: 0, gates: [{ kind: "human", waitMs: 0, decision: "approve" }] },
+        sourceTaskId: `${scope}:task`,
+        principal: `${scope}:principal`,
+        durableApproval: { scope, ttlMs: PARK_SELFCHECK_ROW_TTL_MS },
+        deadline: Date.now() + PARK_SELFCHECK_ROW_TTL_MS,
+    };
+}
+function faithfulnessDelta(sent, got) {
+    const project = (cp) => ({
+        token: cp.token,
+        scope: cp.scope,
+        sessionId: cp.sessionId,
+        leafId: cp.leafId,
+        gate: cp.gate,
+        pendingAction: cp.pendingAction,
+        state: cp.state,
+        deadline: cp.deadline,
+        createdAt: cp.createdAt,
+        version: cp.version,
+        suspendCount: cp.suspendCount,
+        suspendedAt: cp.suspendedAt,
+        resourceLedger: cp.resourceLedger,
+        humanReview: cp.humanReview,
+        sourceTaskId: cp.sourceTaskId,
+        principal: cp.principal,
+        durableApproval: cp.durableApproval,
+    });
+    const a = canonicalize(project(sent));
+    const b = canonicalize(project(got));
+    return a === b ? undefined : `the row came back different from the row that was filed (sent ${a}; read ${b})`;
+}
+export async function probeParkRoundTrip(deps, spec = {}) {
+    const gap = durableParkGapFor(deps, spec);
+    const gapCell = gap !== undefined ? { durableTopologyGap: gap } : {};
+    const store = resolveCheckpointStore(spec, deps);
+    if (store === undefined) {
+        return {
+            verdict: "not_probed",
+            findings: [],
+            summary: "no checkpoint store is wired on this assembly — there is no park lane to probe (the manifest reports the same fact as parkLane.capable: false)",
+            ...gapCell,
+        };
+    }
+    const scope = `${PARK_SELFCHECK_SCOPE_PREFIX}${mintCheckpointToken()}`;
+    const cp = syntheticCheckpoint(scope);
+    const said = (err) => {
+        try {
+            const m = err instanceof Error ? err.message : undefined;
+            return typeof m === "string" ? m : `a ${typeof err} the store threw`;
+        }
+        catch {
+            return "a value the store threw that could not be described";
+        }
+    };
+    const shown = (v) => {
+        try {
+            return typeof v === "string" ? JSON.stringify(v) : `a ${typeof v}`;
+        }
+        catch {
+            return "an undescribable value";
+        }
+    };
+    const fenceQuietly = async () => {
+        await within(async () => {
+            try {
+                await store.expire(cp.token, scope);
+            }
+            catch {
+            }
+        }, "the cleanup fence");
+    };
+    const failed = async (code, detail) => {
+        await fenceQuietly();
+        return { verdict: "failed", findings: [{ code, detail }], scope, summary: `the park lane failed its round-trip self-check at "${code}": ${detail}`, ...gapCell };
+    };
+    let putStarted;
+    const put = await within(() => {
+        const p = Promise.resolve().then(() => store.put(cp.token, cp));
+        putStarted = p;
+        return p;
+    }, "put");
+    if ("timedOut" in put) {
+        void putStarted?.catch(() => { }).then(() => store.expire(cp.token, scope)).catch(() => { });
+        return await failed("put_failed", put.timedOut);
+    }
+    if ("threw" in put)
+        return await failed("put_failed", `the checkpoint store refused to file a synthetic park: ${said(put.threw)}`);
+    const first = await within(() => store.get(cp.token), "get");
+    if ("timedOut" in first)
+        return await failed("row_not_readable", first.timedOut);
+    if ("threw" in first)
+        return await failed("row_not_readable", `the checkpoint store threw reading back the row it had just accepted: ${said(first.threw)}`);
+    const read = first.ok;
+    if (read === null)
+        return await failed("row_not_readable", "the checkpoint store accepted the row and then answered null for its own token — a park filed here would be unresumable");
+    if (typeof read !== "object")
+        return await failed("row_not_readable", `the checkpoint store answered ${read === undefined ? "undefined" : typeof read} for its own token — neither a checkpoint nor the absence of one`);
+    let delta;
+    let status;
+    try {
+        delta = faithfulnessDelta(cp, read);
+        status = read.status;
+    }
+    catch (err) {
+        return await failed("row_not_faithful", `the row the store returned could not be read for comparison: ${said(err)}`);
+    }
+    if (delta !== undefined)
+        return await failed("row_not_faithful", delta);
+    if (status !== "pending")
+        return await failed("row_not_pending", `the filed row came back with status ${shown(status)} — a park in any other status is one nobody can resolve`);
+    const enumerable = store.listByScope !== undefined;
+    if (store.listByScope !== undefined) {
+        const listByScope = store.listByScope.bind(store);
+        const listed = await within(() => listByScope(scope), "listByScope");
+        if ("timedOut" in listed)
+            return await failed("row_not_enumerable", listed.timedOut);
+        if ("threw" in listed)
+            return await failed("row_not_enumerable", `listByScope threw for the probe's own scope: ${said(listed.threw)}`);
+        let present;
+        try {
+            present = Array.isArray(listed.ok) && listed.ok.some((row) => row?.token === cp.token);
+        }
+        catch (err) {
+            return await failed("row_not_enumerable", `the listByScope result could not be read: ${said(err)}`);
+        }
+        if (!present)
+            return await failed("row_not_enumerable", `listByScope("${scope}") did not include the pending row it holds — an inbox enumerating this scope would show no approvals`);
+    }
+    const fence = await within(() => store.expire(cp.token, scope), "expire");
+    if ("timedOut" in fence)
+        return await failed("fence_failed", fence.timedOut);
+    if ("threw" in fence)
+        return await failed("fence_failed", `expire threw on the probe's own pending row: ${said(fence.threw)}`);
+    const fenced = fence.ok === true;
+    const second = await within(() => store.get(cp.token), "get (after the fence)");
+    if ("timedOut" in second)
+        return await failed("fence_not_durable", second.timedOut);
+    if ("threw" in second)
+        return await failed("fence_not_durable", `the store threw re-reading the fenced row: ${said(second.threw)}`);
+    const after = second.ok;
+    let afterStatus;
+    if (after !== null) {
+        if (typeof after !== "object")
+            return await failed("fence_not_durable", `the store answered ${after === undefined ? "undefined" : typeof after} re-reading the fenced row — neither a checkpoint nor the absence of one`);
+        try {
+            afterStatus = after.status;
+        }
+        catch (err) {
+            return await failed("fence_not_durable", `the fenced row's status could not be read: ${said(err)}`);
+        }
+        if (afterStatus !== "expired") {
+            return await failed(fenced ? "fence_not_durable" : "fence_failed", fenced
+                ? `expire reported a win and the row reads ${shown(afterStatus)} — the contract's transition is pending → expired, so the CAS did not land`
+                : `expire lost an UNCONTENDED CAS and the row reads ${shown(afterStatus)} — the fence that keeps a checkpoint from being both reaped and resumed does not close here`);
+        }
+    }
+    const steps = `filed, read back${enumerable ? ", enumerated" : ""} and fenced`;
+    const notExercised = enumerable ? "" : " (this store implements no listByScope, so the inbox enumeration was NOT exercised)";
+    const casNote = fenced ? "" : " (the expire CAS reported a loss while the row closed — consistent with store housekeeping, but a backend that mis-reports CAS wins is not distinguished here)";
+    return {
+        verdict: "round_trip_ok",
+        findings: [],
+        ...(fenced ? {} : { casLossObserved: true }),
+        scope,
+        summary: after === null
+            ? `the park lane ${steps} a synthetic checkpoint${notExercised} — the row is no longer present (a deleting backend or its own housekeeping removed it), so nothing resumable remains${casNote}`
+            : `the park lane ${steps} a synthetic checkpoint${notExercised} — residual expired row in scope "${scope}"${casNote}`,
+        ...gapCell,
+    };
+}

package/dist/core/push-queue.d.ts

@@ -3,7 +3,10 @@ export declare class PushQueue<T> implements AsyncIterable<T> {
     private buffer;
     private waiters;
     private closed;
-    push(value: T): void;
+    /** Returns whether the value was ACCEPTED (`false` after close — the push is a silent no-op then).
+     *  Callers that mirror a pushed value to a second reader gate on this so both sides stay in parity
+     *  (#253: a status frame must not reach a side sink the stream itself already refused). */
+    push(value: T): boolean;
     close(): void;
     [Symbol.asyncIterator](): AsyncIterator<T>;
 }

package/dist/core/push-queue.js

@@ -4,7 +4,7 @@ export class PushQueue {
     closed = false;
     push(value) {
         if (this.closed) {
-            return;
+            return false;
         }
         const waiter = this.waiters.shift();
         if (waiter) {
@@ -13,6 +13,7 @@ export class PushQueue {
         else {
             this.buffer.push(value);
         }
+        return true;
     }
     close() {
         this.closed = true;

package/dist/core/runner/prepare-acquire-reconcile.d.ts

@@ -40,6 +40,12 @@ export interface PrepareAcquireReconcileInput {
      *  {@link import("./prepare-safety-scan.js").PrepareSafetyScanResult}); reconcile classifies an
      *  orphaned call's retry-safety by it. */
     toolEffects: Map<string, ToolEffect>;
+    /** borrowed-readonly — design/252 G-6 sibling: the durable-park TOPOLOGY gap sentence for this
+     *  deployment (`durableParkGapFor`), or `undefined` when the topology is whole / does not apply.
+     *  Read ONLY on the fail-loud missing-session path below, where it turns a symptom into a named
+     *  absent seat; nothing in the phase's control flow depends on it. Computed by the driver (which
+     *  holds `deps`) rather than here, keeping this slice's input the narrow Pick its contract says. */
+    durableParkGap?: string;
 }
 /** The phase's outputs (design/238 相 API 规则件 four-class form). All five are fresh bindings —
  *  the driver destructures them into consts, so a consumer moved ahead of this call is a lexical

package/dist/core/runner/prepare-acquire-reconcile.js

@@ -39,7 +39,8 @@ export async function prepareAcquireReconcile(input) {
         }
         catch (err) {
             if (spec.requireExistingSession && err?.code === "not_found") {
-                const e = new Error(`requireExistingSession: session "${spec.sessionId}" does not exist — refusing a silent fresh run (design/114 Phase3)`);
+                const e = new Error(`requireExistingSession: session "${spec.sessionId}" does not exist — refusing a silent fresh run (design/114 Phase3)` +
+                    (input.durableParkGap !== undefined ? `. Note the assembly: ${input.durableParkGap}` : ""));
                 e.code = "resume.session_not_found";
                 throw e;
             }

package/dist/core/runner/prepare-task.d.ts

@@ -169,9 +169,14 @@ export interface Prepared {
      *  emits; the tool_result-side delete in prepare-task never fires for immediate results). */
     blockedToolCalls: Set<string>;
     /**
-     * What ended the approval a gated call was waiting on, keyed by tool-call id — written ONLY by the
-     * tool gate, at the one exit where an ask resolved, and read once when that call's `tool_end` frame
-     * is minted (the reader deletes on read; a call the gate never settled has no entry).
+     * WHAT ended the approval a gated call was waiting on and — design/252 G-7 — WHOSE settlement it
+     * was, keyed by tool-call id: written ONLY by the tool gate, at the one exit where an ask resolved,
+     * and read once when that call's `tool_end` frame is minted (the reader deletes on read; a call the
+     * gate never settled has no entry, and an entry never names neither fact).
+     *
+     * ONE record rather than two parallel maps because they are one observation: an attribution without
+     * the settlement kind beside it is unreadable ("alice" — approved? her window elapsed?), and two maps
+     * keyed alike are two chances to drain one and leak the other.
      *
      * It is a sideband and not a field on the tool RESULT because a result is not a trustworthy carrier
      * for this: `details` is arbitrary tool-authored data that post-tool hooks may also replace, so a
@@ -180,7 +185,10 @@ export interface Prepared {
      * adjudicating layer can write. Same reason the entries are keyed by CALL id: the gate adjudicated
      * that exact call, and the frame that reads it is that call's own.
      */
-    approvalSettledBy: Map<string, import("../tool-policy.js").ApprovalSettledBy>;
+    approvalSettlement: Map<string, {
+        settledBy?: import("../tool-policy.js").ApprovalSettledBy;
+        approver?: string;
+    }>;
     /** Summed usage of nested sub-runs (sub-agents) spawned by this task's tools. */
     nestedStats: NestedUsageAccum;
     /** RB-430-a: prepare-time rewind disclosures (conversation-only branch / no snapshot backend / no file
@@ -1285,6 +1293,19 @@ export interface RunInternals {
      * MODEL context (this is purely a render channel). Absent unless the deployment opted in.
      */
     onForwardEvent?: (event: TaskEvent) => void;
+    /**
+     * #253 — the run's OWN top-level `status` TaskEvent stream (brain liveness: rate-limit/retry/
+     * reconnect/circuit-open), offered to the internals holder beside the queue. The queue alone was
+     * enough for a direct `runTask` caller (the TaskStream carries these frames), but a COMPOSITION
+     * entry (verify/cascade) drains its inner legs' queues itself — without this seat, an inner leg's
+     * retry disclosure died inside the gate and the wire showed a silent stall. Fed the SAME frame
+     * object the queue receives, at the same moment; contained by the run's safe notifier (#248 form:
+     * a throwing sink is swallowed, first failure per site disclosed, never faults the leg). Subagent
+     * frames still ride {@link onForwardEvent} — this seat is ONLY the run's own status type.
+     */
+    onStatusEvent?: (event: Extract<TaskEvent, {
+        type: "status";
+    }>) => void;
     /**
      * design/115 P2 core slice — trusted run-local system-injection sink. `Runner.runLocked` wires this to the
      * live TaskStream queue plus the current harness follow-up lane; it is not a public TaskSpec field.