@sema-agent/core 5.40.0 → 5.42.0

package/CHANGELOG.md

@@ -1,10 +1,108 @@
 # Changelog
 
-## 5.40.0 — 2026-08-18
+## 5.42.0 — 2026-08-18
 
-No BREAKING changes. Two behavioral narrowings disclosed below (the requestedCwd × workspace-restore
+### Added
+- `checkpointId` — a NON-SECRET stable checkpoint identity minted beside the secret resume
+  token at every suspend site (`mintCheckpointId` exported; `cp_` + uuid, independently minted —
+  not a token digest, so token-less projection surfaces still carry it). Rides `Checkpoint` and
+  `CheckpointSummary` (single-source projection); the park self-check faithfulness probe covers it
+  (a field-whitelisting backend that drops it reports `row_not_faithful`). Identification and
+  capability are separate axes; `token` semantics untouched (still secret, still the capability).
+  Legacy rows read compatibly (`checkpointId` absent; no backfill).
+- `task.user_followup_undrained` — stranded user FOLLOW-UPS at agent_end now announce under their
+  own EngineNotice code (one notice per family; `detail: { followUp, taskId? }`). **Code-family
+  change vs 5.41.0 (the only release with the conflated shape)**: a followUp-only stranding no
+  longer reports under `task.user_steer_undrained`, and the steer notice's `detail` no longer
+  carries a `followUp` count. Settled-frame keys unchanged. Mint extracted pure
+  (`undrainedUserInputNotices`) and pinned.
+
+### Changed
+- Grep's ripgrep legs parse `rg --null` records (ripgrep terminates its own path field with NUL)
+  instead of cutting lines at a guessed `:digits:` separator. The `:digits:`/`-digits-` boundary
+  mis-parse family is gone with the guessing: deny-guarded runs whose match TEXT contains a
+  cluster (e.g. `credentials:12:`) keep the rg fast path instead of over-tripping into a full-tree
+  JS rescan; the deny tripwire still judges every record (deny-hit abandonment unchanged) and the
+  partial legs drop a killed run's cut tail whole BEFORE judging (a half filename can no longer be
+  delivered as a result row or trip a pointless rescan).
+- The JS fallback scanner's unlimited form (`head_limit: 0`) is byte-bounded at the same figure as
+  the ripgrep exec pipe (`JS_GREP_OUTPUT_MAX_BYTES = MAX_EXEC_OUTPUT_BYTES`), head-preserving, with
+  an explicit truncation note when the ceiling is hit (previously unbounded accumulation in
+  rg-less environments).
+- design/238 B-5: the hands/read-face phase (P10) of `prepareTask` moved verbatim to
+  `prepare-hands-readface.ts` behind a dual seam (async hands mount / synchronous hands-less
+  resolver, dispatched on `handsEnabled`) — pure restructuring, zero behavior change; the
+  hands-less leg's synchronous-to-mount property is now pinned (an async wrapper there would open
+  a microtask window the original inline code never had).
+
+### Fixed
+- The Grep tool's structured details stop lying on byte-truncated and fenced-partial texts
+  (merged-code rescan): a byte-truncated run carries `truncated: true` and omits
+  `totalLines`/`numMatches` (the served count no longer poses as the total); a fenced partial's
+  bare `No matches.` line can no longer surface as a fabricated result row. The details assembly
+  is exported pure (`grepDetailFields`).
+- `ControlPlaneCorruptError` gains a structured `facet` discriminant (`"lock-ownership"`) at its
+  three ownership mint sites; the governance-export fold branches on it instead of message text.
+
+- 5.41.0's stranded-user-input notice conflated both families under the steer code ([the -2 item
+  of the 5.41 review]); split per family as above.
+
+## 5.41.0 — 2026-08-18
+
+No BREAKING changes. Three behavioral narrowings disclosed below (garbage values on the three
+tool-face seats now refuse loudly; the strict sidecar family's journal read and lock fence both
+join the fail-closed law).
+
+### Added
+
+- backlog #259 — user steers stranded at agent_end are ANNOUNCED, never silently dropped behind
+  their "queued" receipts: the terminal sweep hands ENGINE notes back for per-session redelivery,
+  but USER inputs have no redelivery semantics (a steer aimed at a finished run must not fire at
+  the next one) — their remnant counts now ride a dedicated harness sink, the `settled` frame
+  (additive `undrainedSteerCount`/`undrainedFollowUpCount`), and a new `EngineNotice` family
+  `task.user_steer_undrained`. The stranding window is a narrow race past the loop's final queue
+  check, which is exactly why it gets a loud terminal account.
+- backlog #251 — the mixed-version window of the design/186 ledger v2 is machine-detected:
+  recovering a v1-format journal over a v2 disk ledger (a shape only a pre-v2 process mints)
+  announces the old-writer-alive warning on the external-findings channel; recovery is unchanged.
+
+### Fixed
+
+- backlog #297 (ruled: narrow) — the three tool-face seats (`excludeTools` / `deferTools` /
+  `alwaysLoadTools`) get the fourth seat's value door: a garbage value (a bare string, a truthy
+  non-iterable, a non-string entry) refuses `config.tool_face_control` instead of stringifying
+  into a never-matching list, throwing an uncoded TypeError, or a falsy value silently reading as
+  absent. **Narrowing**: a deployment whose misspelled seat previously "worked" now hears it.
+- backlog #299 (ruled: fix alone) — the auto-mode classifier's action block bounds tool args at
+  48,000 chars (its own subject-level cap, deliberately above the delegation-review lanes'
+  12,000-per-field sampled payloads so their coverage notes ride through uncut): it was the one
+  unbounded string in the classifier's prompt, so a single long tool argument (a SendMessage body
+  needs nothing crafted, just length) could blow the classifier's context and trip the session
+  breaker out of auto mode.
+- backlog #307 (also filed as #256) — the journal-aware strict sidecar read joins the ENOENT-only
+  absence law: an EACCES/EIO journal read refused `ControlPlaneCorruptError` instead of silently
+  serving the pre-transaction state while a committed next state sat unreadable beside it — the
+  one fail-open left in the strict-read family. **Narrowing**: a deployment whose journal reads
+  were failing now hears it instead of silently reading stale.
+- backlog #255 — the sidecar lock's commit fence splits by family: the fail-closed LEDGER family
+  (challenge/lineage locked updates and the rebuild path) aborts on an UNPROVABLE owner
+  (absent/unreadable owner file) — "cannot disprove a steal" is not a fence; the calibration
+  family keeps its documented pre-token leniency, and a FOREIGN token aborts both as before.
+  **Narrowing**: within the ledger family only.
+- CHANGELOG erratum for 5.40.0 (recorded in that entry): the header counts THREE narrowings
+  (the defer alignment was the missing third) and the release date corrects to 08-17.
+
+## 5.40.0 — 2026-08-17
+
+No BREAKING changes. Three behavioral narrowings disclosed below (the requestedCwd × workspace-restore
 combination now refuses loudly; Grep's ripgrep leg withholds alias-spelled deny-listed paths it
-previously returned).
+previously returned; `deferMode: "auto"` never sweeps engine built-ins — a small-window deployment
+whose built-ins were previously deferred now carries their schemas inline, trading context bytes for
+the first-use activation error the sweep caused).
+
+<!-- Post-release erratum (2026-08-17, server review [4351]): the header originally said "Two
+behavioral narrowings" and dated the entry 2026-08-18 (pre-written); the defer narrowing was listed
+under Fixed but missing from this header, and the release actually shipped late on 08-17. -->
 
 ### Added
 

