@sema-agent/core 5.65.0 → 6.0.0

package/dist/core/runner/compaction-call-options.d.ts

@@ -29,6 +29,99 @@ import type { Prepared } from "./prepare-task.js";
  * task has no hands (no `readTaskFile` ⇒ nothing can be re-read).
  */
 export declare function buildWorkingFileAttachments(spec: TaskSpec, prepared: Prepared): MaybeCompactOptions["workingFileAttachments"];
+/**
+ * #500 — `MaybeCompactOptions.contextInstructionFiles`: the seat that delivers the deployment's own
+ * instruction-file content (the CLAUDE.md family) to the SUMMARIZER, assembled once here and spread
+ * on all three lanes. Without it the compaction boundary is the one place a long task loses the
+ * standing instructions every other turn has been reading — and it loses them exactly where the
+ * summary REPLACES the transcript that carried them, so the loss is durable.
+ *
+ * WHICH BYTES, and why the neighbours are not candidates. `Prepared.projectInstructionContent` =
+ * the RAW loader text (`ProjectMemoryLoad.content`, exactly the string prepare-task feeds
+ * `composeMemoryBlock(projectMem, "project")`), captured beside the existing `instructionSources`
+ * capture under the SAME non-blank predicate that composes the project layer:
+ *   · the assembled `memoryBlock` is NOT a candidate. It is the memory ENGINE's composed layers —
+ *     bytes the model itself authored in-band this session through the memory tools — with the
+ *     project layer appended at the tail. The seat's contract is host/systemPrompt tier and says in
+ *     terms: never from tool output, model text, or any other in-band channel. Handing
+ *     model-authored bytes an envelope whose preamble tells the summarizer they may instruct it is
+ *     the laundering shape, not a purity nit. (Mechanically moot too — `memoryBlock` is a
+ *     prepare-task local and never reaches `Prepared`.)
+ *   · the COMPOSED project block is not it either, and this one is checkable rather than a
+ *     judgement: `contextInstructionFilesSection` neutralizes the whole authority family
+ *     (ENGINE_AUTHORITY_ENVELOPE_TAGS) over its payload, and `user_memory`/`scope` ARE in that
+ *     family — so feeding a composed block would have the engine rewrite the tags of its own
+ *     composition. Raw text in, one fence at the mint.
+ *   · `prepared.instructionSources` carries path + contentHash only, by design (core never learns a
+ *     file-name policy), so it cannot serve this seat at all.
+ *
+ * PROVENANCE, stated plainly because "the host supplies it" is the easy half of the truth. On this
+ * engine the value is REPOSITORY-CONTROLLED text: the loading block one file over calls a CLAUDE.md
+ * of unknown authorship untrusted in so many words, the MAIN lane's own framing tells the model it is
+ * "repository-controlled DATA, not instructions to obey", and this seat hands the same bytes to the
+ * summarizer with instruction standing for the summarization task. Delivery THROUGH a host callback
+ * is not host AUTHORSHIP: a prior agent, or anyone who can land a commit, can write a
+ * "## Compact Instructions" section, and the mint's neutralization stops tag breakout — not a
+ * sentence asking for a fact to be left out of the summary that replaces the transcript.
+ * Why it is nevertheless this value: the seat's own contract names this path ("hosts pass the same
+ * instruction-file content their prompt assembly mounts... on the runner path"), the parity form this
+ * channel exists to reach reads the user's and the project's instruction files at every boundary with
+ * exactly this standing, and the two alternatives are worse for reasons above rather than better.
+ * The standing is also narrower than the framing gap suggests — the section's preamble scopes it to
+ * guidance about HOW to summarize and classifies the rest as background — and a deployment that does
+ * not want it has two exits that need no code: do not wire the loader, or return content it vouches
+ * for. Recorded as an open design candidate rather than built here, because it is a contract change
+ * and not a wiring one: a SEPARATE deployment-vouched summarization-instructions seat, leaving
+ * repository-derived context at data tier.
+ *
+ * RULING ① — BOTH summary forms, no per-form split. Fork eligibility is decided per pass INSIDE
+ * maybeCompact (main-model-only, recorded-request-present, not lossy), so a call site cannot say
+ * "independent form only"; the closest approximation — pass the seat only when `prepared.compModel`
+ * is set, since an independent compaction model has no main prefix to fork — leaves the hole the
+ * wrong way round: the configuration it does NOT cover (no compaction model) is precisely the one
+ * where a fork degrades mid-pass to the independent form, which would then run WITHOUT the files.
+ * Feeding both forms closes that case by construction, and the library face already handles the fork
+ * half (the section rides the APPENDED instruction message, never the cached prefix, so the fork's
+ * whole economic point is untouched).
+ *
+ * RULING ② — no new size knob. The bound is the library's own `fitContextInstructionFilesSection`
+ * (independent form: cap against the compaction model's window, disclosed elision, and a complete
+ * yield when not even the framing fits). Its three KNOWN LIMITS are accepted here KNOWINGLY, as the
+ * pre-condition of this wiring rather than something it discovered: a token-dense payload (CJK,
+ * emoji) can pass a chars-domain fit and still overflow the gateway's tokenizer; an unknown
+ * `contextWindow` leaves the section unbounded (the conversation clamp declines to guess there too);
+ * and the FORK form cannot fit at all — its bound is a prompt-too-long that degrades ONCE to the
+ * independent form, which the engine's own note records as real but NOT total (an oversize rejection
+ * the classifier cannot read as prompt-too-long returns terminally instead).
+ *
+ * HOW BIG THAT ACCEPTANCE ACTUALLY IS — measured, because the sentence above is easy to read more
+ * comfortably than it deserves. The fitted form is NOT the default path: when a fork is eligible and
+ * the model answers in its envelope, the fork IS the pass, and its section is delivered WHOLE at any
+ * size. The independent form — the only one that fits — runs when there is no fork to take or the
+ * fork's answer did not conform. Both facts are pinned in the REF-A2 suite (a 55 KB payload: whole on
+ * the fork, elided on the independent fallback). And when a limit does bite, the failure is not a
+ * quiet degradation: the section is a FIXED part of the request, the reactive retry loop may drop
+ * only CONVERSATION groups, so a request the SECTION overflowed cannot converge and the boundary
+ * fails — the task loses that compaction (or that prompt-too-long recovery, or its end-of-task
+ * summary) rather than sending a shorter one. The exposure is what the wiring widened: this was
+ * previously reachable only by hosts calling the library directly, and is now reachable by every
+ * deployment that wires `loadProjectMemory` with a large instruction file and an unknown or small
+ * window. Making the section participate in the retry loop is the structural answer; it is a change
+ * to that loop's contract, tracked at the library face, and a runner-side knob would only move the
+ * decision to a place with less information.
+ *
+ * WHAT IT COSTS, measured rather than rounded: every deployment that wires `loadProjectMemory` now
+ * sends its instruction-file content plus EXACTLY 716 chars of framing (the preamble and the fence)
+ * on EVERY summarization request, both forms, once per pass — where a real project instruction file
+ * in this family runs to tens of KB, so the payload, not the framing, is the bill. The number is
+ * pinned in the REF-A2 suite against the engine's own renderer, so a preamble edit shows up as a
+ * changed assertion rather than as prose drifting away from the code it describes.
+ * Deployments that never wired the loader pay nothing: the key is absent, not
+ * `undefined`, so their requests are byte-identical to the pre-wiring shape on the independent and
+ * UPDATE passes (the FORK form appends its ~860-char authority clause with or without the seat, and
+ * always did).
+ */
+export declare function contextInstructionFilesOption(prepared: Prepared): Partial<Pick<MaybeCompactOptions, "contextInstructionFiles">>;
 /**
  * design/169-A — the CC-form fork seam, assembled identically on all three lanes (REF-A2): the
  * summary request forks the main lane's latest real request (recorded by prepare-task's provider

package/dist/core/runner/compaction-call-options.js

@@ -14,6 +14,9 @@ export function buildWorkingFileAttachments(spec, prepared) {
         ...(typeof spec.compaction?.attachWorkingFiles === "object" ? spec.compaction.attachWorkingFiles : undefined),
     };
 }
+export function contextInstructionFilesOption(prepared) {
+    return prepared.projectInstructionContent !== undefined ? { contextInstructionFiles: prepared.projectInstructionContent } : {};
+}
 export function forkContextOption(prepared, disable) {
     return disable ? {} : { forkContext: prepared.lastBrainContext };
 }

package/dist/core/runner/memory-capture-optout.d.ts

@@ -0,0 +1,80 @@
+/**
+ * design/383 §3 — the session capture opt-out's ENTITLEMENT ADJUDICATOR (slice 3's core): one pure
+ * function every ingress shares — the prepare-time declaration, the resume-time standing-record
+ * re-check (§3.3), and the Runner flip verb's fresh-resolve closure — so the posture table cannot
+ * fork across call sites.
+ *
+ * The separation law (§3.3) is the module's spine: THIS adjudicator answers "may the declaration /
+ * the continued run proceed"; the one-way control-plane RECORD answers "how does this session run"
+ * (record wins for capture — nothing here ever re-enables capture for a recorded session; the
+ * governed/capture-required continuation arm refuses to RUN instead, keeping both promises: zero
+ * capture and zero out-of-policy running, availability paid).
+ *
+ * The two fault polarities, and why both are deliberate (the code-side home of the §3.1 cost
+ * table):
+ *  - `"open"` (and absent): a resolver fault ALLOWS the opt-out (+ named disclosure). Wrongly
+ *    allowing costs one uncaptured session — recoverable. Wrongly denying captures a session whose
+ *    user explicitly said no — irreversible (read, foldable into products, syncable). The
+ *    fail-safe faces the irreversible side's OPPOSITE, which is why this member is the documented
+ *    exception to the caps family's deny-on-outage degrade.
+ *  - `"governed"`: the deployment has EXPLICITLY declared the compliance side's irreversibility
+ *    (a retention-required principal acquiring an opt-out through an outage window) the heavier
+ *    one, so a fault/absent verdict refuses the run — fail-closed, the declared direction.
+ * A mutation flipping the governed fault arm to the open polarity must turn the G-姿态 escape pin
+ * red (m12).
+ */
+/** The screened posture (prepare-config-doors folds absent → `"open"`). */
+export type MemoryCapturePosture = "open" | "governed" | "capture-required";
+/** The per-principal entitlement input as RESOLVED for this adjudication:
+ *  - `value` — `RuntimeCaps.allowMemoryOptOut` when the resolver answered a boolean; `undefined`
+ *    when absent OR when the resolver faulted (the F2 fault-transit contract: a fault must never
+ *    be encoded as an explicit value);
+ *  - `faulted` — the resolve THREW / timed out / answered a non-boolean (the non-boolean case is
+ *    a fault by the member's own contract, never truthiness-read). Distinguished from a clean
+ *    `undefined` only for DISCLOSURE under `"open"` (both allow there) — under `"governed"` both
+ *    are the same refusal (verdict absent = face fault). */
+export interface CaptureEntitlementInput {
+    value: boolean | undefined;
+    faulted: boolean;
+}
+export type CaptureOptOutVerdict = {
+    allowed: true;
+    /** Present ⇔ the open-posture fault arm fired: the opt-out takes effect AND the caller owes
+     *  the named `onError({phase:"config"})` disclosure line (this string). */
+    faultDisclosure?: string;
+} | {
+    allowed: false;
+    /** Always `memory.capture_optout_denied` (terminal). The caller throws it; a DECLARATION
+     *  denial must leave zero record residue (§2.1 order invariant — adjudicate BEFORE marking). */
+    code: "memory.capture_optout_denied";
+    detail: string;
+};
+/**
+ * Adjudicate one capture opt-out ingress. `subject` names what is being adjudicated, for the
+ * refusal detail only: `"declaration"` (a `capture:"off"` spelling / the flip verb) or
+ * `"standing-record"` (a resumed session whose one-way record stands — §3.3: under
+ * governed/capture-required the question is whether the run may CONTINUE; the record's zero-capture
+ * promise is not on the table).
+ */
+export declare function adjudicateCaptureOptOut(input: {
+    posture: MemoryCapturePosture;
+    entitlement: CaptureEntitlementInput;
+    subject: "declaration" | "standing-record";
+}): CaptureOptOutVerdict;
+/** The typed terminal refusal builder (one spelling for every ingress). */
+export declare function captureOptOutDeniedError(detail: string): Error & {
+    code: string;
+};
+/** The typed could-not-record refusal (§2.8 — never a success notice's sibling; the caller mints
+ *  {@link import("../memory-engine/engine.js").memoryCaptureOptOutUnpersistedNotice} beside it).
+ *
+ *  `ingress` is REQUIRED (internal builder, both call sites in prepare-memory state it): the two
+ *  arms' throws settle different things and the message must say which. The declaration arm's throw
+ *  is whitelisted out of prepare-memory's fail-open catch and refuses the RUN; the host flip verb's
+ *  throw rejects only the verb promise — `captureOptedOut` is assigned below it — so the run
+ *  continues with capture still ON. One sentence for both said "refusing to run", which was false
+ *  in the direction that matters: it told the caller the session had stopped capturing when it had
+ *  not. */
+export declare function captureOptOutUnpersistedError(sessionId: string, ingress: "declaration" | "flip-verb"): Error & {
+    code: string;
+};

