@sema-agent/core 7.19.0 → 7.20.0

package/dist/core/memory-engine/layout.d.ts

@@ -272,6 +272,12 @@ export interface QuarantineOutcome {
     dest?: string;
     /** True ⇔ the model-visible file no longer holds the suspect content (deleted, or tombstoned). */
     removed: boolean;
+    /** WHAT this containment left at the model-visible path, which is the only thing a following restore
+     *  may overwrite (see {@link restoreContainedBaseline}). ABSENT ⇔ the path was freed. Present ⇔ either
+     *  this engine's own tombstone (the clear-in-place rung) or the suspect bytes themselves (neither rung
+     *  worked) — in both cases replacing it takes nobody else's work, and in neither case may anything the
+     *  restore did not put there be destroyed. */
+    leftOnPlane?: string;
     /** Set on ANY deviation from the clean capture+delete path — never a silent best-effort downgrade. */
     detail?: string;
 }
@@ -313,6 +319,31 @@ export interface QuarantineOutcome {
  * `O_TRUNC` already destroyed the destination) is the failure this guard exists to prevent.
  */
 export declare function writeFileNoFollow(path: string, content: string): void;
+/** {@link writeFileNoFollow}'s NO-REPLACE twin: write `content` only if nothing is at `path`. `"written"`
+ *  when the bytes landed, `"kept"` when it was occupied; every other failure throws like the twin (a
+ *  write that could not be ATTEMPTED must not read as one that chose not to). `O_EXCL | O_CREAT` is the
+ *  atomic form — an `existsSync`-then-write pair is a TOCTOU with exactly the window this closes — and
+ *  it refuses a symlink at the final component on its own (POSIX `EEXIST` on a link, dangling or not),
+ *  so the twin's no-follow property is kept without a second check. */
+export declare function writeFileNoReplace(path: string, content: string): "written" | "kept";
+/**
+ * The ONE way a committed baseline goes back after {@link quarantineAndTombstone} emptied its seat —
+ * the inverse half of that function, beside it so the removal word and its readers stay in one module.
+ * Both containment arms (the capture-residue sweep and the polluted-harvest record loop) call it, and
+ * the rule is ONE sentence: THE RESTORE MAY ONLY OVERWRITE WHAT THE CONTAINMENT ITSELF LEFT AT THE PATH.
+ * The removal's own account of what it left (`leftOnPlane` — nothing, our tombstone, or the suspect
+ * bytes) is re-read and compared immediately before the write, through a read that refuses a link, a
+ * pipe and anything but a regular file: a caller that awaited the committed store cannot assume what
+ * the removal saw still holds, on ANY of the three arms. Anything else — a freed path, a path somebody
+ * took back, a path that could not be verified — takes the no-replace write, which is the right answer
+ * for all of them at once: it lands iff nothing is there. Residual window: the read-to-open gap, with
+ * nothing suspended in it.
+ *
+ * Declining never weakens containment. Where the suspect bytes were removed they are already in
+ * quarantine; where they were NOT, the only way the comparison fails is that somebody replaced them —
+ * which took them off the plane as surely as the removal would have.
+ */
+export declare function restoreContainedBaseline(path: string, committed: string, leftOnPlane: string | undefined): "written" | "kept" | "failed";
 export declare function quarantineAndTombstone(path: string, content: string, quarantineDir: string, now: () => number): QuarantineOutcome;
 /** S2-B — the queued memory-change announcements (control plane; drained at session-first inject). */
 export declare const ANNOUNCEMENTS_FILE = "announcements.json";

package/dist/core/memory-engine/layout.js

@@ -1,5 +1,5 @@
-import { chmodSync, closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs";
-const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW, O_EXCL } = fsConstants;
+import { chmodSync, closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs";
+const { O_WRONLY, O_RDONLY, O_CREAT, O_TRUNC, O_NOFOLLOW, O_NONBLOCK, O_EXCL } = fsConstants;
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -740,6 +740,63 @@ export function writeFileNoFollow(path, content) {
         closeSync(fd);
     }
 }
