@sema-agent/core 7.14.0 → 7.16.0

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

@@ -1,6 +1,6 @@
 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 { RunnerDeps, ShellGateDoctrine, TaskSpec } from "../types.js";
 import type { Model } from "../../internal/llm.js";
 import type { AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
 import type { AdvertisedWritableDirs } from "./advertised-writable-dirs.js";
@@ -11,10 +11,10 @@ import { RosterBuilder } from "../tool-roster.js";
  *  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. */
+ *  phase; 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
+ * 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
@@ -30,17 +30,17 @@ export declare function __resetReadFaceClampAnnouncement(): void;
  * 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
+ * and above all the 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
+ * BRANCH BINDING: 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
+ * (`reanchor`). A `null` anchor is NEVER inheritable ("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
@@ -59,14 +59,14 @@ export declare class SessionReadFileStates {
      *  `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
+    /** 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?
+ * 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).
  *
@@ -82,17 +82,17 @@ export declare class SessionReadFileStates {
  *  - 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
+ *    the very state the compaction clear removes 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
+ *    summarized-away recollection, the exact failure the compaction 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.
+ *    dropping every seat a foreign Runner touched would restore the cross-turn read-state amnesia this seat-anchor check already ended.
  */
 export declare function sessionSeatAnchorHolds(getEntry: (id: string) => Promise<{
     parentId: string | null;
@@ -118,8 +118,8 @@ export interface PrepareHandsReadFaceInput {
      *  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; `getStorage`/`getEntry` feed the #483 seat-anchor verification (one
+     *  preserved): `getWorkspaceState` feeds the continuation rung; `buildContext` feeds
+     *  the transcript replay; `getStorage`/`getEntry` feed the 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
@@ -136,9 +136,9 @@ export interface PrepareHandsReadFaceInput {
     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";
+    effectiveShellGate: ShellGateDoctrine;
     /** 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). */
+     *  Monitor-mount honesty bit for the gh rate-limit hint). */
     toolFaceSnapshot: ToolFaceSnapshot;
     /** borrowed-readonly — B-1's resolved main model; read ONLY for its pdf capability profile
      *  (the Read tool's document-degradation fork). */
@@ -149,39 +149,39 @@ export interface PrepareHandsReadFaceInput {
     /** 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). */
+     *  precedes the toolkit compile (the caller retains these arrays by reference). */
     deps: Pick<RunnerDeps, "onError" | "onNotice" | "tracer" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "readFace" | "permissionRuleStore" | "hands">;
     /** borrowed-readonly — the trusted spawn-side seats the band forwards: the finished-command
-     *  notification lane, the mid-flight detach hub, and (#483 rung-1) the Runner's per-session
+     *  notification lane, the mid-flight detach hub, and 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,
+    /** borrowed-readonly — ABSOLUTE paths this prepare's 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-readonly — (ref cell; the REF itself is never replaced) design/138 S2-C memory write gate:
+    /** borrowed-readonly — (ref cell; the REF itself is never replaced) memory write gate:
      *  the band's beforeWrite closure reads `.current` call-time; prepareMemory (driver, BEFORE this phase
-     *  since #691 — the memory root must be known before the toolkit compiles) installs the gate — the one
+     *  since the memory root must be known before the toolkit compiles) installs the gate — the one
      *  writer; this phase only reads. Declared in the driver because the SAME ref feeds prepareMemory. */
     memoryWriteGateRef: {
         current?: BeforeWriteHook;
     };
-    /** borrowed-mutable — #691: the advertised-writable-directory seat (see its module header for the one
+    /** borrowed-mutable — the advertised-writable-directory seat (see its module header for the one
      *  rule). Present on the hands leg only (a fence exists). The memory phase, which runs BEFORE this one,
      *  has already admitted its write root through it; this phase admits the deployment's scratchpad and
      *  folds `roots` into the write-capable containment allowlist before the toolkit compiles. */
     advertisedWritableDirs?: AdvertisedWritableDirs;
-    /** borrowed-readonly — the driver's per-tool offload wrapper (design/158 posture + policy); the
+    /** borrowed-readonly — the driver's per-tool offload wrapper (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. Since design/388 the array is builder-private: this phase `mountAll`s the band. */
+     *  refresh seam's runtime splice/push. The array is builder-private: this phase `mountAll`s the band. */
     roster: RosterBuilder;
     /** 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
@@ -197,16 +197,16 @@ export interface PrepareHandsReadFaceInput {
     /** borrowed-mutable — the classify doctrine's probe installs (`.set`, only where the doctrine
      *  owns the seat). Same-object contract as above. */
     reversibilityProbes: ReversibilityProbes;
-    /** borrowed-readonly — design/319 (A ticket): the run's reminder provenance mark (minted/adopted
+    /** borrowed-readonly — the run's reminder provenance mark (minted/adopted
      *  by the driver's adoption ladder); threaded into the hands band so the fs-side engine mints
      *  (the Read cyber/dedup/offset/empty reminders, the gh rate-limit hint) stamp the same mark the
      *  system-prompt declaration names. */
     reminderMark: string;
-    /** borrowed-mutable — design/319 (B ticket): the leg's disclosure trigger counters; the hands
+    /** borrowed-mutable — the leg's disclosure trigger counters; the hands
      *  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;
-    /** borrowed-readonly — design/381: the first-touch history hook prepare built (present iff a fileHistoryStore is
+    /** borrowed-readonly — 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;
     /** borrowed-readonly — the mutation lane's LANDED observation seat (the accumulator behind
@@ -233,11 +233,11 @@ export interface PrepareHandsReadFaceResult {
         path: string;
         content: string;
     }>) => Promise<void>) | undefined;
-    /** owned — design/99 §E13: the per-task logical cwd ref (observable `cd`), minted when a real
+    /** owned — 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
+    /** owned — 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: {
@@ -246,7 +246,7 @@ export interface PrepareHandsReadFaceResult {
         restoredWorktreeDir?: string;
         baselineUnknown?: boolean;
     } | undefined;
-    /** owned — design/155: the branch-nearest `workspace_state` entry, fetched ONCE here and shared
+    /** owned — 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
@@ -266,7 +266,7 @@ export interface PrepareHandsReadFaceResult {
         pattern: string;
         caseSensitive: boolean;
     }>;
-    /** write-back (D-3 hold) — the hands-LESS legs' resolved face (#242: the read posture is a
+    /** write-back (D-3 hold) — the hands-LESS legs' resolved face (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
@@ -276,19 +276,19 @@ export interface PrepareHandsReadFaceResult {
     /** 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
+    /** owned — 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 ∪
+    /** owned — 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;
-    /** owned (design/380 rescan C4) — the ENV-HAND tool names, minted AT THE MOUNT: every tool this
+    /** owned — the shell-seat PROVENANCE set: the shell-running tools whose tier the engine's shell seat (read
+     *  boundary + shellGate doctrine) is the SOLE POSITIVE source of — no explicit deployment mark on that name.
+     *  The one seat every consumer reads (risk grading, the gate's tighten attribution, the persisted-rule mandate
+     *  boundary): `shellGatedTools.has(toolName)`. Minted here, never grown afterwards; empty when the seat fold
+     *  did not run (no real writable shell). */
+    shellGatedTools: ReadonlySet<string>;
+    /** owned — the ENV-HAND tool names, minted AT THE MOUNT: every tool this
      *  phase mounted over the ExecutionEnv (the fs/bash band), later grown by the driver's own env
      *  mounts (Monitor, the worktree pair — the SAME Set identity, mutated at those mount sites).
      *  Consumed by the O9a external-content-target fold: these are the tools whose RESULTS are the
@@ -297,12 +297,12 @@ 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
+    /** owned — 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
+     *  this task's reads were never on. 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;
 }

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

@@ -2,7 +2,7 @@ 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, inheritSessionReadFileState, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
+import { bashReadBoundaryProbe, 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";
@@ -117,8 +117,7 @@ export function resolveHandsLessReadFace(input) {
         attachmentRootCanonical: undefined,
         readDenyMatcher: undefined,
         envHandToolNames: new Set(),
-        shellGatedBash: false,
-        shellGatedMonitor: false,
+        shellGatedTools: new Set(),
         sealReadStateSeat: undefined,
     };
 }
@@ -140,8 +139,7 @@ export async function prepareHandsMount(input) {
     let resolvedReadFace;
     let readDenyAdditionsNormalized = [];
     let handsLessResolvedFace;
-    let shellGatedBash = false;
-    let shellGatedMonitor = false;
+    const shellGatedTools = new Set();
     const additionalRootsCanonical = [];
     const additionalReadRootsCanonical = [];
     let attachmentRootCanonical;
@@ -345,34 +343,35 @@ export async function prepareHandsMount(input) {
         }
         roster.mountAll(band.map((t) => (envHandToolNames.add(t.name), firstPartyOffload(t))), { source: "builtin", mountedBy: "hands" });
         const shellGate = effectiveShellGate;
-        if (shellGate === "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
-            deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — no shell safety-axis ` +
-                `fold applies to this run (commands are adjudicated by the ordinary policy/hook chain only). ` +
-                `Set spec.shellGate to "classify" or "always" if this deployment expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
-        }
-        if (shellGate !== "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
-            const bashTierBefore = irreversibilityTier.get("Bash");
-            shellGatedBash = !egressTools.has("Bash") && bashTierBefore !== "always" && bashTierBefore !== "maybe";
-            const bashEffectiveTier = shellGate === "always" || bashTierBefore === "always" ? "always" : "maybe";
-            irreversibilityTier.set("Bash", bashEffectiveTier);
-            irreversibleTools.add("Bash");
+        if (!(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
+            if (shellGate === "off") {
+                deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — the read boundary is ` +
+                    `still judged on every command (a deny-listed or out-of-root read asks; the ask is mandated), but no ` +
+                    `residual shell-risk classifier is installed: writes, egress and unknown commands are adjudicated by ` +
+                    `the ordinary policy/hook chain only. Set spec.shellGate to "classify" or "always" if this deployment ` +
+                    `expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
+            }
             const shellReadBoundary = () => ({
                 roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
                 ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
                 denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
                 ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
             });
-            if (shellGate === "classify" && shellGatedBash)
-                reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
-            if (backgroundTaskToolsActive) {
-                const monitorTierBefore = irreversibilityTier.get("Monitor");
-                shellGatedMonitor = !egressTools.has("Monitor") && monitorTierBefore !== "always" && monitorTierBefore !== "maybe";
-                const monitorEffectiveTier = shellGate === "always" || monitorTierBefore === "always" ? "always" : "maybe";
-                irreversibilityTier.set("Monitor", monitorEffectiveTier);
-                irreversibleTools.add("Monitor");
-                if (shellGate === "classify" && shellGatedMonitor)
-                    reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
-            }
+            const installShellSeat = (name) => {
+                const tierBefore = irreversibilityTier.get(name);
+                const seatOwned = !egressTools.has(name) && tierBefore !== "always" && tierBefore !== "maybe";
+                if (seatOwned)
+                    shellGatedTools.add(name);
+                const tier = shellGate === "always" || tierBefore === "always" ? "always" : "maybe";
+                irreversibilityTier.set(name, tier);
+                irreversibleTools.add(name);
+                if (seatOwned && tier === "maybe") {
+                    reversibilityProbes.set(name, shellGate === "classify" ? bashReversibilityProbe(undefined, shellReadBoundary) : bashReadBoundaryProbe(shellReadBoundary));
+                }
+            };
+            installShellSeat("Bash");
+            if (backgroundTaskToolsActive)
+                installShellSeat("Monitor");
         }
     }
     return {
@@ -391,8 +390,7 @@ export async function prepareHandsMount(input) {
         attachmentRootCanonical,
         readDenyMatcher,
         envHandToolNames,
-        shellGatedBash,
-        shellGatedMonitor,
+        shellGatedTools,
         sealReadStateSeat,
     };
 }

package/dist/core/runner/prepare-inherited-gate.d.ts

@@ -1,5 +1,5 @@
 /**
- * design/390 §1.2 M3b — prepareTask's INHERITED-GATE phase, verbatim from the driver: the live/seed fold of the
+ * PrepareTask's INHERITED-GATE phase, verbatim from the driver: the live/seed fold of the
  * chain this run inherits (ancestor rules rev-monotonic per (session, principal), shellGate by max rank, the
  * re-supplied parent constraints with their rebuilt denial trackers, the auto-mode intent, the org-admission
  * freeze with its tighten-only intersection and the monotonic governed bit), the effective shellGate against the
@@ -8,11 +8,11 @@
  * FROZEN ask and question seats (spec over deps), the two delegation refs the memory phase binds late, the ONE
  * child-chain assembly `inheritedGateForChildren`, the caller-tool ctx enrichment `enrichSpecToolCtx` shared by
  * the roster wrap and the revival spawner, the denial-limit stop seat, and the full-shell reachability predicate.
- * The interface is the dependency list the segment had implicitly (design/238 R-1).
+ * The interface is the dependency list the segment had implicitly.
  *
  * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await (the one `await` in it sits inside the
  * `hostSessionFork` closure a tool calls later), so the phase adds no yield between the run-refs phase before it
- * and the caps phase after it (design/390 §1.5: a stretch with no await is extracted as a sync function).
+ * and the caps phase after it (a stretch with no await is extracted as a sync function).
  *
  * LATE-BOUND SEATS. The closures minted here run long after this phase returns — at spawn time, at tool-call
  * time, at suspend time — and several of the facts they read are resolved by LATER stations of the same prepare:
@@ -25,7 +25,7 @@
  * sat behind a short-circuit). Read-stability of the host handles for the call: {@link RunInternals}
  * (`@contract prepare.deps-read-stable`).
  *
- * Every cell that leaves here as `borrowed-mutable` carries its writer table on the Result member (design/238 R-3).
+ * Every cell that leaves here as `borrowed-mutable` carries its writer table on the Result member.
  */
 import type { AgentHarness, ExecutionEnv } from "../../internal/harness.js";
 import type { SubagentWorktreeIsolation } from "../../agents/subagent.js";
@@ -43,7 +43,7 @@ import type { DelegationContentSafety } from "../memory-engine/delegation-proven
 import type { SessionPermissionRules } from "../session-policy-store.js";
 import type { SessionStore } from "../session.js";
 import { type OnAsk } from "../tool-policy.js";
-import type { RunnerDeps, RuntimeCaps, TaskEvent, TaskSpec, ToolExecuteContext } from "../types.js";
+import type { RunnerDeps, RuntimeCaps, ShellGateDoctrine, TaskEvent, TaskSpec, ToolExecuteContext } from "../types.js";
 import type { ActiveSkillScope } from "./active-skill-scope.js";
 import type { InheritedGate, Prepared, PrepareResume, RunInternals, ToolFaceSnapshot } from "./contracts.js";
 import { type StopForDenialLimit } from "./denial-limit-arms.js";
@@ -194,7 +194,7 @@ export interface PrepareInheritedGateResult {
     /** owned — the monotonic governed-provenance bit for this leg. */
     orgGovernedProvenance: boolean;
     /** owned — the spec's own shellGate tightened by the inherited doctrine. */
-    effectiveShellGate: "off" | "classify" | "always";
+    effectiveShellGate: ShellGateDoctrine;
     /** borrowed-mutable — THIS task's own session-rule snapshot for its children's chain. Writers (R-3): the policy-chain
      *  station's session-policy read, once per leg, when a store is wired and the task carries its own sessionId. Read by
      *  `inheritedGateForChildren` at spawn time. */

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

@@ -1,13 +1,13 @@
 /**
- * design/390 M15 — prepareTask's LISTINGS phase: the per-task agent definitions' tool-name audit
+ * PrepareTask's LISTINGS phase: the per-task agent definitions' tool-name audit
  * (deny entries fail loud, allow entries advise), the agent-listing announce face read off the
  * delegation tool's roster (with its deferred / excluded / removal-to-zero arms), the two listing
  * opt-out advisories, the announced-listings mirror seeded from the once-per-session ledger, the
  * deferred roster's ToolSearch ride, and the date_change seam. The body is the driver's stretch moved
- * verbatim; the interface is the dependency list it had implicitly (design/238 R-1).
+ * verbatim; the interface is the dependency list it had implicitly.
  *
  * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between
- * the disclosure mount before it and the context-lane seats after it (design/390 §1.5 S1: a stretch
+ * the disclosure mount before it and the context-lane seats after it (a stretch
  * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
  *
  * Throws pass through unchanged: `config.agent.unknown_tool` (a deny entry naming a tool this

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

@@ -1,13 +1,13 @@
 /**
- * design/390 §1.2 M8 — prepareTask's LSP phase, verbatim from the driver: the manager fold (spec > deps), the
+ * PrepareTask's LSP phase, verbatim from the driver: the manager fold (spec > deps), the
  * LSP tool mount over the per-task env with its git-ignore filter, the diagnostics lane behind its four
  * preconditions (a manager whose sessions feed a registry, write-capable hands, not opted out), the run-scoped
  * registry key, and the edit nudge (raw path → the SAME resolution the tool leg uses → registry reset +
  * session didChange). No manager ⇒ nothing mounts and both lane seats are undefined. The interface is the
- * dependency list the segment had implicitly (design/238 R-1).
+ * dependency list the segment had implicitly.
  *
  * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between the
- * fork-governance note before it and the memory trio's occupancy read after it (design/390 §1.5 S1: a stretch
+ * fork-governance note before it and the memory trio's occupancy read after it (a stretch
  * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
  * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
  */

package/dist/core/runner/prepare-memory-engine-session.d.ts

@@ -1,16 +1,16 @@
 /**
- * design/390 §1.2 M12 — prepareTask's MEMORY-ENGINE-SESSION phase, verbatim from the driver: the content-origin
- * classification + one-way session pollution wrap section (design/178 §3 / design/180 half A / design/324 /
- * design/336 §3.3 + §5.5 / design/378 D-4 / design/380 O9a). Its arming predicate (a mounted memory session OR an
+ * PrepareTask's MEMORY-ENGINE-SESSION phase, verbatim from the driver: the content-origin
+ * classification + one-way session pollution wrap section (consolidating several design threads).
+ * Its arming predicate (a mounted memory session OR an
  * upstream recorder channel), the chain-narrowed classification config, the children's provenance seat, the
  * declared-MCP-class announcement, the settlement seat, the per-tool wrap with its three record verbs (mark /
  * recordExternal / recordIncomplete), the Read tool's recall-taint arm and the delegation arm's three-valued
  * attestation judgment all live here; the announcement helper only this section called moved with it. The
- * interface is the dependency list the segment had implicitly (design/238 R-1).
+ * interface is the dependency list the segment had implicitly.
  *
  * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (the awaits sit inside the wrappers it
  * installs, which run at tool-call time), so the phase adds no yield between the deferred classification before it
- * and the prompt assembly after it (design/390 §1.5: a stretch with no await is extracted as a sync function).
+ * and the prompt assembly after it (a stretch with no await is extracted as a sync function).
  * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
  *
  * One read changed spelling and nothing else: the declared-class announcement read `mcp?.statuses` while `mcp` had

package/dist/core/runner/prepare-memory.js

@@ -10,6 +10,7 @@ import { readSessionCaptureOptOut } from "../memory-engine/layout.js";
 import { createMemoryEngineTools } from "../memory-engine/tools.js";
 import { assertScopeContractPlacement, parseScopeKey, resolveProjectId } from "../memory-engine/scope-contract.js";
 import { FileMemoryEngineBackend } from "../memory-engine/file-backend.js";
+import { writableRootOf } from "../memory-engine/types.js";
 let undeclaredCapturePostureAnnounced = false;
 export async function prepareMemory(input) {
     const { spec, deps, sessionId, taskRootPath, memoryWriteGateRef, admissionCtx } = input;
@@ -460,20 +461,18 @@ export async function prepareMemory(input) {
             }
             const foreignUnderRoot = [];
             if (input.writeToolsMounted && writeHandle.writeScope !== null && input.advertisedWritableDirs !== undefined) {
-                for (const d of [...writeEngine.readonlyDirNamesUnderRoot(writeHandle)].sort())
-                    foreignUnderRoot.push(`another scope's directory ${d}`);
                 const controlPlane = canonicalize(writeEngine.controlPlaneDir);
-                if (isContainedIn(writeHandle.writableRoot, controlPlane))
+                if (isContainedIn(writableRootOf(writeHandle), controlPlane))
                     foreignUnderRoot.push(`the engine's control plane ${controlPlane}`);
             }
             if (foreignUnderRoot.length > 0) {
-                deps.onError?.(new Error(`memory advertised writable directory refused: the write scope's root ${writeHandle.writableRoot} contains what is not the model's to touch (${foreignUnderRoot.join("; ")}) — the file tools' root fence is directory-granular, so admitting it would expose those files; memory writes through the file tools stay closed this session and the write instruction is not taught.`), { phase: "config", sessionId });
+                deps.onError?.(new Error(`memory advertised writable directory refused: the write scope's root ${writableRootOf(writeHandle)} contains what is not the model's to touch (${foreignUnderRoot.join("; ")}) — the file tools' root fence is directory-granular, so admitting it would expose those files; memory writes through the file tools stay closed this session and the write instruction is not taught.`), { phase: "config", sessionId });
             }
             writeChannelOpen =
                 input.writeToolsMounted &&
                     writeHandle.writeScope !== null &&
                     foreignUnderRoot.length === 0 &&
-                    (input.advertisedWritableDirs === undefined || (await input.advertisedWritableDirs.admit({ path: writeHandle.writableRoot, advertiser: "memory", expectCanonical: writeHandle.writableRoot })));
+                    (input.advertisedWritableDirs === undefined || (await input.advertisedWritableDirs.admit({ path: writableRootOf(writeHandle), advertiser: "memory", expectCanonical: writableRootOf(writeHandle) })));
             memoryWriteGateRef.current = async (w) => {
                 if (readOnlyEngine !== undefined && readOnlyHandle !== undefined) {
                     const ro = readOnlyEngine.gateWrite(readOnlyHandle, w.key, w.content);
@@ -482,7 +481,7 @@ export async function prepareMemory(input) {
                 }
                 if (input.memoryPersistenceDeclared === false) {
                     const root = writeHandle.writableRoot;
-                    if (w.key === root || w.key.startsWith(`${root}${sep}`)) {
+                    if (root !== null && (w.key === root || w.key.startsWith(`${root}${sep}`))) {
                         return {
                             ok: false,
                             code: "read_only_layering",
@@ -493,7 +492,7 @@ export async function prepareMemory(input) {
                 }
                 {
                     const root = writeHandle.writableRoot;
-                    if (w.key === root || w.key.startsWith(`${root}${sep}`)) {
+                    if (root !== null && (w.key === root || w.key.startsWith(`${root}${sep}`))) {
                         const state = captureOptedOut ? { record: { at: 0, reason: "in-run state" }, fault: false } : await writeEngine.sessionCaptureOptOutOrFault(sessionId);
                         if (state.record !== undefined || state.fault) {
                             return {

package/dist/core/runner/prepare-offload-wrappers.d.ts

@@ -1,11 +1,11 @@
 /**
- * design/390 §1.2 M0 (the offload half of the prelude) — prepareTask's nested-usage accumulator, the
+ * (The offload half of the prelude) — prepareTask's nested-usage accumulator, the
  * large-tool-result offload store resolution and the THREE offload wrappers every later mount site
  * applies (caller tools, first-party hand tools, remote MCP/A2A peers), verbatim from the driver.
  *
  * SYNCHRONOUS by construction: the segment held no await in the driver, and a phase that yields where
  * the driver did not would open a microtask window between two steps that used to be adjacent (the
- * design/238 T1 posture). Nothing here touches the store — the wrappers close over it and only the
+ * posture). Nothing here touches the store — the wrappers close over it and only the
  * wrapped tools' `execute` reach it, at run time.
  *
  * What stays in the driver: the trust-axis choice of `offloadScope` (`spec.principal ?? "default"`)

package/dist/core/runner/prepare-park-ask.d.ts

@@ -1,11 +1,11 @@
 /**
- * design/390 §1.2 M19 (park ask) — prepareTask's PARK CLOSURE and CONTENT-ASK ROUTING closure, verbatim from the driver's
+ * PrepareTask's PARK CLOSURE and CONTENT-ASK ROUTING closure, verbatim from the driver's
  * gate-machinery block: `resolveContentAsk` (the question face's delivery race, the binding table's cap and redemption
  * identity, the stranded-answer disclosure) and `suspendAsk` (the sync-first decline and the park-priority mandates, the
  * args capture / fidelity projection / re-adjudication steps, the pause-then-cut fence, the gate-kind choice, the row
  * mint, the commit through the saga and the post-commit publication). The one module-scope helper only this segment
- * threw (`ParkRefusal`) moved with it. The interface is the dependency list the segment had implicitly (design/238
- * R-1) — the two closures used to capture every seat here off the driver's scope, which is the capture surface this
+ * threw (`ParkRefusal`) moved with it. The interface is the dependency list the segment had implicitly
+ * — the two closures used to capture every seat here off the driver's scope, which is the capture surface this
  * decomposition exists to make explicit.
  *
  * The thirteen-argument park closure is unchanged: twelve positional seats then the structural {@link AskCarry}, the
@@ -13,7 +13,7 @@
  * carry onto the row exactly as before — this phase mints no origin, changes no word, adds no arm to the closed set.
  *
  * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (both closures run per tool call), so the
- * phase adds no yield between the boundary parks before it and the gate station after it (design/390 §1.5).
+ * phase adds no yield between the boundary parks before it and the gate station after it.
  * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
  *
  * Both closures exist exactly when the ask lane and the saga do (the same predicate) — an absent lane answers two absent
@@ -25,7 +25,7 @@ import { type CheckpointStore } from "../checkpoint-store.js";
 import type { SessionStore } from "../session.js";
 import { type OnAsk, type ToolCallRequest, type ToolPolicy } from "../tool-policy.js";
 import { type ToolResultStore } from "../tool-result-store.js";
-import type { RunnerDeps, RuntimeCaps, TaskSpec } from "../types.js";
+import type { RunnerDeps, RuntimeCaps, ShellGateDoctrine, TaskSpec } from "../types.js";
 import type { CwdRef } from "../../tools/fs/fs-shared.js";
 import { type ContentAskBinding } from "./content-ask-bindings.js";
 import type { AskLane, ParkAsk, Prepared, SuspendSaga } from "./contracts.js";
@@ -50,7 +50,7 @@ export interface PrepareParkAskInput {
     /** borrowed-readonly — the leg's checkpoint store, or undefined (then `suspendAsk` is absent — the park predicate's store
      *  term). Read: the declared fidelity; the saga writes to it. */
     checkpointStore: CheckpointStore | undefined;
-    /** borrowed-readonly — the leg's delta seat (design/388 B18): the park reads the gated tool's identity off its
+    /** borrowed-readonly — the leg's delta seat (B18): the park reads the gated tool's identity off its
      *  CURRENT roster snapshot so the row carries who the action was minted against. */
     toolRosterDeltas: ToolRosterDeltaSeat;
     /** borrowed-readonly — the wiring-manifest phase's park predicate (`parkLane.effective`): arms `suspendAsk`. */
@@ -108,12 +108,11 @@ export interface PrepareParkAskInput {
     maxSuspends: number;
     /** borrowed-mutable — the run-scoped remote-lifecycle failure log. Writer here: a refused `suspendVM` (`push`). */
     remoteEnvFailures: Prepared["remoteEnvFailures"];
-    /** borrowed-readonly — whether Bash is coarsely shell-gated (the risk descriptor's `shellGated`). */
-    shellGatedBash: boolean;
-    /** borrowed-readonly — whether Monitor is coarsely shell-gated (same). */
-    shellGatedMonitor: boolean;
+    /** borrowed-readonly — the shell-seat provenance set: the shell-running tools whose tier is the engine's shell seat's, not a
+     *  deployment mark (the risk descriptor's `shellGated` is the gated tool's membership). */
+    shellGatedTools: ReadonlySet<string>;
     /** borrowed-readonly — the effective shell-gate doctrine persisted on the descriptor. */
-    effectiveShellGate: "off" | "classify" | "always";
+    effectiveShellGate: ShellGateDoctrine;
     /** borrowed-readonly — the EFFECTIVE durable-approval opt-in (the caller's, or the synthesized mandate scope): picks the
      *  gate kind, the scope and the ttl. */
     durableApproval: TaskSpec["durableApproval"];
@@ -156,7 +155,7 @@ export interface PrepareParkAskResult {
 /** The M19 park-ask phase body — prepareTask's park closure and content-ask routing stretch, verbatim (see the module header). */
 export declare function prepareParkAsk(input: PrepareParkAskInput): PrepareParkAskResult;
 /**
- * From the resumed/active transcript, the batch position of `currentId` (design/45 §4.ter): the tool-call
+ * From the resumed/active transcript, the batch position of `currentId`: the tool-call
  * ids of the assistant message that issued it (the batch), and the subset already resolved (executed
  * before the suspend — #1..k-1). ID-based, not positional (council Question #1): immune to reordering.
  */