package/dist/core/runner/memory-capture-optout.js

@@ -0,0 +1,53 @@
+export function adjudicateCaptureOptOut(input) {
+    const { posture, entitlement, subject } = input;
+    const what = subject === "standing-record" ? "continuing a session whose one-way capture opt-out record stands" : "the session memory-capture opt-out declaration";
+    if (posture === "capture-required") {
+        return {
+            allowed: false,
+            code: "memory.capture_optout_denied",
+            detail: `${what} is refused: this deployment declares memoryCapturePolicy "capture-required" (forced retention, resolver-independent). ` +
+                (subject === "standing-record"
+                    ? `The standing record keeps its zero-capture promise — the session is refused rather than run out of policy; start a new session without the opt-out.`
+                    : `Remove the memory.capture declaration and resubmit.`),
+        };
+    }
+    if (posture === "governed") {
+        if (entitlement.value === true)
+            return { allowed: true };
+        return {
+            allowed: false,
+            code: "memory.capture_optout_denied",
+            detail: entitlement.value === false
+                ? `${what} is refused: the entitlement resolver answered allowMemoryOptOut=false for this principal (governed posture — the deployment requires capture for it).`
+                : `${what} is refused: memoryCapturePolicy "governed" requires an explicit per-principal allowMemoryOptOut verdict and none was resolvable (${entitlement.faulted ? "resolver fault" : "verdict absent"}) — fail-closed by the deployment's own declaration (a retention-required principal must not acquire an opt-out through an outage window).`,
+        };
+    }
+    if (entitlement.value === false) {
+        return {
+            allowed: false,
+            code: "memory.capture_optout_denied",
+            detail: `${what} is refused: the entitlement resolver answered allowMemoryOptOut=false for this principal.`,
+        };
+    }
+    if (entitlement.faulted) {
+        return {
+            allowed: true,
+            faultDisclosure: `the runtime-caps resolve faulted while adjudicating a memory-capture opt-out; under the "open" posture the opt-out takes effect anyway ` +
+                `(privacy-side irreversibility wins the fault arm — an explicit allowMemoryOptOut=false is the only denial). Repair the resolver if denial was intended.`,
+        };
+    }
+    return { allowed: true };
+}
+export function captureOptOutDeniedError(detail) {
+    const e = new Error(`memory capture opt-out denied: ${detail}`);
+    e.code = "memory.capture_optout_denied";
+    return e;
+}
+export function captureOptOutUnpersistedError(sessionId, ingress) {
+    const e = new Error(`memory capture opt-out could not be durably recorded for session ${sessionId} (control-plane write failed) — ` +
+        (ingress === "declaration"
+            ? `refusing to run under an opt-out that would silently stop holding at the next resume. Nothing ran and nothing was captured.`
+            : `the opt-out request is REJECTED and not applied: the run continues with memory capture still ON. Nothing was recorded, so an identical retry fails the same way.`));
+    e.code = "memory.capture_optout_unpersisted";
+    return e;
+}