+export function writeFileNoReplace(path, content) {
+    let fd;
+    try {
+        fd = openSync(path, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW, 0o644);
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return "kept";
+        throw err;
+    }
+    try {
+        writeFileSync(fd, content, "utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+    return "written";
+}
+function readForVerification(path, maxBytes) {
+    let fd;
+    try {
+        fd = openSync(path, O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        if (!fstatSync(fd).isFile())
+            return undefined;
+        const buf = Buffer.allocUnsafe(maxBytes);
+        let got = 0;
+        for (;;) {
+            const n = readSync(fd, buf, got, maxBytes - got, got);
+            if (n <= 0 || got + n >= maxBytes)
+                return buf.subarray(0, got + Math.max(0, n)).toString("utf8");
+            got += n;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function restoreContainedBaseline(path, committed, leftOnPlane) {
+    try {
+        if (leftOnPlane === undefined || readForVerification(path, Buffer.byteLength(leftOnPlane) + 1) !== leftOnPlane) {
+            return writeFileNoReplace(path, committed);
+        }
+        writeFileNoFollow(path, committed);
+        return "written";
+    }
+    catch {
+        return "failed";
+    }
+}
 let quarantineSeq = 0;
 export function quarantineAndTombstone(path, content, quarantineDir, now) {
     let captured;
@@ -767,14 +824,17 @@ export function quarantineAndTombstone(path, content, quarantineDir, now) {
     catch (err) {
         detail = `quarantine copy failed: ${err instanceof Error ? err.message : String(err)}`;
     }
+    let left = content;
     let removed = false;
     try {
         rmSync(path, { force: true });
+        left = undefined;
         removed = true;
     }
     catch (rmErr) {
         try {
             writeFileNoFollow(path, DELETED_TOMBSTONE);
+            left = DELETED_TOMBSTONE;
             removed = true;
             detail = `${detail !== undefined ? `${detail}; ` : ""}delete failed (${rmErr instanceof Error ? rmErr.message : String(rmErr)}) — tombstoned in place`;
         }
@@ -782,7 +842,12 @@ export function quarantineAndTombstone(path, content, quarantineDir, now) {
             detail = `${detail !== undefined ? `${detail}; ` : ""}suspect file could not be deleted or cleared: ${clearErr instanceof Error ? clearErr.message : String(clearErr)}`;
         }
     }
-    return { ...(captured !== undefined ? { dest: captured } : {}), removed, ...(detail !== undefined ? { detail } : {}) };
+    return {
+        ...(captured !== undefined ? { dest: captured } : {}),
+        removed,
+        ...(left !== undefined ? { leftOnPlane: left } : {}),
+        ...(detail !== undefined ? { detail } : {}),
+    };
 }
 export const ANNOUNCEMENTS_FILE = "announcements.json";
 export const MEMORY_ANNOUNCEMENTS_MAX = 20;

package/dist/core/memory-engine/types.d.ts

@@ -549,6 +549,21 @@ export interface MemoryAnnouncement {
      *  the stored strings are already render-safe; the render step only adds the trusted lead/frame. */
     items: string[];
 }
+/** What `MemoryEngine.sweepSessionCaptureResidue` reports: the paths it contained, the baselines it put
+ *  back, the ones it DECLINED to (`restoreContainedBaseline`), and the paths it could not contain. */
+export interface SessionCaptureResidueSweep {
+    swept: string[];
+    restored: string[];
+    failures: Array<{
+        path: string;
+        detail: string;
+    }>;
+    withheld: Array<{
+        path: string;
+        entryId?: string;
+        rev?: string;
+    }>;
+}
 /**
  * design/138 §2.4 — the harvest outcome. Rejections are MODEL-VISIBLE gate events: S1 delivers the
  * structure; the runner's boundary-announcement wiring (attachments member) lands in S2 (TODO(S2)).
@@ -626,6 +641,15 @@ export interface HarvestReport {
      *  storage), so those paths appear here beside {@link containment}.heldInstruction, never in
      *  `missing` (the file never vanished — its edit is in custody). */
     restored: string[];
+    /** The other outcome of the same restore: a path whose committed baseline was NOT written back, because
+     *  another writer held the file when the restore reached it. The newer bytes stand, the baseline is
+     *  still in the store, and this row is how a host learns which paths are in that state. ABSENT/empty
+     *  ⇔ every restore landed; `rev` is the declined generation, when it could be derived. */
+    restoreWithheld?: Array<{
+        path: string;
+        entryId?: string;
+        rev?: string;
+    }>;
     /** Index self-heal notes (L8): suspected-duplicate index lines kept-with-warning, cleared orphans. */
     warnings: string[];
     /** M7 harvest budget: set when the deadline/file budget cut the harvest short. `pending` files were

package/dist/core/memory.d.ts

@@ -275,6 +275,25 @@ export declare class MemoryGateError extends Error {
     readonly code: string;
     constructor(code: string, detail?: string);
 }
+/**
+ * The same SHAPE as {@link MemoryGateError} — a stable `code` a caller switches on — for the opposite
+ * PHASE of a memory write, and deliberately NOT that class: a gate error means the write was REFUSED
+ * and never reached the backend, so a host branching on it would take exactly the wrong action here.
+ *
+ * @contract memory.projection_failure_is_post_durable — a store throws this ONLY after the note's own
+ * event is durably appended and fsync'd, so `committed` is always true and the note survives a restart:
+ * a caller that retries the write on this error stores the note a second time. Only the derived
+ * projection is missing, and the next mutation of the same scope rewrites it whole.
+ */
+export declare class MemoryProjectionError extends Error {
+    /** Stable, switchable — the phase this failure belongs to. */
+    readonly code = "memory.projection_failed";
+    /** Always true: this error only exists AFTER the durable append was fsync'd. Never retry the write. */
+    readonly committed = true;
+    /** The projection file that could not be rewritten. */
+    readonly path: string;
+    constructor(path: string, cause: unknown);
+}
 /**
  * Scan `text` for a high-confidence credential (CC-parity P0-2). Returns the matched pattern's stable
  * `label` (NEVER the matched secret value — labels are safe to log/surface), or `null` when clean.

package/dist/core/memory.js

@@ -22,6 +22,18 @@ export class MemoryGateError extends Error {
         this.code = code;
     }
 }
+export class MemoryProjectionError extends Error {
+    code = "memory.projection_failed";
+    committed = true;
+    path;
+    constructor(path, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`memory.projection_failed: the note IS durably committed — only the derived projection ${path} could not be rewritten: ${detail}. ` +
+            `Do not retry the write (it would store the note twice); the projection is rebuilt by the next mutation of this scope.`, cause !== undefined ? { cause } : undefined);
+        this.name = "MemoryProjectionError";
+        this.path = path;
+    }
+}
 function hasPromotableMarker(note) {
     return note.outcomeStats !== undefined;
 }

package/dist/core/remote-env.d.ts

@@ -316,6 +316,16 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
          *  without durable suspend instead (the human gate refuses it), or extend capabilities with an
          *  explicit workspace-durability flag before building one. */
         suspendable: boolean;
+        /** True iff this adapter's {@link FileSystem.canonicalPath} is the AUTHORITY on where a path lands —
+         *  it answers for the very filesystem the commands run on, and a failure to answer is a failure of
+         *  the resolver rather than a namespace it cannot see into. Optional, and absent is not a
+         *  declaration: an adapter that says nothing keeps the reading every adapter has had, in which a
+         *  chain nothing could be established about leaves the lexical verdict standing. Declaring it says
+         *  the opposite — that an unanswerable chain is a question, not an absence — and the read
+         *  boundary's execute-time recheck then refuses rather than passing the written spelling through.
+         *  Read STRICTLY through {@link canonicalPathIsAuthoritative}, like every other capability whose
+         *  `true` changes what a containment leg does; a wrong-SHAPE value reads absent and is announced. */
+        canonicalPathAuthoritative?: boolean;
     };
     /** Identity of the connected workspace (design/48 §5 gap 1). Synchronous: it is data the env already holds. */
     workspaceHandle(): WorkspaceHandle;
@@ -507,6 +517,9 @@ export declare function missingRestoreSurface(env: ExecutionEnv): readonly ("res
  *
  * A composite type guard (structural AND capability) so a `suspendVM` call site narrowed by THIS predicate
  * gets the {@link RemoteExecutionEnv} type without a cast — `true` always implies the structural check too.
+ * The capability is read STRICTLY, like the containment ones: a non-boolean reads as NOT suspendable and
+ * the census announces it. This took anything truthy, so `suspendable: "false"` was snapshotted — the one
+ * key of the three whose malformed reading fell on the unsafe side.
  *
  * It also requires the RESTORE surface ({@link missingRestoreSurface}). A suspend is only durable
  * if something can undo it; an adapter that offers `suspendVM` but no `resumeVM` used to pass this guard,
@@ -549,3 +562,22 @@ export declare function isIsolated(env: ExecutionEnv): boolean;
  * answers exactly, and reading the shape as containment made that deployment's boundary lexical-only.
  */
 export declare function boundaryIsTheSandbox(env: ExecutionEnv): boolean;
+/**
+ * Does this env DECLARE that its `canonicalPath` is the authority on where a path lands?
+ *
+ * The question the execute-time read boundary asks about its own resolver's SILENCE. Resolving a
+ * spelling walks it from the deepest answerable ancestor; when no ancestor answers at all, two
+ * different worlds produce the same `undefined`: a resolver that is authoritative and is FAILING (an
+ * RPC into the machine the command will run on, a transport that dropped), and an env that simply does
+ * not answer path questions (an in-memory double, an adapter with no resolution surface). The first is
+ * a question and the second is an absence, and reading both as the absence is what leaves a containment
+ * leg silently open on an RPC-backed lane.
+ *
+ * So the adapter says which it is, and says it the way {@link isIsolated} is said — strictly, because a
+ * `true` here makes a containment leg REFUSE where it used to pass. ABSENT is the reading every adapter
+ * has had, so no existing env moves; a PRESENT non-boolean reads absent HERE too but is announced at the
+ * env's admission point, once per key — this reader does not validate. A non-remote env keeps the same
+ * reading, which is why the local lane is unchanged: its resolver answers `/`, so the arm this gates
+ * has no case to fire on.
+ */
+export declare function canonicalPathIsAuthoritative(env: ExecutionEnv): boolean;

package/dist/core/remote-env.js

@@ -37,7 +37,7 @@ export function missingRestoreSurface(env) {
     return missing;
 }
 export function isSuspendable(env) {
-    return isRemoteExecutionEnv(env) && env.capabilities.suspendable && missingRestoreSurface(env).length === 0;
+    return isRemoteExecutionEnv(env) && env.capabilities.suspendable === true && missingRestoreSurface(env).length === 0;
 }
 export function isIsolated(env) {
     return isRemoteExecutionEnv(env) ? env.capabilities.isolation === true : false;
@@ -45,3 +45,6 @@ export function isIsolated(env) {
 export function boundaryIsTheSandbox(env) {
     return isIsolated(env);
 }
+export function canonicalPathIsAuthoritative(env) {
+    return isRemoteExecutionEnv(env) ? env.capabilities.canonicalPathAuthoritative === true : false;
+}

package/dist/core/runner/advertised-writable-dirs.d.ts

@@ -20,6 +20,11 @@
  * planted path is never written through); an advertiser whose directory is created elsewhere passes
  * no marker and an absent directory narrows.
  *
+ * A directory the fence already holds is never admitted as a HOLE in it: a candidate that resolves onto
+ * a root — or above one — would turn that whole root into the advertised, write-gate-exempt domain, so
+ * an ordinary source write inside the workspace would stop asking. One predicate
+ * ({@link swallowedFenceRoot}) states that, and the write gate's configured domains apply the same one.
+ *
  * Reverse check (the seat's own invariant): nothing enters `roots` except through `admit`, and every
  * caller of `admit` is an advertiser deciding its advertisement off the returned verdict — so no
  * directory reaches the ROOTS FENCE through this seat without the prompt advertising it, and none
@@ -55,12 +60,65 @@ export interface AdvertisedWritableDir {
 }
 /** The skip announcement — the one loud outlet for a directory that was advertised but could not be admitted. */
 export type AdvertisedWritableDirSkipped = (dir: AdvertisedWritableDir, reason: string) => void;
+/**
+ * ONE rule for both halves of the auto-approved write surface: a directory offered as a WRITABLE DOMAIN
+ * (an advertised writable directory here; a configured `exemptDirs`/`acceptDirs` entry at the write
+ * gate) must not SWALLOW a root the fence already holds. Returns the first root the candidate equals or
+ * is an ancestor of — the one to name in the refusal — else `undefined`.
+ *
+ * Why a domain that contains a root is not a domain: the point of the domain is to exempt a small area
+ * the prompt (or the deployment) named. A candidate resolving onto the task root — a symlinked
+ * scratchpad or memory home is all it takes, and the resolution is what makes it invisible to the
+ * spelling — exempts the ENTIRE workspace instead, turning every ordinary source write from `ask` into
+ * `allow`. Refusing the admission is the fix; a special case inside the gate ("ignore this domain when
+ * it contains the root") would be the same rule written twice, in the place where it is easiest to
+ * forget. Both arguments must already be CANONICAL — this compares spellings, it does not resolve them.
+ */
+export declare function swallowedFenceRoot(domainCanonical: string, fenceRootsCanonical: readonly string[]): string | undefined;
 export declare class AdvertisedWritableDirs {
     private readonly env;
     private readonly onSkipped;
+    /** The extra fence roots the SPEC declares (`additionalDirectories` / `additionalReadDirectories`), as
+     *  spelled. Resolved by this seat rather than awaited from the hands phase — the memory advertiser is
+     *  admitted BEFORE that phase, so a list that only grew there made the rule depend on phase order. An
+     *  entry that does not resolve is not a fence root at all (the hands phase reads the SAME memoized
+     *  answer and skips it too, announcing it there), so there is nothing here for it to guard. */
+    private readonly declaredRootSpellings;
     private readonly admitted;
     private readonly verdicts;
-    constructor(env: ExecutionEnv, onSkipped: AdvertisedWritableDirSkipped);
+    /** The CANONICAL roots the fence holds: the task root at construction, plus every root the spec
+     *  DECLARES, resolved by this seat before it judges anything (see {@link resolveDeclaredRoots}) —
+     *  so which advertiser runs first cannot decide what the rule sees. */
+    private readonly fenceRoots;
+    /** Latched after the declared spellings have been resolved once (the resolution is per seat, not per call). */
+    private declaredRootsResolved;
+    /** ONE answer per declared spelling, for this seat AND for the hands phase that folds the same entries
+     *  into the allowlist ({@link canonicalizeDeclaredRoot}): two independent lookups of one path can
+     *  DISAGREE, and a root outside this rule's list while inside the fence is exactly the gap. */
+    private readonly declaredRootAnswers;
+    constructor(env: ExecutionEnv, onSkipped: AdvertisedWritableDirSkipped, 
+    /** The run's task root, CANONICAL (the driver's one resolution — see `task-root-canonical.ts`). */
+    taskRootCanonical: string, 
+    /** The extra fence roots the SPEC declares (`additionalDirectories` / `additionalReadDirectories`), as
+     *  spelled. Resolved by this seat rather than awaited from the hands phase — the memory advertiser is
+     *  admitted BEFORE that phase, so a list that only grew there made the rule depend on phase order. An
+     *  entry that does not resolve is not a fence root at all (the hands phase reads the SAME memoized
+     *  answer and skips it too, announcing it there), so there is nothing here for it to guard. */
+    declaredRootSpellings?: readonly string[]);
+    /** Declare one more CANONICAL root the fence holds (an `additionalDirectories` /
+     *  `additionalReadDirectories` entry, once the hands phase has resolved it). Declaring is
+     *  idempotent and order-free; a root declared after an advertiser was judged does not re-open it. */
+    declareFenceRoot(canonical: string): void;
+    /**
+     * The canonical form of a DECLARED fence-root spelling — resolved at most once per spelling and
+     * served from the memo thereafter. The hands phase calls this instead of canonicalizing the same
+     * entries again, so the list this rule judges against and the allowlist the fence ends up holding
+     * are built from ONE answer per path: a lookup that fails for this seat fails for that phase too,
+     * and a root cannot be outside the rule's view while being inside the fence.
+     */
+    canonicalizeDeclaredRoot(spelled: string): Promise<Awaited<ReturnType<ExecutionEnv["canonicalPath"]>>>;
+    /** Resolve the spec-declared root spellings into {@link fenceRoots}, exactly once per seat. */
+    private resolveDeclaredRoots;
     /** The admitted roots, CANONICAL, in admission order, deduplicated. The hands phase folds this list into the
      *  write-capable containment allowlist before the toolkit compiles; it is not a live view after that. */
     get roots(): readonly string[];

package/dist/core/runner/advertised-writable-dirs.js

@@ -1,11 +1,52 @@
+import { isWithin } from "./session-rule-policy.js";
+export function swallowedFenceRoot(domainCanonical, fenceRootsCanonical) {
+    for (const root of fenceRootsCanonical) {
+        if (root && isWithin(domainCanonical, root))
+            return root;
+    }
+    return undefined;
+}
 export class AdvertisedWritableDirs {
     env;
     onSkipped;
+    declaredRootSpellings;
     admitted = [];
     verdicts = new Map();
-    constructor(env, onSkipped) {
+    fenceRoots;
+    declaredRootsResolved;
+    declaredRootAnswers = new Map();
+    constructor(env, onSkipped, taskRootCanonical, declaredRootSpellings = []) {
         this.env = env;
         this.onSkipped = onSkipped;
+        this.declaredRootSpellings = declaredRootSpellings;
+        this.fenceRoots = [taskRootCanonical];
+    }
+    declareFenceRoot(canonical) {
+        if (canonical && !this.fenceRoots.includes(canonical))
+            this.fenceRoots.push(canonical);
+    }
+    async canonicalizeDeclaredRoot(spelled) {
+        const memo = this.declaredRootAnswers.get(spelled);
+        if (memo !== undefined)
+            return memo;
+        const c = await this.env.canonicalPath(spelled);
+        const first = this.declaredRootAnswers.get(spelled);
+        if (first !== undefined)
+            return first;
+        this.declaredRootAnswers.set(spelled, c);
+        if (c.ok)
+            this.declareFenceRoot(c.value);
+        return c;
+    }
+    resolveDeclaredRoots() {
+        this.declaredRootsResolved ??= (async () => {
+            for (const spelled of this.declaredRootSpellings) {
+                if (!spelled || !spelled.trim())
+                    continue;
+                await this.canonicalizeDeclaredRoot(spelled);
+            }
+        })();
+        return this.declaredRootsResolved;
     }
     get roots() {
         return this.admitted;
@@ -41,8 +82,15 @@ export class AdvertisedWritableDirs {
             this.onSkipped(dir, `the execution environment resolves it to ${c.value} while the advertiser's gates key on ${dir.expectCanonical} — a fence hole those gates cannot see is not opened`);
             return false;
         }
-        if (!this.admitted.includes(c.value))
-            this.admitted.push(c.value);
+        if (this.admitted.includes(c.value))
+            return true;
+        await this.resolveDeclaredRoots();
+        const swallowed = swallowedFenceRoot(c.value, [...this.fenceRoots, ...this.admitted]);
+        if (swallowed !== undefined) {
+            this.onSkipped(dir, `it resolves to ${c.value}, which covers ${swallowed === this.fenceRoots[0] ? "task root" : "root"} ${swallowed} — a directory that holds a root is not a hole in the fence but the whole of it, and admitting it would auto-approve every write under that root`);
+            return false;
+        }
+        this.admitted.push(c.value);
         return true;
     }
 }

package/dist/core/runner/announce-once-ledger.d.ts

@@ -27,6 +27,21 @@ export interface AnnounceOnceSession {
     getAnnouncedListing(): Promise<AnnouncedListingSnapshot | undefined>;
     appendAnnouncedListing(snapshot: AnnouncedListingSnapshotInput): Promise<string>;
 }
+/**
+ * Flush the PARKED announced-listing snapshot write (`FrameReceiptLedger.listingSnapshotOwed`, set by a
+ * frame receipt's commit inside the `message_end` walk) at a serialization point — the boundary's end,
+ * the prompt's settle. Best-effort: a lost append is a duplicate announcement next run. Never while
+ * prepare's branch read failed: a whole-snapshot write would replace the branch's record with this
+ * leg's partial view (the flag is cleared either way — nothing is owed on such a leg).
+ */
+export declare function flushOwedAnnouncedSnapshot(prepared: {
+    frameReceipts: {
+        listingSnapshotOwed: boolean;
+    };
+    announcedSnapshotRecovered: boolean;
+    announcedListingsRef: AnnouncedListingSnapshotInput;
+    session: Pick<AnnounceOnceSession, "appendAnnouncedListing">;
+}): Promise<void>;
 /** The run-local ledger — see the module header for the two commit disciplines it serves. */
 export interface AnnounceOnceLedger {
     /** The nearest announced snapshot on the branch as read at prepare (undefined = pre-entry

package/dist/core/runner/announce-once-ledger.js

@@ -29,6 +29,14 @@ export function withAnnounceDigests(existing, add) {
 function sameFailure(a, b) {
     return a.name === b.name && a.error === b.error;
 }
+export async function flushOwedAnnouncedSnapshot(prepared) {
+    if (!prepared.frameReceipts.listingSnapshotOwed)
+        return;
+    prepared.frameReceipts.listingSnapshotOwed = false;
+    if (!prepared.announcedSnapshotRecovered)
+        return;
+    await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
+}
 export async function loadAnnounceOnceLedger(session, checkpointMirror, onError) {
     let recovered = true;
     const entry = await session.getAnnouncedListing().catch(() => {

package/dist/core/runner/classifier-ladder.d.ts

@@ -87,6 +87,11 @@ export type ClassifierSeat = {
  *     all ⇒ the main model, `main_only`.
  * The relative pick follows the run's MAIN model on purpose: a side channel that resolved without it is the
  * misfit the ticket names (a `flash` classifier above a `lite` main; two tiers below a `max` main).
+ *
+ * @contract classifier.seat.one_resolver — this function is the ONE answer to "which model judges this run's
+ * gated calls". The engine's arming calls it and a host that DISPLAYS the seat (a capabilities face, an
+ * operator pane) calls the same exported function rather than re-deriving the pick from catalog, roles and
+ * tiers: a second derivation is a second answer, and the two drift the moment either side's rules move.
  */
 export declare function classifierSeatModel(args: {
     deps: Pick<RunnerDeps, "models" | "roles" | "tiers">;

package/dist/core/runner/classifier-ladder.js

@@ -2,7 +2,7 @@ import { sameRouteIdentity } from "../../brain/route-adjudicator.js";
 import { thinkingOffSpelled } from "../../brain/reasoning.js";
 import { AUTO_MODE_CLASSIFIER_CONTRACT_BROKEN_AFTER, AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS, AUTO_MODE_CLASSIFIER_MAX_TOKENS, AUTO_MODE_CLASSIFIER_THINK_BUDGET_TOKENS } from "../auto-mode-defaults.js";
 import { autoModeClassifierFallbackOf, parseAutoModeResponse } from "../auto-mode.js";
-import { DEFAULT_TIER_ORDER, resolveTaskModel, roleSpecNamesModel } from "../roles.js";
+import { DEFAULT_TIER_ORDER, expandTiers, resolveTaskModel, roleSpecNamesModel } from "../roles.js";
 import { emitTrace } from "../trace.js";
 import { deliverEngineNotice } from "../types.js";
 export function classifierLadderRungs(knob, classifier, main) {
@@ -20,7 +20,8 @@ function sameRouteQuietly(a, b) {
 }
 export const CLASSIFIER_ROLE_DEFAULT_REASONS = ["tier_below_main", "tier_table", "role_fallback", "main_only", "role_unresolvable"];
 export function classifierSeatModel(args) {
-    const { deps, main } = args;
+    const { main } = args;
+    const deps = normalizeSeatDeps(args.deps);
     if (roleSpecNamesModel(deps.roles?.classifier)) {
         try {
             return { model: resolveTaskModel({ modelRole: "classifier" }, deps).model };
@@ -42,6 +43,16 @@ export function classifierSeatModel(args) {
         return { model: main, defaulted: "main_only" };
     }
 }
+function normalizeSeatDeps(deps) {
+    if (deps.tiers === undefined)
+        return deps;
+    try {
+        return { ...deps, models: expandTiers(deps.models, deps.tiers) };
+    }
+    catch {
+        return deps;
+    }
+}
 function tierBelowMain(deps, main) {
     if (deps.tiers === undefined || Object.keys(deps.tiers).length === 0 || deps.models === undefined)
         return undefined;

package/dist/core/runner/contracts.d.ts

@@ -173,6 +173,35 @@ export interface CommittedPause {
     scope: string;
     gatedCallId?: string;
 }
+/**
+ * One engine frame whose commit waits for the receipt of the message carrying it.
+ *
+ * @contract frames.commit_on_receipt — an engine-minted frame that rides a user message (the git-status
+ * frame, an `agent_listing` or `skills_listing` frame) is recorded as announced ONLY when the run loop's
+ * `message_end` walk sees a persisted user entry whose text equals the carrying text it was registered
+ * with; every receipt with that text settles on that one entry. Until then nothing is recorded — a
+ * message that never reaches the transcript (a pre-append failure, a suppressed or undrained steer, a
+ * leg that ends first) leaves the frame unannounced, and the next boundary or leg renders it again.
+ * The error asymmetry is one-directional by design: a lost receipt costs a duplicate frame, never a
+ * fact the model was recorded as told and was not.
+ */
+export interface FrameReceipt {
+    /** The carrying message's exact text (its first text block) — the receipt's match key. */
+    text: string;
+    /** Which frame this receipt settles. A boundary collector must not render a listing whose receipt is
+     *  still pending (the frame is queued, not yet in the transcript). */
+    source: "git_status" | "agent_listing" | "skills_listing";
+    /** Runs inside the `message_end` walk (synchronous, never awaited): advances the run-local record
+     *  and parks any session write for the next serialization point. */
+    commit: (entryId: string) => void;
+}
+/** The leg's frame-receipt ledger — see {@link FrameReceipt}. `listingSnapshotOwed` is the parked
+ *  announced-listing snapshot write (a session append from inside the walk would race the loop's own
+ *  next transcript append); the boundary's end and the prompt's settle flush it. */
+export interface FrameReceiptLedger {
+    pending: FrameReceipt[];
+    listingSnapshotOwed: boolean;
+}
 export interface Prepared {
     harness: AgentHarness;
     /** The CONCRETE built-in session (engine-internal: prepare constructs/acquires `StoredSession` itself,
@@ -1017,6 +1046,7 @@ export interface Prepared {
         toolName: string;
         seedAnnounced: boolean;
         models?: readonly string[];
+        budget: ResolvedSkillListingBudget;
     };
     /** [c209-C] skills_listing counterpart of {@link agentListing} — the normalized skills METADATA
      *  projection (names/descriptions/attachment paths, never bodies; the exact list `createSkillTool`
@@ -1038,6 +1068,9 @@ export interface Prepared {
      *  announce-once-ledger.ts): seeded at prepare from the branch's record, advanced by the run loop
      *  on intact delivery of the tools_delta `failedServers` arm / the mcp_dropped_tools frame. */
     announcedListingsRef: AnnouncedListingSnapshotInput;
+    /** The frame-receipt ledger — the ONE commit point of every engine frame that rides a user message
+     *  (the git-status frame, the agent and skills listing frames). Always present; per leg. */
+    frameReceipts: FrameReceiptLedger;
     /** env-tail migration — the git-status frame lane's run-local state: this leg's
      *  resolved frame (probe outcome rendered + hashed at prepare), the announced `(kind, hash)`
      *  mirror the checkpoint serializer reads, the trim-protection slot the request-build context
@@ -1796,7 +1829,11 @@ export interface RunInternals {
    * `forwardSubagentEvents: true` it ALSO forwards the child's content events (`text_delta` / `text_end` /
      * `reasoning_delta` / `tool_start` / `tool_end` — the subagent viewing pane, carrying the same UNTRUSTED-RAW/consumer-must-redact
      * contract as the main stream's tool events). Either way the child stream is NEVER merged into the parent's
-     * MODEL context (this is purely a render channel). Absent unless the deployment opted in.
+     * MODEL context (this is purely a render channel). Absent unless the deployment opted in. CONTAINED at
+     * one door: every engine site feeding this seat goes through `forwardSafely` (`forward-sink.ts`), so a
+     * sink that throws — or, since an `async` function satisfies this `=> void` type, one that returns a
+     * REJECTING promise — drops its frame and nothing else, never awaited
+     * (`@contract runtask.forward_sink_never_faults_the_run`).
      */
     onForwardEvent?: (event: TaskEvent) => void;
     /**
@@ -1815,6 +1852,12 @@ export interface RunInternals {
     /** The run-local per-tool-call detach hub. runtask creates it and exposes
      *  `TaskStream.detach(toolCallId)`; the hands Bash tool threads `signalFor(toolCallId)` into env.exec. */
     detachHub?: import("../tool-detach.js").ToolDetachHub;
+    /** The run's forwarding-failure bookkeeping for {@link onForwardEvent} — ENGINE-owned and opaque,
+     *  minted once per run by `Runner.runTaskStream` and carried by every later COPY of this object (the
+     *  prepare re-spread, a placement-root rebind, a child's snapshot), which is what makes "announced once
+     *  per run" true across the lanes that forward. A caller value is overridden like the refs beside it;
+     *  absent ⇒ the door mints a per-object one, so containment never depends on the threading. */
+    forwardScope?: import("./forward-sink.js").ForwardSinkScope;
     /**
      * The Runner's per-session read-file-state seats (CC parity: readFileState is
      * session-scoped). Always set by the Runner's own prepare call (overriding any caller value, like