@sema-agent/core 5.29.0 → 5.30.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 5.30.0 — 2026-08-13
+
+No API-BREAKING changes (exports grow only: `resolveReadFace`, `ReadFace`, `ReadFaceInputs`,
+`READ_FACE_DEFAULT_DENY_ENTRIES`, `compileReadDeny`, `ReadDenyEntry`, `ReadDenyMatcher`,
+`NormalizedReadDenyEntry`; `TaskSpec`/`RunnerDeps`/`HandsToolkitOptions` gain `readFace`/
+`readDenyPatterns`). Narrowings are tighten-direction and named below.
+
+### Added
+
+- **A read-face containment knob (`readFace: "open" | "roots"`, default `"roots"` — byte-compatible
+  with prior behavior).** `TaskSpec`/`RunnerDeps`/`HandsToolkitOptions` each gain the seat; task-layer
+  may only tighten under governance, deployment-layer sets the default. Beside a read-only (verifier)
+  mount, a task-seat `"open"` is a genuine contradiction and refuses loudly; a deployment-seat
+  `"open"` there silently clamps to `"roots"` (a deployment default cannot override a load-bearing
+  containment wall). Every workflow/subagent/SendMessage delegation lane inherits the resolved face
+  tighten-only (stricter-wins), including `run_workflow`'s script-spawned children, which previously
+  did not inherit it at all. Checkpoint schema bumps to v9 (`FACE_CHECKPOINT_VERSION`) to carry the
+  resolved face across suspend/resume; an absent v9 section on an older checkpoint row is the default
+  posture (roots) — no existing row's behavior changes.
+- **A built-in sensitive-path READ deny set**, exported as `READ_FACE_DEFAULT_DENY_ENTRIES` (SSH
+  keys, cloud/VCS credential files, browser profile directories, crypto wallet files, shell history,
+  and similar). Enforced under BOTH containment modes — an `"open"` face does not exempt it — and not
+  shrinkable by any deployment configuration, including the `readFace: "roots"` compatibility seat
+  (the two axes are orthogonal). `.env`-family files are deliberately excluded (write-side guards
+  already cover them). Deployments may extend the table (`readDenyPatterns` on the same three seats,
+  additive-only; `compileReadDeny` lets a host pre-validate additions with the engine's own rules).
+
+### Narrowed (behavior)
+
+- **A UNC-rooted deployment's `..` can no longer walk out of its declared root.** Lexical folding now
+  normalizes `..` segments and Win32 device-namespace prefixes (`\\?\`, `\\.\`) before they reach the
+  containment check; this is a security repair with no compatibility escape hatch (unaffected by any
+  "keep old behavior" knob).
+- **`bashReversibilityProbe` no longer auto-executes an operand with an unexpanded shell glob
+  metacharacter it can't verify against the deny/boundary check.** A command whose read target is
+  undecided at the classifier layer now routes to the ask flow instead of running unattended.
+- **A hands-less resume no longer clones the `realApproval` governance marker onto an ungoverned
+  re-park.** The seed-carry now picks only `{face, denyEntries}`; previously, a worker resuming into a
+  plain (non-governed) ask could inherit a stale `realApproval: true` and permanently wedge the row on
+  its next resume (`real_approval_damaged`, fail-closed by design).
+- **The auto-mode classifier can no longer resolve an ask that originated from an explicit
+  user-written permission rule or a hook-raised promotion.** Both are now excluded from classifier
+  judgment and the persisted-rule-clearing lane, closing two asymmetric gaps against the existing
+  `decisionReason === "hook"` exclusion.
+- **`resolveAsk`'s object-arm reads share one exception boundary.** A throwing getter on `settledBy`/
+  `allow`/`updatedInput` now fails closed (deny) instead of propagating an unhandled rejection; a
+  non-boolean `allow` is refused loudly by name instead of silently rendering as a human refusal.
+
+### Fixed
+
+- `run_workflow`'s durable-store off switch (`spec.checkpointStore === null`) and design/148's
+  center-artifact inheritance (`centerArtifactDigest`/`centerSourceRevision`) were dead reads on the
+  tool's auto-mounted execute context (which never carries them) — neither ever reached a
+  script-spawned child. Both now fall back to a mount-time dependency, matching the tool's other two
+  ctx-or-deps fields.
+- Under `readFace: "open"`, compaction's attachment-reader legs (`readTaskFile`/
+  `normalizeAttachmentPath`) refused files the Read tool had already legitimately served out-of-root;
+  they now thread the resolved face like the structured read tools do.
+- `deleteBySession` joins the `ToolResultStore` contract kit as an honest optional member: when
+  implemented, the four-state semantics (same-session rows deleted, other-session rows untouched,
+  unowned rows counted not deleted, idempotent re-delete) are asserted; when absent, the contract
+  probe reports it by name instead of silently passing.
+
 ## 5.29.0 — 2026-08-13
 
 No API-BREAKING changes (exports grow only: `AskOutcome.reason`, `AskRequest.isDelegatedChild`).

package/dist/agents/send-message-tool.js

@@ -680,6 +680,8 @@ export function createSendMessageTool(opts) {
                     ...(ctx.onQuestion !== undefined && row.sessionScoped !== true ? { currentOnQuestion: ctx.onQuestion } : {}),
                     currentClamps: {
                         ...(ctx.handsReadOnly === true ? { handsReadOnly: true } : {}),
+                        ...(ctx.readFace === "roots" ? { readFaceRoots: true } : {}),
+                        ...(ctx.readDenyPatterns !== undefined ? { readDenyPatterns: ctx.readDenyPatterns } : {}),
                         ...(ctx.interactiveTools === false ? { interactiveTools: false } : {}),
                         ...(ctx.oneShot === true ? { oneShot: true } : {}),
                         ...(ctx.memoryPersistenceCapable === false ? { memoryPersistenceCapable: false } : {}),

package/dist/agents/subagent.d.ts

@@ -404,6 +404,8 @@ export declare function createSubagentResume(deps: {
         interactiveTools?: false;
         oneShot?: true;
         memoryPersistenceCapable?: false;
+        readFaceRoots?: true;
+        readDenyPatterns?: readonly import("../tools/fs/read-deny.js").ReadDenyEntry[];
     };
     /** The RESUMING caller's own handback-review seat (its trusted `ToolExecuteContext.autoModeReview`),
      *  same turn-bound reasoning as `currentOnQuestion` above: a resumed cycle is a completion like any

package/dist/agents/subagent.js

@@ -520,6 +520,10 @@ export function createSubagentResume(deps) {
                 requireExistingSession: true,
                 ...(deps.currentOnQuestion !== undefined ? { onQuestion: deps.currentOnQuestion } : {}),
                 ...(entry.specSnapshot.handsReadOnly === true || deps.currentClamps?.handsReadOnly === true ? { handsReadOnly: true } : {}),
+                ...(entry.specSnapshot.readFace === "roots" || deps.currentClamps?.readFaceRoots === true ? { readFace: "roots" } : {}),
+                ...(entry.specSnapshot.readDenyPatterns !== undefined || deps.currentClamps?.readDenyPatterns !== undefined
+                    ? { readDenyPatterns: [...(entry.specSnapshot.readDenyPatterns ?? []), ...(deps.currentClamps?.readDenyPatterns ?? [])] }
+                    : {}),
                 ...(entry.specSnapshot.interactiveTools === false || deps.currentClamps?.interactiveTools === false ? { interactiveTools: false } : {}),
                 ...(entry.specSnapshot.oneShot === true || deps.currentClamps?.oneShot === true ? { oneShot: true } : {}),
                 ...(entry.specSnapshot.memoryPersistenceCapable === false || deps.currentClamps?.memoryPersistenceCapable === false
@@ -1693,6 +1697,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(ctx.onQuestion !== undefined ? { onQuestion: ctx.onQuestion } : {}),
                 ...(ctx.interactiveTools === false ? { interactiveTools: false } : {}),
                 ...(ctx.handsReadOnly === true ? { handsReadOnly: true } : {}),
+                ...(ctx.readFace === "roots" ? { readFace: "roots" } : {}),
+                ...(ctx.readDenyPatterns !== undefined ? { readDenyPatterns: [...ctx.readDenyPatterns] } : {}),
                 ...(childMemoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: childMemoryPersistenceCapable } : {}),
                 ...(ctx.oneShot === true ? { oneShot: true } : {}),
                 ...(ctx.clientContext !== undefined ? { clientContext: ctx.clientContext } : {}),

package/dist/agents/teacher.js

@@ -180,6 +180,8 @@ async function runTeacherCore(runner, studentSpec, teacher) {
         ...(studentSpec.clientContext !== undefined ? { clientContext: studentSpec.clientContext } : {}),
         ...(studentSpec.promptProfile !== undefined ? { promptProfile: studentSpec.promptProfile } : {}),
         ...(studentSpec.handsReadOnly === true ? { handsReadOnly: true } : {}),
+        ...(studentSpec.readFace === "roots" ? { readFace: "roots" } : {}),
+        ...(studentSpec.readDenyPatterns !== undefined ? { readDenyPatterns: [...studentSpec.readDenyPatterns] } : {}),
         ...(studentSpec.interactiveTools === false ? { interactiveTools: false } : {}),
         ...(studentSpec.excludeTools !== undefined ? { excludeTools: [...studentSpec.excludeTools] } : {}),
         ...(studentSpec.deferTools !== undefined ? { deferTools: [...studentSpec.deferTools] } : {}),

package/dist/agents/verify.js

@@ -99,6 +99,8 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
             roles: specBase.roles,
             tools: verifierTools,
             handsReadOnly: config.verifierHandsReadOnly ?? true,
+            ...(specBase.readFace === "roots" ? { readFace: "roots" } : {}),
+            ...(specBase.readDenyPatterns !== undefined ? { readDenyPatterns: [...specBase.readDenyPatterns] } : {}),
             interactiveTools: false,
             outputSchema: VerdictSchema,
             enableBlockedReport: false,

package/dist/core/auto-compaction.d.ts

@@ -244,7 +244,11 @@ export interface MaybeCompactOptions {
      */
     workingFileAttachments?: {
         /** Read a task workspace file; null/throw = skip it. Wired by the Runner from the task's ExecutionEnv. */
-        readFile: (path: string) => Promise<string | null>;
+        readFile: (path: string) => Promise<string | null | {
+            withheld: {
+                pattern: string;
+            };
+        }>;
         /** Max modified files to attach. Default 3. */
         maxFiles?: number;
         /** Per-file char cap (≈4 chars/token). Default 16_000 (~4k tokens). */

package/dist/core/auto-compaction.js

@@ -397,12 +397,21 @@ export async function maybeCompact(opts) {
             if (remaining <= 0)
                 break;
             let content = null;
+            let withheldPattern;
             try {
-                content = await att.readFile(path);
+                const r = await att.readFile(path);
+                if (typeof r === "string")
+                    content = r;
+                else if (r !== null && typeof r === "object")
+                    withheldPattern = r.withheld.pattern;
             }
             catch {
                 content = null;
             }
+            if (withheldPattern !== undefined) {
+                blocks.push(`<working-file path="${escapeWorkingFilePathAttr(path)}" withheld="content withheld: matches the sensitive-path read deny list (pattern ${escapeWorkingFilePathAttr(withheldPattern)})"/>`);
+                continue;
+            }
             if (content === null)
                 continue;
             const cap = Math.min(perFileCap, remaining);

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

@@ -647,6 +647,37 @@ export interface CheckpointState {
     /** design/44: the hand's read-file state (content hashes), serialized from the hands-toolkit closure
      *  (NOT part of Prepared — §15.2 net-add #8). Without it a resumed `edit_file` is rejected "not read". */
     readFileState?: Array<[string, ReadEntry]>;
+    /**
+     * design/199 — the READ-face containment state at suspend (v9,
+     * {@link FACE_CHECKPOINT_VERSION}): the RESOLVED face plus the NORMALIZED deny-set ADDITIONS in
+     * force (deployment ∪ task layers; the built-in table is engine code, never frozen here — a newer
+     * engine's built-ins apply on resume as everywhere else). Written ONLY when the posture is
+     * non-default (face "open", or additions present) — an absent section IS the default posture and
+     * resumes as roots + built-ins on any worker. Resume folds STRICTER-WINS: face = roots unless the
+     * section says open AND the live resolution says open; deny additions = frozen ∪ live (add-only,
+     * monotone — a resume can never widen what the cut leg could read).
+     *
+     * The design's r3/r4 rounds carried a third key (the workspace domain at cut) to evaluate
+     * domain-scoped deny entries under their frozen domain; the D-4 ruling (2026-08-13) removed the
+     * scoped tier entirely, leaving that key without a consumer — it is deliberately NOT persisted
+     * (dead fields in a durable format are the drift surface the liveness gate exists to catch).
+     */
+    readFace?: {
+        face: "open" | "roots";
+        denyEntries?: Array<{
+            pattern: string;
+            caseSensitive: boolean;
+        }>;
+        /** codex r2 — REDUNDANT governance marker: `true` iff the row's gate was minted WITH a
+         *  {@link RealApprovalGateBit}. v8's bit-required invariant was version-keyed and v9 (face)
+         *  outranks v8 in the stamp, so without this a v9 GOVERNED row whose `gate.realApproval` member
+         *  was dropped in storage would pass pre-CAS and be redeemable on an unwired worker — the exact
+         *  #130/#120 corruption/downgrade hole, reopened one version up. The resume pre-CAS ladder
+         *  refuses a v9+ row whose section says `realApproval: true` while the gate carries no
+         *  well-formed bit (same protection level as v8: a coherent rewrite of BOTH sites remains out of
+         *  scope for any in-row invariant). Absent = the row was minted ungoverned. */
+        realApproval?: true;
+    };
     /**
      * design/78 Slice-1: the SAFE-tier self-repair loop's durable state (`failureTrace`/`diagnostics`/
      * `rejectedHypotheses`/`attemptCount`/`oracleTier` — all JSON/`structuredClone`-safe, no fn/Date). Set ONLY
@@ -963,14 +994,29 @@ export declare const F012_CHECKPOINT_VERSION = 7;
  * stays true: rows whose gate carries no realApproval bit keep their historic stamps everywhere.
  */
 export declare const REAL_APPROVAL_CHECKPOINT_VERSION = 8;
+/**
+ * design/199 (2026-08-13 — the precedent replayed a seventh time): the schema version a suspend
+ * stamps when its state carries the READ-FACE section ({@link CheckpointState.readFace} — the
+ * resolved open face and/or deny-set additions). The enforcement lives ENTIRELY in the resuming
+ * worker (the stricter-wins face fold + the deny-entry union at prepare): a pre-199 worker
+ * (MAX_SUPPORTED=8) would accept the row, ignore the section, and resume the leg under its own
+ * defaults — silently DROPPING the frozen deny additions (a widening), and re-deriving the face
+ * from live config alone. Stamping v9 forces it to reject PRE-CAS (`unsupported_version`, stays
+ * `pending`, retried on an enforcing worker). A row whose task ran the default posture (face roots,
+ * no additions) carries NO section and keeps the historic stamps — such a resume on ANY worker
+ * folds to roots + built-ins, which is exactly the semantics it was cut under.
+ */
+export declare const FACE_CHECKPOINT_VERSION = 9;
 /** The highest {@link Checkpoint.version} `runner.resume` will act on; a higher one is rejected pre-CAS with
  *  {@link CheckpointError} `unsupported_version` (the checkpoint stays `pending`, retryable on a newer worker).
  *  Raised to 8 for realApproval-bearing gates — this worker reads v1 (legacy human), v2 (resource), v3
  *  (binding human/irreversible_ask), v4 (a pre-164 row, refused only when it carries the retired
  *  wall-clock allocation), v5 (token-allocation-bearing resource/approval), v6 (org-admission freeze
- *  state), v7 (F-012 constraint-chain / delegation-provenance enforcement state) and v8 (a
- *  non-budgetable `realApproval` gate bit with its org-origin resume semantics). */
-export declare const MAX_SUPPORTED_CHECKPOINT_VERSION = 8;
+ *  state), v7 (F-012 constraint-chain / delegation-provenance enforcement state), v8 (a
+ *  non-budgetable `realApproval` gate bit with its org-origin resume semantics) and v9 (the
+ *  design/199 read-face section: resolved face + deny-set additions, folded stricter-wins on
+ *  resume). */
+export declare const MAX_SUPPORTED_CHECKPOINT_VERSION = 9;
 /**
  * Read a checkpoint's schema version, defaulting an absent field to **legacy `0`** (a 1.67-era checkpoint
  * written before the field existed — it carries no `workspaceHandle`, so resuming it the v1 way is safe).
@@ -1507,7 +1553,7 @@ export declare class CheckpointError extends Error {
          *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
          *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
          *     current bytes — no worker version redeems a damaged row). */
-        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "constraint_chain_missing";
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
     } | undefined;
     constructor(code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found"
     /** `runner.resume` was handed an {@link ResumeOutcome} whose `gate` arm does not match the
@@ -1628,7 +1674,7 @@ export declare class CheckpointError extends Error {
          *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
          *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
          *     current bytes — no worker version redeems a damaged row). */
-        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "constraint_chain_missing";
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
     } | undefined);
 }
 /**

package/dist/core/checkpoint-store.js

@@ -136,7 +136,8 @@ export const TOKEN_CHECKPOINT_VERSION = 5;
 export const ORG_ADMISSION_CHECKPOINT_VERSION = 6;
 export const F012_CHECKPOINT_VERSION = 7;
 export const REAL_APPROVAL_CHECKPOINT_VERSION = 8;
-export const MAX_SUPPORTED_CHECKPOINT_VERSION = 8;
+export const FACE_CHECKPOINT_VERSION = 9;
+export const MAX_SUPPORTED_CHECKPOINT_VERSION = 9;
 export function checkpointVersionOf(cp) {
     return cp.version ?? 0;
 }

package/dist/core/hooks.d.ts

@@ -724,13 +724,20 @@ export interface ToolGateInput {
      *  - `unavailable`/`parse_error` → FAIL-CLOSED: the ask continues down the ORIGINAL chain
      *    (durable suspend / onAsk / headless auto-deny) exactly as if auto mode were absent
      *    (CC `automode-unavailable`/`automode-parsing-error` — "NOT a policy decision").
-     * SCOPE (declared semantic): this covers EVERY surviving ask, INCLUDING the deterministic egress/
+     * SCOPE (declared semantic): this covers every surviving ask INCLUDING the deterministic egress/
      * irreversibility safety tightens — auto mode is the deployment's explicit choice to let the
      * classifier be the "explicit ask-resolution" for this session (its rule set covers exactly those
      * action classes: outbound writes, irreversible operations, and sensitive-value handling). A
      * deployment that wants human-only
      * resolution for safety asks simply does not arm auto mode. The classifier can never AUTO-ALLOW by
      * failing — only an affirmative `<block>no</block>` allows.
+     * EXCLUDED from that scope (the ask flows the ORIGINAL chain untouched, exactly as if this field
+     * were absent for that one call): an org-constrained ask (design/182 §7.4, either org arm), the
+     * reserved question tool, a call MARKED unresolvable (design/153), a hook-raised or hook-promoted
+     * ask (`decisionReason:"hook"`), and an ask carrying `matchedAskRule` (an explicit `ask` permission
+     * rule matched — #213: a person's standing "ask me each time" is not classifier hesitation). The
+     * last two are the same pair the persisted-rule lane refuses, so the gate's two ask→allow seams
+     * answer provenance questions identically.
      */
     autoMode?: {
         decider: import("./auto-mode.js").AutoModeDecider;
@@ -769,6 +776,10 @@ export interface ToolGateInput {
      *    tool's own egress/irreversibility marks are structural requirements, not classifier hesitation
      *    ("allow rules silence the classifier's questions, never a mandated one"). When a rule matches
      *    but cannot clear, the surviving ask discloses it (message + `persistedRuleShadowed`).
+     *  · #213: an ask carrying `matchedAskRule` (an explicit `ask` permission rule matched this call)
+     *    is never consumed — a person's standing "ask me each time" outranks the memory of one past
+     *    yes, across lanes exactly as the DSL's own deny > ask > allow order says within one. Same
+     *    disclosure as the mandated family when a rule matches anyway.
      * What it DOES consume is the classify-DOCTRINE shell ask (the coarse tier "maybe" — the
      * don't-ask-again main case this feature exists for) and unmarked bare asks. Consuming such an ask
      * also skips the park it would have minted; that IS what a standing approval means, and the

package/dist/core/hooks.js

@@ -354,7 +354,7 @@ export async function runToolGate(input) {
             req.toolName !== ASK_USER_QUESTION_TOOL_NAME &&
             input.isMarkedUnresolvable?.(input.event.toolCallId) !== true) {
             const hit = await input.persistedRules.admits(req).catch(() => undefined);
-            if (hit !== undefined && persistedRuleMandate === undefined) {
+            if (hit !== undefined && persistedRuleMandate === undefined && decision.matchedAskRule === undefined) {
                 decision = {
                     action: "allow",
                     message: `a persisted allow rule (${hit}) covers this call`,
@@ -365,7 +365,11 @@ export async function runToolGate(input) {
             }
             else if (hit !== undefined) {
                 const shownRule = inlineUntrusted(hit, 200);
-                const mandateNoun = persistedRuleMandate === "operator_always" ? "this deployment mandates per-call confirmation for shell commands (shellGate: always)" : "this tool carries egress/irreversibility marks (a mandated confirmation a rule cannot clear)";
+                const mandateNoun = persistedRuleMandate === "operator_always"
+                    ? "this deployment mandates per-call confirmation for shell commands (shellGate: always)"
+                    : persistedRuleMandate !== undefined
+                        ? "this tool carries egress/irreversibility marks (a mandated confirmation a rule cannot clear)"
+                        : "an explicit ask rule matched this call (a person's ask-me-each-time outranks a standing allow rule)";
                 decision = {
                     ...decision,
                     persistedRuleShadowed: shownRule,
@@ -376,6 +380,8 @@ export async function runToolGate(input) {
         if (input.autoMode &&
             !orgRealApprovalRequired &&
             decision.action === "ask" &&
+            decision.decisionReason !== "hook" &&
+            decision.matchedAskRule === undefined &&
             req.toolName !== ASK_USER_QUESTION_TOOL_NAME &&
             input.isMarkedUnresolvable?.(input.event.toolCallId) !== true) {
             const verdict = await input.autoMode.decider

package/dist/core/permission-rules.js

@@ -287,11 +287,11 @@ export function createPermissionRulePolicy(rules, opts) {
                     return { action: "deny", message: ruleMessage("denied", paramDeny.ruleText, paramDeny.source) };
                 }
                 if (entry.bare.ask) {
-                    return { action: "ask", message: ruleMessage("flagged", entry.bare.ask.ruleText, entry.bare.ask.source) };
+                    return { action: "ask", message: ruleMessage("flagged", entry.bare.ask.ruleText, entry.bare.ask.source), matchedAskRule: entry.bare.ask.ruleText };
                 }
                 const paramAsk = matchParamRules(entry.param.ask, req.args, caps.maxScalarValueChars);
                 if (paramAsk) {
-                    return { action: "ask", message: ruleMessage("flagged", paramAsk.ruleText, paramAsk.source) };
+                    return { action: "ask", message: ruleMessage("flagged", paramAsk.ruleText, paramAsk.source), matchedAskRule: paramAsk.ruleText };
                 }
                 if (entry.bare.allow) {
                     return { action: "allow" };

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

@@ -307,14 +307,14 @@ export interface Prepared {
      *  threaded to every compaction-boundary epoch selection so boundary re-pins hash the same
      *  artifact identity as the prepare-time pin. Empty on declaration-free runs. */
     epochDeclaredSections: import("../../prompt-assembly/epoch.js").EpochDeclaredSections;
+    /** design/148 S3 — the LIVE nine-element identity face (refreshed by deferred materialization and
+     *  the RB-31 adoption swap); the manifest holds the prepare-time initial copy. */
+    turnSnapshot?: import("../../prompt-assembly/turn-snapshot.js").TurnPromptSnapshot;
     /** RB-31 (design/148 S2) — the compaction-boundary center-adoption seam (undefined = no source
      *  wired or session not center-pinned). Returns the maybeCompact `centerAdoption` fragment or
      *  undefined; `apply` runs post-CAS only (auto-compaction owns the ordering). Both
      *  `epochDeclaredSections` and `promptOverheadTokens` on THIS object are mutated by a successful
      *  adoption (read them at call time, never capture early). */
-    /** design/148 S3 — the LIVE nine-element identity face (refreshed by deferred materialization and
-     *  the RB-31 adoption swap); the manifest holds the prepare-time initial copy. */
-    turnSnapshot?: import("../../prompt-assembly/turn-snapshot.js").TurnPromptSnapshot;
     centerCompactionCandidate?: () => {
         centerArtifactDigest?: string;
         sourceRevision?: string;
@@ -573,8 +573,15 @@ export interface Prepared {
     /** Narrow workspace reader for compaction working-file attachments (LONGRUN-2): reads a task file
      *  via the SAME env the hands ran against (so remote/k8s/E2B tasks read the container's tree, not
      *  the control plane's). Present only when the hands are enabled — without an env there is no
-     *  workspace to re-read. null = unreadable (deleted/binary/transport error); callers skip it. */
-    readTaskFile?: (path: string) => Promise<string | null>;
+     *  workspace to re-read. null = unreadable (deleted/binary/transport error); callers skip it.
+     *  design/199 件B: `{ withheld }` = the target matches the sensitive-path read deny list — the
+     *  attachment is deliberately withheld and the consumer must SAY so (an annotation, never a silent
+     *  skip: a silently missing attachment reads as "file gone", which is a different fact). */
+    readTaskFile?: (path: string) => Promise<string | null | {
+        withheld: {
+            pattern: string;
+        };
+    }>;
     /** CC post-compact restore parity (2026-07-03): the task's READ files, most recent
      *  first (from the hands' readFileState `lastReadAt` stamps). The compaction working-file
      *  attachment prefers this over the modified set — CC restores what the model RECENTLY READ,
@@ -1483,6 +1490,15 @@ export declare function rebaseWorkspacePath(p: string, fromRaw: string, toRaw: s
  * which case the earlier — more specific — spelling is the intended one. Exported for direct unit pinning.
  */
 export declare function rebaseWorkspacePathAcross(p: string, froms: readonly string[], to: string): string;
+/**
+ * Build everything a task run needs (council design/34 ②: a free function with EXPLICIT deps, not a
+ * Runner method — testable and decoupled). Resolves the model/role/thinking, acquires + reconciles the
+ * session (with the conflict-detecting Proxy + bounded re-wake on a lost CAS), assembles the tool set
+ * (caller tools + offload wrap + report_blocked + submit_output + MCP + memory + read_tool_result),
+ * builds the system prompt, constructs the harness, wires the tool-policy gate + context-edit/guard
+ * hooks + external-signal cancellation, and sets up the cache-break detector. **No run-loop control
+ * flow** lives here — that stays in the Runner loop.
+ */
 export declare function prepareTask(spec: TaskSpec, deps: RunnerDeps, sessions: SessionStore, resume?: PrepareResume, internals?: RunInternals, 
 /** design/98 §3.1 (S8c): a TRUSTED self-reference to the Runner, passed by the Runner itself (never a
  *  TaskSpec field) so the `run_workflow` tool can execute child tasks via `runner.runTask`. Undefined when