package/dist/core/runner/prepare-config-doors.d.ts

@@ -196,6 +196,11 @@ export interface PrepareConfigDoorsResult {
      *  the synchronous pre-await stretch, screened (#123), absent folded to the `"carry"` default.
      *  The memory phase constructs every engine with THIS value — never a live deps re-read. */
     memoryProvenance: "off" | "carry";
+    /** owned — the NORMALIZED memory-capture posture (design/383 §3.1): the deps seat read ONCE,
+     *  screened (#123 — a bad value refuses, never folds), absent folded to `"open"`. The capture
+     *  opt-out adjudicator consumes THIS value on every leg (declaration, resume record re-check,
+     *  and the flip verb's frozen closure) — never a live deps re-read. */
+    memoryCapturePolicy: "open" | "governed" | "capture-required";
     /** owned — validated deployment governance windows (undefined = ungoverned). */
     usageWindows: readonly UsageWindow[] | undefined;
     /** owned, out-param cell — created EMPTY here; the brain-call wiring later installs into

package/dist/core/runner/prepare-config-doors.js

@@ -225,6 +225,21 @@ export function prepareConfigDoors(input) {
         throw e;
     }
     const memoryProvenance = memoryProvenanceRaw === "off" ? "off" : "carry";
+    const memoryCapturePolicyRaw = deps.memoryCapturePolicy;
+    if (memoryCapturePolicyRaw !== undefined && memoryCapturePolicyRaw !== "open" && memoryCapturePolicyRaw !== "governed" && memoryCapturePolicyRaw !== "capture-required") {
+        const got = typeof memoryCapturePolicyRaw === "string"
+            ? JSON.stringify(memoryCapturePolicyRaw.length > 64 ? `${memoryCapturePolicyRaw.slice(0, 64)}…` : memoryCapturePolicyRaw)
+            : memoryCapturePolicyRaw === null
+                ? "null"
+                : Array.isArray(memoryCapturePolicyRaw)
+                    ? "an array"
+                    : typeof memoryCapturePolicyRaw;
+        const e = new Error(`RunnerDeps.memoryCapturePolicy must be "open", "governed" or "capture-required" when present (got ${got}) — ` +
+            `an unevaluable capture posture is refused loudly, never folded to any posture (the fault arms differ per posture, so a guess would pick a polarity nobody configured).`);
+        e.code = "config.memory_capture_policy";
+        throw e;
+    }
+    const memoryCapturePolicy = memoryCapturePolicyRaw === "governed" ? "governed" : memoryCapturePolicyRaw === "capture-required" ? "capture-required" : "open";
     if (spec.resumeAtMode !== undefined) {
         if (spec.resumeAt === undefined) {
             const e = new Error(`resumeAtMode "${spec.resumeAtMode}" requires resumeAt (there is no branch target to position against)`);
@@ -420,6 +435,7 @@ export function prepareConfigDoors(input) {
         modelGate,
         memoryDelegationEvidence,
         memoryProvenance,
+        memoryCapturePolicy,
         usageWindows,
         brainCallGuardrailRef,
         brainCallGuardrailMs,

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -13,6 +13,91 @@ import type { PrepareResume, RunInternals } from "./prepare-task.js";
  *  the console arm's key is the process itself, which only this seam can refresh. Moved WITH the
  *  phase (design/238 B-5); prepare-task.ts keeps a re-export so the existing import sites stand. */
 export declare function __resetReadFaceClampAnnouncement(): void;
+/**
+ * #483 rung-1 — the Runner's per-session read-file-state seats (CC parity: readFileState is minted
+ * once per REPL session and mutated across turns; it has NO turn-boundary and NO abort clear site —
+ * its only clears are compaction/fork/subagent-cleanup/dispose). sema's map stays per-task (the §11
+ * ruling-A closure wiring), so the SESSION scope lives here instead: prepare adopts each task's live
+ * map under its sessionId, and the next same-session, same-Runner task INHERITS it (through the same
+ * containment judgment the transcript-replay seed applies — see `inheritSessionReadFileState`).
+ *
+ * This seat is a CACHE, never an authority:
+ *  - a durable resume's checkpoint seed stays the sole authority on that leg (the seed was cut
+ *    atomically with the leaf; this seat may be older OR newer than it);
+ *  - a cross-process continuation misses here and falls back to the transcript replay (rung-2);
+ *  - eviction (the LRU cap, a Runner restart) degrades to that same replay — never to wrong state.
+ *
+ * Bounded: an LRU over sessionIds (insertion-order refresh on read), because the SessionStore's own
+ * eviction is not observable from here — a dropped seat costs one transcript replay, nothing else.
+ * The stored value is the task's LIVE map (object identity), so in-turn mutations — tool write-backs,
+ * and above all the RB-197 compaction clear — are the seat's truth by construction; a snapshot copy
+ * here would resurrect summarized-away reads on the next turn.
+ *
+ * BRANCH BINDING (codex r1+r2, adopted): a sessionId alone does not name a transcript — the same id
+ * can be rebranched (`resumeAt`), rewound out-of-band, or DELETED and re-created (`release()` + the
+ * default create-on-miss acquire), and the seat's map would then vouch for reads the CURRENT branch
+ * never saw. Each seat therefore records `anchorLeafId` — a leaf on the lineage its task produced —
+ * and inheritance must first prove the CURRENT branch still descends from that anchor
+ * (see {@link sessionSeatAnchorHolds}). The anchor is written twice: at ADOPT (the leaf at prepare;
+ * `null` when the branch was still empty) and SEALED at the task's settle to the task's own tail
+ * (`reanchor`). A `null` anchor is NEVER inheritable (codex r2: "the branch is non-empty now" proves
+ * nothing about WHOSE messages those are — another Runner repopulating a released id, or a session
+ * import, makes a non-empty branch that never contained this seat's reads). An unprovable anchor
+ * falls back to the transcript replay, which reads the current branch by construction — cost, never
+ * wrongness.
+ */
+export declare class SessionReadFileStates {
+    private readonly seats;
+    private static readonly CAP;
+    /** The session's seat row, or undefined (cross-process / evicted / first turn) ⇒ caller replays.
+     *  The caller must verify the anchor against the session's CURRENT branch before using `state`. */
+    get(sessionId: string): {
+        state: ReadFileState;
+        anchorLeafId: string | null;
+    } | undefined;
+    /** Adopt THIS task's live map as the session's seat (every hands leg: fresh, continuation, resume).
+     *  `anchorLeafId` = the session's leaf as read at THIS prepare (null = the branch was empty; a
+     *  null-anchored seat is not inheritable until the settle-time {@link reanchor} names a real leaf). */
+    adopt(sessionId: string, state: ReadFileState, anchorLeafId: string | null): void;
+    /** #483 codex r2 — the settle-time SEAL: re-anchor the seat to the finished task's own tail, so a
+     *  first-task (null-anchor) seat becomes inheritable only through a leaf its task provably wrote.
+     *  Identity-guarded: touches the row only while it still holds THIS task's map (a later prepare on
+     *  the same session has already replaced the seat and owns its own anchor). */
+    reanchor(sessionId: string, state: ReadFileState, anchorLeafId: string): void;
+}
+/**
+ * #483 (codex r1+r2) — does the session's CURRENT branch still descend from the seat's anchor?
+ * TRUE is the licence to inherit; anything unprovable answers FALSE (the caller then replays the
+ * transcript — the fail-closed direction costs a rebuild, never admits a wrong entry).
+ *
+ *  - anchor `null`: NEVER inheritable (r2). The seat was adopted on an empty branch and its task
+ *    never sealed (crashed pre-settle, or the leaf read failed) — "the branch is non-empty now"
+ *    would also be true of a released-and-repopulated id or an imported log, whose messages are not
+ *    this seat's lineage. The settle-time reanchor is what upgrades such a seat to a real leaf.
+ *  - anchor non-null: holds iff walking parentIds from the current leaf reaches the anchor within
+ *    a bounded number of steps (the walk length is one task's appends in the ordinary continuation).
+ *    A rebranch/rewind moved the leaf OFF the anchor's subtree ⇒ the walk misses ⇒ no inherit; a
+ *    recreated/foreign log does not contain the anchor ⇒ same answer; a re-IMPORT of the same log
+ *    keeps the anchor's lineage ⇒ inheritance stays correct there by the same test.
+ *  - a COMPACTION on the walked segment (A-082 idx2): refuses, even though the branch is perfectly
+ *    intact. The walked segment is exactly what landed AFTER this seat was anchored, and a
+ *    compaction there summarized older Read results OUT of the context the model will be shown —
+ *    the very state RB-197 clears from the live map at the landing site. That clear reaches the seat
+ *    only when the SAME Runner did both (the seat IS that map, by object identity); a second Runner
+ *    on the shared durable session clears its own map and commits the compaction as an ORDINARY
+ *    LINEAR APPEND, which every other test here passes. Inheriting across it would let requireRead
+ *    and checkStale both pass on a read whose card the model no longer has — a blind edit from a
+ *    summarized-away recollection, the exact failure the RB-197 clear exists to prevent. Refusing
+ *    costs one transcript replay, and the replay reads the POST-compaction branch by construction,
+ *    so the fail-closed direction is also the CORRECT state. A compaction at or ABOVE the anchor is
+ *    not on the walked segment and does not refuse: the seat that observed it already carries its
+ *    clear (P-483-4), and an ordinary foreign turn with no compaction still inherits (G-483-5) —
+ *    dropping every seat a foreign Runner touched would restore the cross-turn amnesia #483 ended.
+ */
+export declare function sessionSeatAnchorHolds(getEntry: (id: string) => Promise<{
+    parentId: string | null;
+    type?: string;
+} | null | undefined>, anchorLeafId: string | null, currentLeafId: string | null): Promise<boolean>;
 export interface PrepareHandsReadFaceInput {
     /** owned (value) — `ownedEnv !== undefined || deps.executionEnv !== undefined`, computed in the
      *  driver: the phase's own branch condition (hands mount vs the hands-less resolver arm). */
@@ -34,8 +119,9 @@ export interface PrepareHandsReadFaceInput {
     resume: Pick<PrepareResume, "seed"> | undefined;
     /** borrowed-readonly — the acquired session (B-3 output), as a Pick (相 API 规则件 R-4: receiver
      *  preserved): `getWorkspaceState` feeds the design/155 continuation rung; `buildContext` feeds
-     *  the transcript replay. */
-    session: Pick<StoredSession, "getWorkspaceState" | "buildContext">;
+     *  the transcript replay; `getStorage`/`getEntry` feed the #483 seat-anchor verification (one
+     *  leaf read per prepare + a bounded parent walk on the inherit leg only). */
+    session: Pick<StoredSession, "getWorkspaceState" | "buildContext" | "getStorage" | "getEntry">;
     /** borrowed-readonly — the acquired session's id, for error/notice tags and the band's session
      *  registration. */
     sessionId: string;
@@ -59,15 +145,23 @@ export interface PrepareHandsReadFaceInput {
     model: Model;
     /** borrowed-readonly — the task-spec seats this phase reads, as a Pick over the SAME spec object
      *  (R-4). `tools` feeds only the band shadow check; `envFacts` only the advertised scratchpad. */
-    spec: Pick<TaskSpec, "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "handsReadOnly" | "readDenyPatterns" | "readFace" | "oneShot" | "sessionId" | "tools">;
+    spec: Pick<TaskSpec, "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "handsReadOnly" | "readDenyPatterns" | "readFace" | "oneShot" | "resumeAt" | "sessionId" | "tools">;
     /** borrowed-readonly — the deployment seats this phase reads, as a Pick over the SAME deps
      *  object (R-4: `deps.onError?.()` keeps its receiver; a new deps read must widen this Pick).
      *  `readDenyBuiltinTiers`/`readDenyBuiltinExclude` are SNAPSHOTTED before the first await that
      *  precedes the toolkit compile (#245/#244 — the caller retains these arrays by reference). */
     deps: Pick<RunnerDeps, "onError" | "onNotice" | "tracer" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "readFace" | "permissionRuleOrg" | "hands">;
     /** borrowed-readonly — the trusted spawn-side seats the band forwards: the finished-command
-     *  notification lane and the mid-flight detach hub. */
-    internals: Pick<RunInternals, "onTaskNotification" | "detachHub"> | undefined;
+     *  notification lane, the mid-flight detach hub, and (#483 rung-1) the Runner's per-session
+     *  read-state seats (absent on a standalone prepare ⇒ the transcript-replay rung covers alone). */
+    internals: Pick<RunInternals, "onTaskNotification" | "detachHub" | "sessionReadStates"> | undefined;
+    /** borrowed-readonly (A-082 idx7) — ABSOLUTE paths this prepare's design/381 restore wrote, deleted,
+     *  or failed to write. Every read-state seed above describes the PRE-restore tree, so these keys are
+     *  dropped from the map: the engine replaced those bytes itself, and a surviving entry makes the
+     *  next refusal blame "the user or a linter" for the engine's own write. Absent (the common case)
+     *  when no file restore ran. Fail-closed by construction — dropping a read record only ever
+     *  produces refusals. */
+    restoredFilePaths?: readonly string[];
     /** borrowed (ref cell; the REF itself is never replaced) — design/138 S2-C late-bound memory
      *  write gate: the band's beforeWrite closure reads `.current` call-time; prepareMemory (driver,
      *  after this phase) installs the gate. Declared in the driver because the SAME ref feeds
@@ -107,6 +201,9 @@ export interface PrepareHandsReadFaceInput {
      *  band's Read/notebook/PDF trailer outlets bump keys on it at tool-execute time (the driver owns
      *  the object and folds it into result stats). */
     reminderDisclosureCounts: import("../reminder-disclosure.js").ReminderDisclosureCounts;
+    /** design/381 — the first-touch history hook prepare built (present iff a fileHistoryStore is
+     *  wired and the run mounts a real fs env); threaded to the write band's trackFileEdit seat. */
+    trackFileEdit?: import("../types.js").TrackFileEditHook;
 }
 /** The phase's outputs (相 API 规则件 four-class form) — ALL settled before the return; the driver
  *  binds them as fresh consts (R-5) except the inverted-closure trio and the two shellGated bits,
@@ -190,6 +287,14 @@ export interface PrepareHandsReadFaceResult {
      *  misses Monitor/worktree, which are hands — both directions wrong for this consumer). Empty on
      *  a hands-less leg (nothing mounts on the env; the driver's env mounts are hands-gated too). */
     envHandToolNames: Set<string>;
+    /** owned (#483 codex r2+r3) — the settle-time SEAT SEAL: re-anchors the session seat to the
+     *  task's OWN last-committed entry (see {@link SessionReadFileStates.reanchor}). The driver calls
+     *  it once at the run's settle (every terminal, suspend included), under the session lock, passing
+     *  the last entryId ITS OWN run committed (the message_committed lane) — never a re-read of the
+     *  shared session leaf, which a concurrent writer on another Runner could have moved onto a branch
+     *  this task's reads were never on (codex r3). No commits observed ⇒ no-op (the adopt-time anchor
+     *  stands). Synchronous, never throws. Undefined ⇔ hands-less / no seat channel. */
+    sealReadStateSeat: ((ownCommittedTailEntryId: string | undefined) => void) | undefined;
 }
 export declare function resolveHandsLessReadFace(input: PrepareHandsReadFaceInput): PrepareHandsReadFaceResult;
 /** The hands-MOUNT branch — the async half of the phase (see the module header for the contract).

package/dist/core/runner/prepare-hands-readface.js

@@ -2,8 +2,9 @@ import { emitTrace } from "../trace.js";
 import { StubExecutionEnv } from "../stub-env.js";
 import { hasBackgroundShell } from "../background-shell.js";
 import { defaultTaskRegistry } from "../task-registry.js";
-import { bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, pdfModelCapabilitiesOf, resolveReadDenyBuiltins, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
-import { resolveKey } from "../../tools/fs/safety.js";
+import { bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, pdfModelCapabilitiesOf, resolveReadDenyBuiltins, inheritSessionReadFileState, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
+import { resolveKey, sha256 } from "../../tools/fs/safety.js";
+import { normalizeFileText } from "../../tools/fs/encoding.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
 import { deliverEngineNotice } from "../types.js";
 import { rebaseWorkspacePath } from "./prepare-workspace-restore.js";
@@ -12,6 +13,49 @@ let readFaceClampConsoleAnnounced = false;
 export function __resetReadFaceClampAnnouncement() {
     readFaceClampConsoleAnnounced = false;
 }
+export class SessionReadFileStates {
+    seats = new Map();
+    static CAP = 1024;
+    get(sessionId) {
+        const seat = this.seats.get(sessionId);
+        if (seat !== undefined) {
+            this.seats.delete(sessionId);
+            this.seats.set(sessionId, seat);
+        }
+        return seat;
+    }
+    adopt(sessionId, state, anchorLeafId) {
+        this.seats.delete(sessionId);
+        this.seats.set(sessionId, { state, anchorLeafId });
+        while (this.seats.size > SessionReadFileStates.CAP) {
+            const oldest = this.seats.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.seats.delete(oldest);
+        }
+    }
+    reanchor(sessionId, state, anchorLeafId) {
+        const seat = this.seats.get(sessionId);
+        if (seat !== undefined && seat.state === state)
+            seat.anchorLeafId = anchorLeafId;
+    }
+}
+export async function sessionSeatAnchorHolds(getEntry, anchorLeafId, currentLeafId) {
+    if (anchorLeafId === null)
+        return false;
+    let id = currentLeafId;
+    for (let steps = 0; id !== null && steps < 100_000; steps++) {
+        if (id === anchorLeafId)
+            return true;
+        const entry = await getEntry(id);
+        if (entry === null || entry === undefined)
+            return false;
+        if (entry.type === "compaction")
+            return false;
+        id = entry.parentId;
+    }
+    return false;
+}
 function assertStringArraySeat(value, seat, entryLaw) {
     if (value === undefined)
         return;
@@ -74,6 +118,7 @@ export function resolveHandsLessReadFace(input) {
         envHandToolNames: new Set(),
         shellGatedBash: false,
         shellGatedMonitor: false,
+        sealReadStateSeat: undefined,
     };
 }
 export async function prepareHandsMount(input) {
@@ -84,6 +129,7 @@ export async function prepareHandsMount(input) {
     assertStringArraySeat(deps.readDenyPatterns, "RunnerDeps.readDenyPatterns", "compiler-owned");
     assertStringArraySeat(spec.readDenyPatterns, "TaskSpec.readDenyPatterns", "compiler-owned");
     let readFileStateForCheckpoint;
+    let sealReadStateSeat;
     let seedContextFiles;
     let handsCwdRef;
     let workspaceStateSettle;
@@ -205,14 +251,58 @@ export async function prepareHandsMount(input) {
         if (resume !== undefined && (seedReadFaceSection === undefined || seedReadFaceSection.face === "roots"))
             liveReadFace = "roots";
         resolvedReadFace = liveReadFace;
+        const sessionSeats = input.internals?.sessionReadStates;
+        let seatLeafId;
+        try {
+            seatLeafId = (await session.getStorage().getLeafId()) ?? null;
+        }
+        catch {
+            seatLeafId = undefined;
+        }
+        const judgeKey = async (path) => {
+            const rk = await resolveKey(executionEnv, rootCanonical, path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, liveReadFace);
+            return rk.ok ? rk.key : undefined;
+        };
         if (resume === undefined && spec.sessionId !== undefined) {
-            const prior = await session.buildContext().catch(() => undefined);
-            for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
-                const rk = await resolveKey(executionEnv, rootCanonical, rec.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, liveReadFace);
-                if (rk.ok)
-                    seedReadFileStateFromTranscript(readFileState, rk.key, rec.content, rec.at);
+            const seatRow = spec.resumeAt === undefined && seatLeafId !== undefined ? sessionSeats?.get(sessionId) : undefined;
+            const inheritedSeat = seatRow !== undefined && (await sessionSeatAnchorHolds((id) => session.getEntry(id), seatRow.anchorLeafId, seatLeafId))
+                ? seatRow.state
+                : undefined;
+            if (inheritedSeat !== undefined) {
+                await inheritSessionReadFileState(readFileState, inheritedSeat, judgeKey);
+            }
+            else {
+                const prior = await session.buildContext().catch(() => undefined);
+                for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
+                    const rk = await judgeKey(rec.path);
+                    if (rk !== undefined)
+                        seedReadFileStateFromTranscript(readFileState, rk, rec.content, rec.at);
+                }
+            }
+        }
+        if (input.restoredFilePaths !== undefined) {
+            for (const abs of input.restoredFilePaths) {
+                const k = await judgeKey(abs);
+                if (k === undefined)
+                    continue;
+                const entry = readFileState.get(k);
+                if (entry === undefined || entry.seededFromContext === true)
+                    continue;
+                const cur = await executionEnv.readTextFile(abs);
+                if (cur.ok && entry.hash === sha256(normalizeFileText(cur.value)))
+                    continue;
+                readFileState.delete(k);
             }
         }
+        if (seatLeafId !== undefined)
+            sessionSeats?.adopt(sessionId, readFileState, seatLeafId);
+        sealReadStateSeat =
+            sessionSeats !== undefined && seatLeafId !== undefined
+                ? (ownCommittedTailEntryId) => {
+                    if (ownCommittedTailEntryId !== undefined)
+                        sessionSeats.reanchor(sessionId, readFileState, ownCommittedTailEntryId);
+                }
+                : undefined;
         const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
             ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
             ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
@@ -222,6 +312,7 @@ export async function prepareHandsMount(input) {
             readFace: liveReadFace,
             reminderMark: input.reminderMark,
             reminderDisclosureCounts: input.reminderDisclosureCounts,
+            ...(input.trackFileEdit !== undefined ? { trackFileEdit: input.trackFileEdit } : {}),
             includeShell: handsIncludeShell,
             readOnly: handsReadOnly,
             ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
@@ -309,5 +400,6 @@ export async function prepareHandsMount(input) {
         envHandToolNames,
         shellGatedBash,
         shellGatedMonitor,
+        sealReadStateSeat,
     };
 }