@sema-agent/core 5.41.0 → 5.42.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 5.42.0 — 2026-08-18
+
+### 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

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

@@ -2171,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) {
@@ -3241,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";
     });
 }
 /**

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) {
@@ -605,12 +608,12 @@ export function assertSidecarLockOwnership(lockDir, token, what, mode = "lenient
     }
     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 });
+            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) {

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-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>;