package/dist/core/auto-mode-prompt.js

@@ -102,5 +102,5 @@ export function renderAutoModeWindow(messages, options) {
 export function renderAutoModeAction(input) {
     const ask = input.askMessage ? `\npermission gate: ${input.askMessage}` : "";
     return (`\n## New action to classify (the agent's most recent action — evaluate THIS)\n\n` +
-        `[tool_call] ${input.req.toolName} ${JSON.stringify(input.req.args ?? {})}${ask}\n`);
+        `[tool_call] ${input.req.toolName} ${excerpt(JSON.stringify(input.req.args ?? {}), 48_000)}${ask}\n`);
 }

package/dist/core/checkpoint-store.d.ts

@@ -40,6 +40,15 @@ export type CheckpointToken = string & {
 };
 /** Mint a CSPRNG 128-bit checkpoint token (token-as-auth, §6/Q5): unguessable, never logged/in-URL. */
 export declare function mintCheckpointToken(): CheckpointToken;
+/**
+ * Mint the NON-SECRET stable checkpoint identity — identification and capability are separate
+ * axes (settledBy/approvalId precedent): `checkpointId` is safe to log, render, and correlate across
+ * frames (tool_approval cards, replay, resume, snapshots); {@link Checkpoint.token} stays the secret
+ * resume capability and never rides a display surface. Minted independently (NOT a token digest —
+ * a digest would make the id derivable only where the token is held, and the projection surfaces
+ * that need it most are exactly the token-less ones). Legacy rows have no id (absent, additive).
+ */
+export declare function mintCheckpointId(): string;
 /**
  * Who resumes a checkpoint, and how the resume `outcome` is interpreted. The `kind` is the discriminant
  * that {@link ResumeOutcome} must match at the resume entry (council #3: prevents a `task_done` gate
@@ -1327,6 +1336,10 @@ export interface ResolveExpectation {
  *  machine (pending → resolved | expired) that makes resume idempotent (§5). */
 export interface Checkpoint {
     token: CheckpointToken;
+    /** Non-secret stable identity ({@link mintCheckpointId}) — the display/correlation twin of
+     *  the secret `token` (identification vs capability, separate axes). Present on every row minted
+     *  since its introduction; absent ⇒ legacy row (read compatibly, no backfill). */
+    checkpointId?: string;
     /**
      * Schema version of this checkpoint (design/49 v1.5). Every live suspend stamps the version of the
      * FEATURE it carries (RESOURCE / BINDING / TOKEN / ORG_ADMISSION); {@link CURRENT_CHECKPOINT_VERSION}
@@ -1490,6 +1503,8 @@ export interface Checkpoint {
 export interface CheckpointSummary {
     /** The resume capability token ({@link Checkpoint.token}). */
     token: CheckpointToken;
+    /** Non-secret stable identity ({@link Checkpoint.checkpointId}) — absent on legacy rows. */
+    checkpointId?: string;
     /** The suspended task / session id ({@link Checkpoint.sessionId}). */
     sessionId: string;
     /** The multi-tenant scope this checkpoint lives in ({@link Checkpoint.scope}) — always equal to the query's. */

package/dist/core/checkpoint-store.js

@@ -1,10 +1,13 @@
-import { randomBytes } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { uuidv7 } from "../internal/harness.js";
 import { inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 export function mintCheckpointToken() {
     return randomBytes(16).toString("hex");
 }
+export function mintCheckpointId() {
+    return `cp_${randomUUID()}`;
+}
 export const PROBE_REASON_MAX = 200;
 export const PROBE_CAUSE_PATH_MAX = 200;
 const PROBE_CAUSE_MAX_SHOWN = 8;
@@ -234,6 +237,7 @@ export function summarizeCheckpoint(cp) {
     }
     return {
         token: cp.token,
+        ...(cp.checkpointId !== undefined ? { checkpointId: cp.checkpointId } : {}),
         sessionId: cp.sessionId,
         scope: cp.scope,
         gateKind: cp.gate.kind,

package/dist/core/memory-engine/file-backend.js

@@ -1166,6 +1166,17 @@ export class FileMemoryEngineBackend {
                         throw new ControlPlaneCorruptError(`transaction journal v1 ledger snapshot entry ${JSON.stringify(id)} is not a string: ${jp}`);
                     snapshotRows[id] = { rev };
                 }
+                try {
+                    const diskRaw = readControlFileOrAbsent(join(this.controlPlaneRoot, LEDGER_FILE), "committed-rev ledger");
+                    const diskParsed = diskRaw !== undefined ? JSON.parse(diskRaw) : undefined;
+                    if (diskParsed !== null && typeof diskParsed === "object" && "v" in diskParsed && diskParsed.v === LEDGER_SCHEMA_VERSION) {
+                        this.enqueueExternalItems([
+                            "memory ledger: recovering a v1-format journal over a v2 ledger — a pre-v2 process wrote AFTER this store migrated (mixed-version deployment window). Retire old readers/writers before further writes; see the v2 rollback runbook.",
+                        ]);
+                    }
+                }
+                catch {
+                }
             }
             for (const op of journal.ops) {
                 const invalid = journalOpInvalid(op, this.directoryRoot);
@@ -2160,7 +2171,7 @@ export class FileMemoryEngineBackend {
             held = undefined;
         }
         if (held !== token) {
-            throw new ControlPlaneCorruptError("txn lock ownership lost before commit (holder stalled past the stale deadline and was stolen from?) — transaction aborted, nothing was committed");
+            throw new ControlPlaneCorruptError("txn lock ownership lost before commit (holder stalled past the stale deadline and was stolen from?) — transaction aborted, nothing was committed", { facet: "lock-ownership" });
         }
     }
     async applyPatchesLocked(patches, lockToken) {
@@ -3230,7 +3241,7 @@ export class FileMemoryEngineBackend {
             }
             catch (err) {
                 if (err.code === FileMemoryEngineBackend.EXPORT_INCOMPLETE || err instanceof ControlPlaneCorruptError) {
-                    if (err instanceof ControlPlaneCorruptError && !err.message.includes("ownership"))
+                    if (err instanceof ControlPlaneCorruptError && err.facet !== "lock-ownership")
                         throw err;
                     return { custody: [], unbound: [], complete: false, unsliceableCustody: 0, reason: err instanceof Error ? err.message : String(err) };
                 }

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

@@ -11,8 +11,13 @@ export declare const CONTROL_PLANE_DIR = ".engine";
  *  silently degraded to an empty ledger / unclaimed root — that would let a corrupted (or truncated)
  *  sidecar erase CAS baselines and re-open the root claim. */
 export declare class ControlPlaneCorruptError extends Error {
+    /** Structured discriminant for callers that fold ONE corruption family and rethrow the rest —
+     *  branching on message text is banned (§B8). Only `"lock-ownership"` is minted today (the
+     *  recoverable-as-incomplete family); absent = every other corruption (a definite state, throw). */
+    readonly facet?: "lock-ownership";
     constructor(message: string, opts?: {
         cause?: unknown;
+        facet?: "lock-ownership";
     });
 }
 /**
@@ -248,6 +253,16 @@ export interface SidecarLockOptions {
  *  volume, revoked permission) makes mkdir fail forever while the lock dir it would stat never
  *  exists — spun this synchronous loop at full speed and never reached its own cap. */
 export declare function acquireSidecarLock(lockDir: string, opts?: SidecarLockOptions): string;
+/** 证伪式复审 L2-analog: re-verify the owner token at the COMMIT POINT — a stolen-from holder
+ *  aborts instead of writing over the stealer. A FOREIGN token always aborts (positive proof the
+ *  lock is someone else's now). What an ABSENT/UNREADABLE owner file means splits by caller family
+ *  (backlog #255): the fail-closed LEDGER family (`"strict"` — challenges/lineage via
+ *  lockedStrictUpdate) treats unprovable ownership as lost — those sidecars promise their commit
+ *  point is fenced, and "cannot disprove" is not a fence; the fail-open calibration family
+ *  (`"lenient"`, the pre-#255 shape — e.g. the scope registry, whose sidecars self-heal at the next
+ *  locked update) keeps the leniency, because its token writes are best-effort and an absent owner
+ *  file there is the documented pre-token degraded shape, not evidence of a steal. */
+export declare function assertSidecarLockOwnership(lockDir: string, token: string, what: string, mode?: "strict" | "lenient"): void;
 interface AnnouncementsRecord {
     /** How many announcements were dropped by the bounded-queue fold (disclosed at render). */
     folded: number;

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

@@ -7,9 +7,12 @@ const SCOPES_FILE = "scopes.json";
 export const CURSORS_FILE = "cursors.json";
 export const CONTROL_PLANE_DIR = ".engine";
 export class ControlPlaneCorruptError extends Error {
+    facet;
     constructor(message, opts) {
-        super(message, opts);
+        super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
         this.name = "ControlPlaneCorruptError";
+        if (opts?.facet !== undefined)
+            this.facet = opts.facet;
     }
 }
 function slugifyPath(absPath) {
@@ -598,16 +601,19 @@ function lockedJournaledUpdate(controlDir, fileName, mutate) {
         releaseSidecarLock(lock, token);
     }
 }
-function assertSidecarLockOwnership(lockDir, token, what) {
+export function assertSidecarLockOwnership(lockDir, token, what, mode = "lenient") {
     let held;
     try {
         held = readFileSync(join(lockDir, "owner"), "utf8");
     }
-    catch {
+    catch (err) {
+        if (mode === "strict" && err.code !== undefined) {
+            throw new ControlPlaneCorruptError(`${what}: sidecar lock ownership UNPROVABLE at commit (owner file ${err.code === "ENOENT" ? "absent" : `unreadable: ${err.code}`}) — a fail-closed ledger must not commit on a fence it cannot prove; update aborted`, { cause: err, facet: "lock-ownership" });
+        }
         return;
     }
     if (held !== token) {
-        throw new ControlPlaneCorruptError(`${what}: sidecar lock ownership lost before commit (holder stalled past ${LOCK_STALE_MS}ms and was stolen from) — update aborted`);
+        throw new ControlPlaneCorruptError(`${what}: sidecar lock ownership lost before commit (holder stalled past ${LOCK_STALE_MS}ms and was stolen from) — update aborted`, { facet: "lock-ownership" });
     }
 }
 function releaseSidecarLock(lockDir, token) {
@@ -897,7 +903,7 @@ function lockedStrictUpdate(controlDir, fileName, what, coerce, fn) {
         const { next, result } = fn(current);
         if (next !== undefined) {
             const data = `${JSON.stringify(next, null, 2)}\n`;
-            assertSidecarLockOwnership(lock, token, what);
+            assertSidecarLockOwnership(lock, token, what, "strict");
             atomicWriteFileSync(journal, data);
             atomicWriteFileSync(file, data);
             rmSync(journal, { force: true });
@@ -932,7 +938,10 @@ function readStrictSidecar(controlDir, fileName, what) {
     try {
         journalRaw = readFileSync(journal, "utf8");
     }
-    catch {
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw new ControlPlaneCorruptError(`control-plane journal unreadable ((${err.code ?? "io error"})) — a committed next state may exist that cannot be proven; repair the read fault rather than serving the pre-transaction state: ${journal}`, { cause: err });
+        }
         journalRaw = undefined;
     }
     if (journalRaw !== undefined) {
@@ -1421,7 +1430,7 @@ export function rebuildStrictControlPlaneLedger(controlDir, ledger, now) {
         }
         const at = now();
         const quarantinedTo = [];
-        assertSidecarLockOwnership(lock, token, what);
+        assertSidecarLockOwnership(lock, token, what, "strict");
         for (const path of [file, journal]) {
             if (!existsSync(path))
                 continue;
@@ -1439,7 +1448,7 @@ export function rebuildStrictControlPlaneLedger(controlDir, ledger, now) {
             }
             quarantinedTo.push(dest);
         }
-        assertSidecarLockOwnership(lock, token, what);
+        assertSidecarLockOwnership(lock, token, what, "strict");
         atomicWriteFileSync(file, `${JSON.stringify(empty, null, 2)}\n`);
         rmSync(journal, { force: true });
         return { ledger, quarantinedTo, at };

package/dist/core/park-selfcheck.js

@@ -1,5 +1,5 @@
 import { boundInputHashOf, canonicalize } from "./canonical-json.js";
-import { MAX_SUPPORTED_CHECKPOINT_VERSION, mintCheckpointToken, resolveCheckpointStore } from "./checkpoint-store.js";
+import { MAX_SUPPORTED_CHECKPOINT_VERSION, mintCheckpointId, 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;
@@ -59,6 +59,7 @@ export function durableParkGapFor(deps, spec = {}) {
 function syntheticCheckpoint(scope) {
     return {
         token: mintCheckpointToken(),
+        checkpointId: mintCheckpointId(),
         scope,
         sessionId: `${scope}:session`,
         leafId: `${scope}:leaf`,
@@ -89,6 +90,7 @@ function syntheticCheckpoint(scope) {
 function faithfulnessDelta(sent, got) {
     const project = (cp) => ({
         token: cp.token,
+        checkpointId: cp.checkpointId,
         scope: cp.scope,
         sessionId: cp.sessionId,
         leafId: cp.leafId,

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

@@ -87,6 +87,26 @@ export function prepareConfigDoors(input) {
     const { deps, sessions, resume, internals } = input;
     let spec = input.spec;
     assertRestoreGatedToolsValue(spec.restoreGatedTools);
+    const assertToolNameListValue = (value, seat) => {
+        if (value === undefined)
+            return;
+        if (!Array.isArray(value)) {
+            const e = new Error(`TaskSpec.${seat} must be an array of tool names or absent (got ${value === null ? "null" : typeof value}) — a garbage list must refuse loudly, never be read as "no ${seat}".`);
+            e.code = "config.tool_face_control";
+            throw e;
+        }
+        const entries = value;
+        for (const entry of entries) {
+            if (typeof entry !== "string") {
+                const e = new Error(`TaskSpec.${seat} entries must be strings (got ${entry === null ? "null" : typeof entry}).`);
+                e.code = "config.tool_face_control";
+                throw e;
+            }
+        }
+    };
+    assertToolNameListValue(spec.excludeTools, "excludeTools");
+    assertToolNameListValue(spec.deferTools, "deferTools");
+    assertToolNameListValue(spec.alwaysLoadTools, "alwaysLoadTools");
     const toolFaceSnapshot = {
         exclude: spec.excludeTools ? Object.freeze([...spec.excludeTools]) : undefined,
         defer: spec.deferTools ? Object.freeze([...spec.deferTools]) : undefined,

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

@@ -0,0 +1,192 @@
+import { type BeforeWriteHook, type CwdRef, type ReadDenyMatcher, type ReadFace } from "../../tools/fs/index.js";
+import { type ReadFileState } from "../../tools/fs/safety.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { Model } from "../../internal/llm.js";
+import type { AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
+import type { StoredSession } from "../session.js";
+import type { PrepareConfigDoorsResult } from "./prepare-config-doors.js";
+import type { PrepareSafetyScanResult } from "./prepare-safety-scan.js";
+import type { PrepareResume, RunInternals } from "./prepare-task.js";
+/** Test seam (mirrors `__resetMalformedNoticeSeatAnnouncement`): never called by production code.
+ *  Deliberately asymmetric — it resets only the console latch: the WeakSet arm needs no seam
+ *  because a test resets it by minting a fresh sink function (identity IS the ledger key), while
+ *  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;
+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). */
+    handsEnabled: boolean;
+    /** borrowed-readonly (the ownership-ref PROTOCOL stays with the driver — D-8 案① posture, same
+     *  as B-4): the effective env (`ownedEnv ?? deps.executionEnv ?? stub`). This phase drives it
+     *  (canonicalPath/joinPath/writeFileExclusive probe/instanceof screens) and closes tool bands
+     *  over it, but NEVER rebinds or destroys it. */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — B-4's settled root (T6 FINAL semantics); the containment root every face
+     *  in this phase canonicalizes from. */
+    taskRootFinal: string;
+    /** borrowed-readonly — B-4's checkpoint-path rebaser (T7): identity unless a divergent restore
+     *  armed it; applied to the readFileState seed keys and the handsCwd seed. */
+    rebaseRestoredPath: (p: string) => string;
+    /** borrowed-readonly — the durable-resume seat this phase reads: `seed` only (readFileState /
+     *  handsCwd / readFace section). Presence also gates the leg forks (T11: replay never runs on a
+     *  resume; the workspace_state rung is skipped; the face fold goes stricter-wins). */
+    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">;
+    /** borrowed-readonly — the acquired session's id, for error/notice tags and the band's session
+     *  registration. */
+    sessionId: string;
+    /** borrowed-readonly — the host task id: trace frames + the band's task-registry owner. */
+    hostTaskId: string;
+    /** borrowed-readonly — the registry scope (`internals?.registryScope ?? spec.principal ??
+     *  "default"`, computed in the driver); the band's task-registry scope. */
+    taskScope: string;
+    /** borrowed-readonly — the D-6 spec-time full-shell reachability precomputation; an input to the
+     *  face resolver on BOTH arms (the driver's post-exclusion roster assertion pins it to the
+     *  mounted truth — that assertion is driver-side, after this phase). */
+    fullShellReachable: boolean;
+    /** borrowed-readonly — the MAX-RANK fold of spec.shellGate with the inherited chain's doctrine
+     *  (computed in the driver's inherited-gate block); the shellGate fold's doctrine value. */
+    effectiveShellGate: "off" | "classify" | "always";
+    /** borrowed-readonly — B-1's frozen task-start face snapshot; only `.exclude` is read here (the
+     *  Monitor-mount honesty bit for the gh rate-limit hint, #181-F6). */
+    toolFaceSnapshot: PrepareConfigDoorsResult["toolFaceSnapshot"];
+    /** borrowed-readonly — B-1's resolved main model; read ONLY for its pdf capability profile
+     *  (the Read tool's document-degradation fork). */
+    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">;
+    /** 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;
+    /** 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
+     *  prepareMemory. */
+    memoryWriteGateRef: {
+        current?: BeforeWriteHook;
+    };
+    /** borrowed-readonly — the driver's per-tool offload wrapper (design/158 posture + policy); the
+     *  band rides through it exactly as caller/MCP tools do. */
+    firstPartyOffload: (tool: AgentTool) => AgentTool;
+    /** borrowed-mutable — the SHARED mount array (§4.4: later refs alias it; identity is the
+     *  contract, never map/copy). This phase pushes the hands band IN PLACE (after caller tools /
+     *  built-ins / MCP / A2A, before the background-task mounts — T22 order). Mutation owners after
+     *  this phase: P11 background/Monitor/worktree pushes, the driver's excludeTools splice, the
+     *  refresh seam's runtime splice/push. */
+    tools: AgentTool[];
+    /** borrowed-readonly HERE (census divergence #5 vs the design row): this phase only reads
+     *  `.has("Bash")`/`.has("Monitor")` for the provenance bits — its mutation owners are B-2/P8/P9
+     *  (+refresh seam)/P11/P22, per the B-2 Result's mutation-owner table. */
+    egressTools: ReadonlySet<string>;
+    /** borrowed-mutable — the shellGate fold's tier write-back (`.get` for the provenance bit,
+     *  monotonic `.set` — tighten-only). Same object B-2 returned; owner table lives on the B-2
+     *  Result. */
+    irreversibilityTier: PrepareSafetyScanResult["irreversibilityTier"];
+    /** borrowed-mutable — the shellGate fold `.add`s Bash/Monitor here. Same-object contract as
+     *  above. */
+    irreversibleTools: PrepareSafetyScanResult["irreversibleTools"];
+    /** borrowed-mutable — the classify doctrine's probe installs (`.set`, only where the doctrine
+     *  owns the seat). Same-object contract as above. */
+    reversibilityProbes: PrepareSafetyScanResult["reversibilityProbes"];
+}
+/** 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,
+ *  which write back into the driver's pre-existing `let`s (D-3 hold / driver-owned seats — see the
+ *  module header). */
+export interface PrepareHandsReadFaceResult {
+    /** owned — the per-task read-before-write state, exposed for the suspend closure's checkpoint
+     *  serialization (§15.2 net-add #8) and the compaction faces. Undefined ⇔ hands-less. The MAP
+     *  keeps being mutated by tool executes / compaction at run time — object identity carried. */
+    readFileStateForCheckpoint: ReadFileState | undefined;
+    /** owned — parity-204 (CC seededFromContext): seeds declared context files through the SAME
+     *  resolveKey containment as a real Read. CREATED here; CALLED by the driver's memory-seed and
+     *  loadProjectMemory blocks (T10 — the forever-cross-phase edge; this module does not claim the
+     *  call order). Undefined on a hands-less task (nothing to seed). Reads the phase-local
+     *  `resolvedReadFace` call-time — settled before this function returns. */
+    seedContextFiles: ((files: ReadonlyArray<{
+        path: string;
+        content: string;
+    }>) => Promise<void>) | undefined;
+    /** owned — design/99 §E13: the per-task logical cwd ref (observable `cd`), minted when a real
+     *  writable shell mounts. The driver stamps it into checkpoints, threads it into worktree tools
+     *  and gate cwd reads; tools mutate `.current` at run time. Undefined when no shell / readOnly. */
+    handsCwdRef: CwdRef | undefined;
+    /** owned — design/155: the settle-side snapshot base (what the cwd/worktree refs were RESTORED
+     *  to), so runtask's settle write diffs against it. The driver's G4 worktree mount writes
+     *  `.restoredWorktreeDir` after this phase — object identity carried. */
+    workspaceStateSettle: {
+        rootCanonical: string;
+        restoredHandsCwd?: string;
+        restoredWorktreeDir?: string;
+        baselineUnknown?: boolean;
+    } | undefined;
+    /** owned — design/155: the branch-nearest `workspace_state` entry, fetched ONCE here and shared
+     *  with the driver's worktree seed (the G4 mount reads `.activeWorktree` through it). */
+    wsSnapshot: WorkspaceState | undefined;
+    /** owned — the wsSnapshot path rebaser (identity when no snapshot / same root); the G4 worktree
+     *  seed applies it to the snapshot's worktree paths. */
+    rebaseWsPath: (p: string) => string;
+    /** owned — real shell + write hands + background-capable env: gates the driver's TaskOutput/
+     *  TaskStop/Monitor/SendMessage mounts (P11) and the Monitor arm of the shellGate fold here. */
+    backgroundTaskToolsActive: boolean;
+    /** write-back (D-3 hold) — the run's RESOLVED read face where hands mount; undefined ⇔ no hands
+     *  (the hands-less value lives in `handsLessResolvedFace`). The driver assigns this onto its
+     *  outer `let` for the call-time closures (ctx enrichment / checkpoint mint / envFacts). */
+    resolvedReadFace: ReadFace | undefined;
+    /** write-back (D-3 hold) — the NORMALIZED deny-set additions in force (deployment ∪ task ∪
+     *  resume-seed; zero-builtin compile — the persisted/carrier form, never the judged union's
+     *  post-dedup remainder). Driver assigns onto its outer `let`. */
+    readDenyAdditionsNormalized: ReadonlyArray<{
+        pattern: string;
+        caseSensitive: boolean;
+    }>;
+    /** write-back (D-3 hold) — the hands-LESS legs' resolved face (#242: the read posture is a
+     *  property of the RUN, not the mount). Driver assigns onto its outer `let`. */
+    handsLessResolvedFace: ReadFace | undefined;
+    /** owned — the canonicalized write-capable extra roots (additionalDirectories + the advertised
+     *  scratchpad), deduped; the driver's envFacts advertisement and attachment readers share the
+     *  ARRAY identity. Settled here (no mutation after return). */
+    additionalRootsCanonical: string[];
+    /** owned — the read-only arm of the fence widening (2026-08-05 both-arms ruling); same identity
+     *  contract as above. */
+    additionalReadRootsCanonical: string[];
+    /** owned — RB-159: the canonical containment root, published so the working-file ATTACHMENT
+     *  reader applies the same containment the hands tools do. Undefined ⇔ hands-less. */
+    attachmentRootCanonical: string | undefined;
+    /** owned — design/199 件B: the ONE compiled deny judge per prepare (built-ins ∪ deployment ∪
+     *  task additions). Undefined ⇔ hands-less (its consumers only exist with hands). */
+    readDenyMatcher: ReadDenyMatcher | undefined;
+    /** write-back — "the shellGate doctrine is the SOLE POSITIVE source of Bash's tier" provenance
+     *  bit; the driver's `let` (risk grading + the persisted-rule mandate boundary read it
+     *  call-time). Written ONLY by this phase; false when the fold did not run. */
+    shellGatedBash: boolean;
+    /** write-back — the Monitor twin of the bit above. */
+    shellGatedMonitor: boolean;
+}
+/** The hands-LESS resolver arm (#242) — SYNCHRONOUS by contract. The original P10 else-arm ran
+ *  with ZERO awaits, so on a hands-less leg the stretch from the driver's A2A warning callback
+ *  (deployment `onError`, which can queue a microtask) through the P11 SendMessage/delegation
+ *  mounts was uninterruptible. An `async` phase call would open exactly that microtask window (the
+ *  T1 hazard, here on the hands-less leg — a queued `spec.tools` mutation could suppress the
+ *  SendMessage mount or plant a trusted-revive delegation entry). So this leg is its OWN plain sync
+ *  seam the driver calls WITHOUT `await` (dispatching on the `handsEnabled` boolean it already
+ *  owns — NOT on a `Promise` identity check, which a host that replaces `globalThis.Promise` could
+ *  defeat; r3): the leg is byte-for-byte as synchronous as before the extraction.
+ *  (Adversarial review 2026-08-18, verified against the a945be28 baseline: awaits 3981–4243 are all
+ *  inside the hands branch; the else arm reached 4440/4463 with none.) */
+export declare function resolveHandsLessReadFace(input: PrepareHandsReadFaceInput): PrepareHandsReadFaceResult;
+/** The hands-MOUNT branch — the async half of the phase (see the module header for the contract).
+ *  The driver awaits this ONLY on the hands leg (`handsEnabled === true`); the hands-less leg goes
+ *  through the synchronous {@link resolveHandsLessReadFace} instead. Two seams, one boolean
+ *  dispatch — no `Promise`-identity guard (r3). */
+export declare function prepareHandsMount(input: PrepareHandsReadFaceInput): Promise<PrepareHandsReadFaceResult>;