@sema-agent/core 5.30.0 → 5.31.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 5.31.0 — 2026-08-14
+
+No API-BREAKING changes. Behavior narrowings are all tighten-direction (auto-allow → ask, or
+map → refuse) and named below; two additive surfaces (an optional contract-kit callback, a
+workflow-governance notice family).
+
+### Narrowed (behavior)
+
+- **Recursive/expanding read forms demote from auto-allow to ask when the sensitive-path deny set
+  is in force.** The bash read-only classifier's traversal set is not in the command text —
+  `grep -r . dir` names `dir`, not the `.ssh` it reaches — so under a wired deny judge, a
+  recursive verb (`grep -r/-R`, `ls -R`, `du`, `find`, `rg`/`ag`/`ack`/`tree` — recursive by
+  default, `tar` creation modes, `diff -r`) with a path operand is UNDECIDED and asks. Per-verb
+  getopt-aware form table (BSD/GNU divergences resolve demote-ward; divergent option-letter
+  ownership is scanned, not skipped); a bare `-` operand keeps stdin meaning only where the
+  command grants it (ls/du open a file literally named `-`); a recursive verb with NO operand
+  demotes too — the implicit cwd is the traversal root (`du`, `ls -R`, `tree` traverse `.` when
+  given nothing). A persisted allow rule clears the ask permanently (the rule lane absorbs the
+  one-time friction).
+- **The classifier's operand walk honors POSIX end-of-options on EVERY face** (the same window's
+  `--` correction, disclosed as its own item because it flips behavior in BOTH directions on the
+  `bash_readonly` face too, which has no ask channel): past a bare `--`, a dash-leading token is
+  an OPERAND. Spellings like `cat -- -f/etc/passwd` used to be refused on a path extracted from
+  inside the token as if it were an option (a false refusal — the real program opens a relative
+  file literally named `-f/etc/passwd`); they now execute. Conversely a dash-named operand
+  (`cat -- -dir a.txt`) now enters symlink/boundary checking it previously skipped, so a
+  dash-named symlink pointing out of the roots is now refused. No new admission lands outside
+  the containment roots.
+- **Win32 extended-length (`\\?\`) spellings map to DOS form only when the strip is an identity.**
+  Non-mappable bodies (`Volume{GUID}`, `GLOBALROOT`, device names, drive-relative `\\?\C:`,
+  forward-slash separators, empty/`.`/`..` components, trailing dots/spaces, reserved DOS device
+  components — `CONIN$`, superscript `COM¹` aliases included) now REFUSE by name instead of
+  silently resolving to a different file than the spelling denotes (approval-to-execution drift).
+  `WIN_RESERVED_RE` widens to the full documented reserved set (COM0/LPT0, superscript aliases,
+  `CONIN$`/`CONOUT$`) for every win-form key. UNC tail segments fold Win32 trailing dots/spaces so
+  a deny pattern matches the alias spelling.
+- **The transcript-replay and startup-seed legs judge with the resolved read face** (open-face
+  twins of 5.30.0's attachment fix): a file legitimately read out-of-root under `readFace:"open"`
+  re-seeds across turns instead of being silently re-locked. A garbage `readFace` value now
+  refuses loudly on hands-less runs too (the value screen is unconditional).
+- **Workflow governance: a governed script may declare the two read-face TIGHTENINGS**
+  (`readFace:"roots"` — admitted by VALUE, `"open"` never crosses — and `readDenyPatterns`,
+  grammar-checked by the child's own compiler). Every stripped unknown key is announced via the
+  new `workflow.governance_key_stripped` notice (one aggregated notice per governed build); the
+  WHITELIST_KEYS comment no longer claims a refusal rule that never existed.
+
+### Added
+
+- **`toolResultStoreContract` gains an optional third parameter `onOptionalMember`** — the
+  observable channel for optional-member coverage (`deleteBySession`: `verified` | `absent`).
+  Previously absence was "reported" via an always-true assert message that only prints on failure,
+  so verified and absent produced byte-identical green runs. A present-but-uncallable member now
+  fails loudly as a defect. Additive: omitting the callback keeps prior behavior.
+- **`PgToolResultStore.deleteBySession`** — the pg sibling of the file backend's session sweep
+  (same four-state semantics; one CTE statement so the deletion and the unattributable count come
+  from the same snapshot). The observable-absence channel above is what exposed it as missing.
+- **Deny-refusal disclosure cites the view the pattern actually matched** (`ReadDenyHit.matchedView`):
+  under a symlink/case alias the canonical target and the requested spelling differ, and naming
+  the unmatched one sent the reader chasing a path the pattern does not match.
+- Search results keep the honesty caveat and the deny-withholding note as SEPARATE disclosures
+  (a tail-anchored bracket merge used to splice read-loop facts into the deny note and drop the
+  "results may be incomplete" marker whenever pruning fired).
+- Checkpoint face section: a compile-time closed-set guard forces a deliberate carry-or-drop
+  ruling when a new section key is added (the hands-less seed-carry whitelist can no longer
+  silently lag the persisted shape).
+
 ## 5.30.0 — 2026-08-13
 
 No API-BREAKING changes (exports grow only: `resolveReadFace`, `ReadFace`, `ReadFaceInputs`,
@@ -19,6 +85,18 @@ No API-BREAKING changes (exports grow only: `resolveReadFace`, `ReadFace`, `Read
   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.
+- **Checkpoint schema v9** (erratum 2026-08-13 — this deserved its own entry, not a clause above; a
+  store schema bump is a load-bearing event for store implementors regardless of which feature rides
+  it). What v9 is: rows minted under a non-default read-face posture carry a `readFace` section —
+  `{ face: "open" | "roots", denyEntries?: Array<{pattern, caseSensitive}>, realApproval?: true }` —
+  and the resume pre-CAS ladder validates it (a malformed section refuses the row; a v9+ row claiming
+  `realApproval: true` with no well-formed gate bit refuses as `real_approval_damaged`). Absence
+  semantics: a missing section (all pre-v9 rows, and v9 rows minted under the default posture) means
+  ROOTS — zero migration, no existing row's behavior changes. Store implementors (SQL backends
+  included): the section is part of the opaque checkpoint state blob, so no schema/DDL change is
+  required — but a store that inspects or rewrites state must treat the section as tamper-guarded
+  (the pre-CAS ladder refuses a row whose section it cannot validate), and `MAX_SUPPORTED` acceptance
+  now includes v9.
 - **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

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

@@ -74,7 +74,7 @@ import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.j
 import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../task-registry.js";
 import { createMonitorTool } from "../../tools/monitor.js";
 import { createWorktreeTools } from "../../tools/worktree.js";
-import { applyCompactionToReadFileState, bashReversibilityProbe, compileReadDeny, createHandsToolkit, isReadDedupStubResult, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, FULL_SHELL_CONTRACT_ID, HAND_TOOL_EFFECTS, pdfModelCapabilitiesOf } from "../../tools/fs/index.js";
+import { applyCompactionToReadFileState, assertReadFaceValue, bashReversibilityProbe, compileReadDeny, createHandsToolkit, isReadDedupStubResult, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, FULL_SHELL_CONTRACT_ID, HAND_TOOL_EFFECTS, pdfModelCapabilitiesOf } from "../../tools/fs/index.js";
 import { decodeTextBytes } from "../../tools/fs/encoding.js";
 import { ASK_USER_QUESTION_TOOL_NAME, createAskUserQuestionTool, classifyQuestionOutcome, isLiveQuestionFace, validateAskQuestions, } from "../ask-question.js";
 import { createSchedulerTools } from "../../tools/scheduler-tools.js";
@@ -342,6 +342,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             throw e;
         }
     }
+    assertReadFaceValue(spec.readFace, "TaskSpec.readFace");
+    assertReadFaceValue(deps.readFace, "readFace (deployment seat)");
     if (spec.resumeAtMode !== undefined) {
         if (spec.resumeAt === undefined) {
             const e = new Error(`resumeAtMode "${spec.resumeAtMode}" requires resumeAt (there is no branch target to position against)`);
@@ -1388,6 +1390,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 parentThinking: () => harnessRef.current?.getThinkingLevel() ?? thinking,
                 parentReadFace: () => resolvedReadFace,
                 parentReadDenyPatterns: () => (readDenyAdditionsNormalized.length > 0 ? readDenyAdditionsNormalized : undefined),
+                onNotice: deps.onNotice,
                 parentCheckpointStoreDisabled: spec.checkpointStore === null,
                 parentCenterArtifactDigest: () => centerAdoption?.artifact.artifactDigest,
                 parentCenterSourceRevision: () => centerAdoption?.sourceRevision,
@@ -1652,17 +1655,9 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             }
             const readFileState = new Map((resume?.seed.readFileState ?? []).map(([k, v]) => [rebaseRestoredPath(k), v]));
             readFileStateForCheckpoint = readFileState;
-            if (resume === undefined && spec.sessionId !== undefined) {
-                const prior = await session.buildContext().catch(() => undefined);
-                for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
-                    const rk = await resolveKey(executionEnv, rootCanonical, rec.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical]);
-                    if (rk.ok)
-                        seedReadFileStateFromTranscript(readFileState, rk.key, rec.content, rec.at);
-                }
-            }
             seedContextFiles = async (files) => {
                 for (const f of files) {
-                    const rk = await resolveKey(executionEnv, rootCanonical, f.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical]);
+                    const rk = await resolveKey(executionEnv, rootCanonical, f.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, resolvedReadFace);
                     if (rk.ok)
                         seedReadFileStateFromContext(readFileState, rk.key, f.content);
                 }
@@ -1701,6 +1696,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             if (resume !== undefined && (seedReadFaceSection === undefined || seedReadFaceSection.face === "roots"))
                 liveReadFace = "roots";
             resolvedReadFace = liveReadFace;
+            if (resume === undefined && spec.sessionId !== undefined) {
+                const prior = await session.buildContext().catch(() => undefined);
+                for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
+                    const rk = await resolveKey(executionEnv, rootCanonical, rec.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, liveReadFace);
+                    if (rk.ok)
+                        seedReadFileStateFromTranscript(readFileState, rk.key, rec.content, rec.at);
+                }
+            }
             const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
                 ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
                 ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),

package/dist/core/store-contracts/tool-result-store-contract.d.ts

@@ -19,4 +19,7 @@ import { type ContractAssertionRunner } from "./contract-harness.js";
  * host-side read face, and an optional parameter one store honors while another drops it silently is
  * exactly the divergence the two legs above exist to prevent.
  */
-export declare function toolResultStoreContract(make: () => ToolResultStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function toolResultStoreContract(make: () => ToolResultStore, runAssertion?: ContractAssertionRunner, onOptionalMember?: (report: {
+    member: "deleteBySession";
+    status: "verified" | "absent";
+}) => void): Promise<void>;

package/dist/core/store-contracts/tool-result-store-contract.js

@@ -1,6 +1,6 @@
 import { strict as assert } from "node:assert";
 import { beginContract } from "./contract-harness.js";
-export async function toolResultStoreContract(make, runAssertion) {
+export async function toolResultStoreContract(make, runAssertion, onOptionalMember) {
     const { run, settle } = beginContract(runAssertion);
     run("put/get full + sliced; write-once no-op; unknown → undefined", async () => {
         const store = make();
@@ -57,10 +57,11 @@ export async function toolResultStoreContract(make, runAssertion) {
     });
     run("#196 deleteBySession (optional): four-state semantics when present; absence is REPORTED, not silently green", async () => {
         const probe = make();
-        if (typeof probe.deleteBySession !== "function") {
-            assert.equal(probe.deleteBySession, undefined, "deleteBySession is NOT IMPLEMENTED on this backend — sweep semantics unverified (optional member; this is a disclosure, not a failure)");
+        if (probe.deleteBySession === undefined) {
+            onOptionalMember?.({ member: "deleteBySession", status: "absent" });
             return;
         }
+        assert.equal(typeof probe.deleteBySession, "function", `deleteBySession is present but not callable (got ${typeof probe.deleteBySession}) — a garbage member is a DEFECT, not an optional-member absence`);
         const store = make();
         const del = (sessionId) => Promise.resolve(store.deleteBySession(sessionId));
         await store.put("tr_sweep~a", "A-bytes", { sessionId: "sess-X", taskId: "t1" });
@@ -77,6 +78,7 @@ export async function toolResultStoreContract(make, runAssertion) {
         const second = await del("sess-X");
         assert.equal(second.deleted, 0, "a repeated sweep deletes nothing");
         assert.equal((await store.get("tr_sweep~other")).content, "OTHER-bytes");
+        onOptionalMember?.({ member: "deleteBySession", status: "verified" });
     });
     await settle();
 }

package/dist/core/tool-result-store.d.ts

@@ -103,10 +103,12 @@ export interface ToolResultStore {
      *   - **concurrency-tolerant**: an entry that disappears between enumeration and removal is honest
      *     absence, not an error.
      *
-     * Typed OPTIONAL, and deliberately NOT part of the published contract kit
-     * (`toolResultStoreContract`): unlike `ownerOf`, a backend that cannot enumerate by owner is still
-     * a usable offload store, so its absence must stay a checkable fact rather than a contract breach.
-     * Present ⇒ the store can complete a session deletion; absent ⇒ the deployment owns that gap.
+     * Typed OPTIONAL, and an OPTIONAL leg of the published contract kit (`toolResultStoreContract`,
+     * its #196 case): unlike `ownerOf`, a backend that cannot enumerate by owner is still a usable
+     * offload store, so absence is never a contract breach — the kit verifies the four-state
+     * semantics when the member is present and reports absence through its `onOptionalMember`
+     * callback (a checkable fact, not a failure). Present ⇒ the store can complete a session
+     * deletion; absent ⇒ the deployment owns that gap.
      *
      * Implementing it does NOT make a store `retention: "managed"` — that declaration promises the whole
      * {@link import("./retention.js").ManagedRetentionCapability} (domain enumeration, tombstones,

package/dist/core/types.d.ts

@@ -4223,7 +4223,14 @@ export interface EngineNotice {
      *    failed; THIS attempt stored nothing (the failure arm reports, it never re-inserts under the
      *    ref) — an earlier attempt of the same idempotent re-put may already have stored the row, so
      *    the notice claims a failed write, not an empty ref; `detail: { ref, sessionId, cause }`.
-     *    Per-occurrence, not per-process-deduplicated: each failed write is a distinct fact. */
+     *    Per-occurrence, not per-process-deduplicated: each failed write is a distinct fact.
+     *  - `"workflow.governance_key_stripped"` (#235) — the fields of an LLM-authored workflow `agent(spec)`
+     *    that did NOT cross the governed default-deny whitelist: an unrecognized/control-plane field, or a
+     *    `readFace` value that is not the containment-tightening one. The spawn PROCEEDS on the deployment
+     *    baseline (the strip is not a refusal in this window), which is why the drop is announced;
+     *    `detail: { total, stripped: [{ key, reason }], omitted? }`, the rendered key list bounded in count
+     *    and length because the names come from the untrusted script. One aggregated notice per governed
+     *    child build, not de-duplicated across builds: each spec is a distinct fact. */
     code: string;
     /** The exact human-readable line the unwired build prints via `console.warn` — same words, one text. */
     message: string;

package/dist/orchestration/run-workflow-tool.d.ts

@@ -267,6 +267,11 @@ export interface RunWorkflowToolDeps {
      *  ctx is minimal `{toolCallId, signal}`, so `ctx.checkpointStoreDisabledForChildren` was a DEAD
      *  read there — the off-switch never actually reached this lane's children. */
     parentCheckpointStoreDisabled?: boolean;
+    /** #235 — the deployment's structured notice sink (`RunnerDeps.onNotice`), forwarded into the governed
+     *  build so the fields a script's agent spec wrote that did NOT reach the child are announced instead of
+     *  vanishing (`workflow.governance_key_stripped`). A dep for the same reason as the seats above: this
+     *  auto-mount's execute ctx is minimal. Absent ⇒ the historic `console.warn` loudness. */
+    onNotice?: (n: import("../core/types.js").EngineNotice) => void;
     /** Twin of the above for design/148 S1's center-artifact inheritance (see the `ctx.centerArtifactDigest`/
      *  `ctx.centerSourceRevision` reads at the `startWorkflow` options site) — `centerAdoption` resolves
      *  LATE in prepare-task.ts (well after this tool's mount point), so this is a call-time getter, not

package/dist/orchestration/run-workflow-tool.js

@@ -167,7 +167,7 @@ export async function createRunWorkflowTool(d) {
                 : {}),
         }
         : d.governanceBaseline;
-    const governance = { baseline: baselineWithParentFace, models: d.models, caps: childCaps };
+    const governance = { baseline: baselineWithParentFace, models: d.models, caps: childCaps, onNotice: d.onNotice };
     const builtinsEnabled = d.builtinWorkflows !== false;
     const namedWorkflowSection = renderNamedWorkflowListing(await collectNamedWorkflowListings(d.scriptStore, builtinsEnabled));
     const sizeGuidelineSection = workflowSizeGuidelineSection(d.sizeGuideline ?? lim.sizeGuideline);

package/dist/orchestration/workflow-governance.d.ts

@@ -13,7 +13,8 @@
  * cost/token caps — codex Q4).
  */
 import type { Model } from "../internal/llm.js";
-import type { ImageInput, TaskSpec, ThinkingLevel, WorkflowGovernanceBaseline } from "../core/types.js";
+import type { EngineNotice, ImageInput, TaskSpec, ThinkingLevel, WorkflowGovernanceBaseline } from "../core/types.js";
+import { type ReadDenyEntry } from "../tools/fs/read-deny.js";
 /** Thrown when an LLM-authored script picks a `modelName` not in the workflow model allowlist (or no
  *  allowlist is configured). FAIL-CLOSED: a script can only ever name a model the deployment pre-approved. */
 export declare class WorkflowModelNotAllowedError extends Error {
@@ -41,12 +42,56 @@ export interface WorkflowAgentSpec {
         maxTokens?: number;
         maxCostUsd?: number;
     };
+    /**
+     * design/199 件A, TIGHTEN-ONLY: `"roots"` — the read-face containment judgment — is the ONLY value a
+     * script may set. `"open"` is the WIDENING direction (it removes the containment step), so it is
+     * stripped and announced rather than applied; the type states the asymmetry, and
+     * {@link pickWhitelist} enforces it on the untrusted value.
+     */
+    readFace?: "roots";
+    /**
+     * design/199 件B, TIGHTEN-ONLY: additional read-deny entries. Add-only at every layer (the built-in
+     * table and the baseline's entries are always in force and cannot be removed or replaced — see
+     * `compileReadDeny`'s zero-shrink contract and `tightenTaskSpec`'s union), so anything a script
+     * writes here can only ever narrow what the child may read.
+     */
+    readDenyPatterns?: readonly ReadDenyEntry[];
 }
 /**
  * The SINGLE source of truth for the whitelist (a test pins that it contains no control-plane key). `objective`
  * + `modelName` are handled explicitly in {@link buildGovernedChildSpec}; the rest map 1:1 onto `TaskSpec`.
+ *
+ * WHAT HAPPENS TO EVERY OTHER FIELD — {@link pickWhitelist} READS these keys and only these keys; it never
+ * enumerates the script's fields to judge them, which is precisely the complete-by-construction property this
+ * module is built on (nothing can leak by being forgotten in a denylist). The consequence is that an
+ * unrecognized field is STRIPPED, not refused: the spawn proceeds on the baseline as if the field had never
+ * been written. That silence is what {@link STRIPPED_KEYS_NOTICE_CODE} exists to close — one aggregated
+ * notice per governed build names the fields that did not cross the seam, so a mistyped budget axis (a
+ * top-level `maxCostUsd` that belongs inside `limits` since design/164, which would run the child unbounded
+ * on exactly the axis the author tried to bound) or a rejected containment request is visible to the operator
+ * instead of evaporating. Turning the strip into a LOUD REFUSAL that fails the spawn is a deliberate
+ * NON-GOAL of this window: it would break every existing script carrying a harmless extra field, and is held
+ * for a BREAKING window.
+ */
+export declare const WHITELIST_KEYS: readonly ["objective", "modelName", "thinking", "systemPrompt", "images", "limits", "readFace", "readDenyPatterns"];
+/**
+ * One field of an untrusted agent spec that did NOT reach the child, and why.
+ *  - `not_whitelisted` — the field is outside {@link WHITELIST_KEYS}: a control-plane field, a work field
+ *    spelled at the wrong nesting level, or plain noise. It was never read.
+ *  - `not_a_tightening_value` — the KEY is whitelisted but only its containment-TIGHTENING value may cross
+ *    the seam, and the script wrote a different one. Today that is `readFace`, where `"roots"` tightens and
+ *    anything else (`"open"`, or garbage) would either widen the child's read face or ask for a value the
+ *    resolver does not define.
  */
-export declare const WHITELIST_KEYS: readonly ["objective", "modelName", "thinking", "systemPrompt", "images", "limits"];
+export interface StrippedSpecKeyNote {
+    key: string;
+    reason: "not_whitelisted" | "not_a_tightening_value";
+}
+/** The {@link EngineNotice} family for the strip announcement (see {@link WHITELIST_KEYS}). ONE notice per
+ *  governed build, listing every field that did not cross the seam — a governed script can carry an
+ *  arbitrary number of unrecognized fields, and a per-field notice would turn one authoring mistake into a
+ *  flood. Not de-duplicated across builds: each spawn is a distinct fact about a distinct spec. */
+export declare const STRIPPED_KEYS_NOTICE_CODE = "workflow.governance_key_stripped";
 /** Per-child workflow ceilings the engine forces onto every spawned agent (design/98 §D.6), independent of
  *  what the script asks for. The child's effective limits = min(script, baseline, these). */
 export interface WorkflowChildCaps {
@@ -91,5 +136,10 @@ export declare function resolveModelName(name: string, allowlist: string[] | und
  * disclosure hook the caller can wire to a log/event channel (see `buildWorkflowPrimitives`, which logs it
  * onto the run's log stream so the LLM-authored script's caller can see requested→applied per field instead
  * of the child silently running under different limits than the script wrote).
+ *
+ * `onNotice` is the deployment's structured notice sink (`RunnerDeps.onNotice`): step 1's strip is announced
+ * through it as one aggregated {@link STRIPPED_KEYS_NOTICE_CODE} notice (see {@link WHITELIST_KEYS}). An
+ * absent sink keeps the historic loudness (`console.warn`); the delivery itself is swallow-guarded, so no
+ * sink can turn an announcement into a failed spawn.
  */
-export declare function buildGovernedChildSpec(scriptSpec: unknown, baseline: WorkflowGovernanceBaseline, models: Record<string, Model> | undefined, caps?: WorkflowChildCaps, onResourceClamp?: (notes: ResourceClampNote[]) => void): TaskSpec;
+export declare function buildGovernedChildSpec(scriptSpec: unknown, baseline: WorkflowGovernanceBaseline, models: Record<string, Model> | undefined, caps?: WorkflowChildCaps, onResourceClamp?: (notes: ResourceClampNote[]) => void, onNotice?: (n: EngineNotice) => void): TaskSpec;

package/dist/orchestration/workflow-governance.js

@@ -1,5 +1,7 @@
+import { deliverEngineNotice } from "../core/types.js";
 import { tightenTaskSpec } from "../core/tighten-task-spec.js";
 import { sanitizeUntrustedText } from "../core/untrusted-text.js";
+import { compileReadDeny } from "../tools/fs/read-deny.js";
 import { WorkflowScriptError } from "./workflow-meta.js";
 export class WorkflowModelNotAllowedError extends Error {
     modelName;
@@ -17,7 +19,43 @@ export const WHITELIST_KEYS = [
     "systemPrompt",
     "images",
     "limits",
+    "readFace",
+    "readDenyPatterns",
 ];
+const WHITELIST_KEY_SET = new Set(WHITELIST_KEYS);
+export const STRIPPED_KEYS_NOTICE_CODE = "workflow.governance_key_stripped";
+const MAX_STRIPPED_KEYS_ANNOUNCED = 20;
+const MAX_STRIPPED_KEY_CHARS = 64;
+const UNSAFE_KEY_CODE_POINT = /[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/u;
+function renderStrippedKey(key) {
+    let out = "";
+    let seen = 0;
+    for (const point of key) {
+        if (seen === MAX_STRIPPED_KEY_CHARS)
+            return `${out}…`;
+        out += UNSAFE_KEY_CODE_POINT.test(point) ? "?" : point;
+        seen++;
+    }
+    return out;
+}
+function emitStrippedKeysNotice(survey, onNotice) {
+    const shown = survey.sample.map((s) => ({ key: renderStrippedKey(s.key), reason: s.reason }));
+    const omitted = survey.total - shown.length;
+    const list = shown.map((s) => JSON.stringify(s.key)).join(", ") + (omitted > 0 ? `, +${omitted} more` : "");
+    const message = `workflow governance: ${survey.total} field(s) of an agent spec were NOT applied to the child (${list}). ` +
+        `A governed workflow script may set only: ${WHITELIST_KEYS.join(", ")} — and \`readFace\` only as "roots" ` +
+        `(the containment-tightening direction; "open" widens and is never taken from a script). Every other field ` +
+        `of the child comes from the deployment baseline.`;
+    try {
+        deliverEngineNotice(onNotice, {
+            code: STRIPPED_KEYS_NOTICE_CODE,
+            message,
+            detail: { total: survey.total, stripped: shown, ...(omitted > 0 ? { omitted } : {}) },
+        });
+    }
+    catch {
+    }
+}
 const VALID_THINKING = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 export function resolveModelName(name, allowlist, models) {
     if (!allowlist || allowlist.length === 0) {
@@ -49,49 +87,121 @@ function pickImageInput(el, i) {
     }
     const o = el;
     if ("url" in o) {
-        if (typeof o.url !== "string" || o.url.length === 0) {
+        const url = o.url;
+        if (typeof url !== "string" || url.length === 0) {
             throw new WorkflowScriptError(`${at}.url must be a non-empty string`);
         }
-        return { url: o.url };
+        return { url };
     }
-    if (typeof o.data !== "string") {
+    const data = o.data;
+    const mimeType = o.mimeType;
+    if (typeof data !== "string") {
         throw new WorkflowScriptError(`${at}.data must be a base64 string (or supply { url } instead)`);
     }
-    if (typeof o.mimeType !== "string" || o.mimeType.length === 0) {
+    if (typeof mimeType !== "string" || mimeType.length === 0) {
         throw new WorkflowScriptError(`${at}.mimeType must be a non-empty string, e.g. "image/png"`);
     }
-    return { data: o.data, mimeType: o.mimeType };
+    return { data, mimeType };
+}
+const MAX_SCRIPT_DENY_ENTRIES = 16;
+const MAX_SCRIPT_DENY_PATTERN_CHARS = 256;
+const MAX_SCRIPT_DENY_WILDCARDS_PER_SEGMENT = 1;
+const MAX_SCRIPT_IMAGES = 32;
+function assertScriptDenyPatternBounded(pattern, at) {
+    if (pattern.length > MAX_SCRIPT_DENY_PATTERN_CHARS) {
+        throw new WorkflowScriptError(`${at} is ${pattern.length} characters — a workflow script's deny pattern is limited to ${MAX_SCRIPT_DENY_PATTERN_CHARS} (the matcher runs on every read of the child's run).`);
+    }
+    for (const segment of pattern.split("/")) {
+        const wildcards = segment.split("*").length - 1;
+        if (wildcards > MAX_SCRIPT_DENY_WILDCARDS_PER_SEGMENT) {
+            throw new WorkflowScriptError(`${at} has a path segment with ${wildcards} \`*\` wildcards — a workflow script's deny pattern allows at most ` +
+                `${MAX_SCRIPT_DENY_WILDCARDS_PER_SEGMENT} per path segment (the same expressiveness the engine's built-in deny table ` +
+                `uses). Each \`*\` compiles to a greedy match, and more than one in a single segment makes the judgment cost grow ` +
+                `superlinearly with the path length, on every read the child performs. Write the intent as separate entries ` +
+                `(the set is a union, so more entries deny strictly more) or anchor it with literal segments.`);
+        }
+    }
+}
+function mapUntrustedArray(value, at, atMost, why, build) {
+    const declared = value.length;
+    if (typeof declared !== "number" || !Number.isSafeInteger(declared) || declared < 0) {
+        throw new WorkflowScriptError(`${at} does not report a valid array length.`);
+    }
+    if (declared > atMost) {
+        throw new WorkflowScriptError(`${at} carries ${declared} entries — a workflow script may set at most ${atMost}. ${why}`);
+    }
+    const out = [];
+    for (let i = 0; i < declared; i++)
+        out.push(build(value[i], i));
+    return out;
+}
+function pickReadDenyEntry(el, i) {
+    const at = `agent(spec): \`readDenyPatterns[${i}]\``;
+    if (typeof el === "string") {
+        if (el.length === 0)
+            throw new WorkflowScriptError(`${at} must be a non-empty pattern string`);
+        assertScriptDenyPatternBounded(el, at);
+        return el;
+    }
+    if (typeof el !== "object" || el === null || Array.isArray(el)) {
+        throw new WorkflowScriptError(`${at} must be a pattern string or an object { pattern, caseSensitive? }`);
+    }
+    const o = el;
+    const pattern = o.pattern;
+    const caseSensitive = o.caseSensitive;
+    if (typeof pattern !== "string" || pattern.length === 0) {
+        throw new WorkflowScriptError(`${at}.pattern must be a non-empty string, e.g. ".ssh" or "secrets/*.json"`);
+    }
+    if (caseSensitive !== undefined && typeof caseSensitive !== "boolean") {
+        throw new WorkflowScriptError(`${at}.caseSensitive must be a boolean`);
+    }
+    assertScriptDenyPatternBounded(pattern, at);
+    return caseSensitive === undefined ? { pattern } : { pattern, caseSensitive };
 }
 function pickWhitelist(scriptSpec) {
     if (typeof scriptSpec !== "object" || scriptSpec === null || Array.isArray(scriptSpec)) {
         throw new WorkflowScriptError("agent(spec): spec must be an object with at least an `objective` string");
     }
     const s = scriptSpec;
-    if (typeof s.objective !== "string" || s.objective.length === 0) {
+    const stripped = { total: 0, sample: [] };
+    for (const k of Object.keys(s)) {
+        if (WHITELIST_KEY_SET.has(k))
+            continue;
+        stripped.total++;
+        if (stripped.sample.length < MAX_STRIPPED_KEYS_ANNOUNCED)
+            stripped.sample.push({ key: k, reason: "not_whitelisted" });
+    }
+    const objective = s.objective;
+    const thinking = s.thinking;
+    const systemPrompt = s.systemPrompt;
+    const modelNameRaw = s.modelName;
+    if (typeof objective !== "string" || objective.length === 0) {
         throw new WorkflowScriptError("agent(spec): `objective` is required and must be a non-empty string");
     }
-    const safe = { objective: s.objective };
-    if (s.thinking !== undefined) {
-        if (typeof s.thinking !== "string" || !VALID_THINKING.has(s.thinking)) {
+    const safe = { objective };
+    if (thinking !== undefined) {
+        if (typeof thinking !== "string" || !VALID_THINKING.has(thinking)) {
             throw new WorkflowScriptError(`agent(spec): invalid \`thinking\` (must be one of ${[...VALID_THINKING].join(", ")})`);
         }
-        safe.thinking = s.thinking;
+        safe.thinking = thinking;
     }
-    if (s.systemPrompt !== undefined) {
-        if (typeof s.systemPrompt !== "string")
+    if (systemPrompt !== undefined) {
+        if (typeof systemPrompt !== "string")
             throw new WorkflowScriptError("agent(spec): `systemPrompt` must be a string");
-        safe.systemPrompt = `[workflow-script-authored persona — task guidance, not engine authority]\n${sanitizeUntrustedText(s.systemPrompt)}`;
+        safe.systemPrompt = `[workflow-script-authored persona — task guidance, not engine authority]\n${sanitizeUntrustedText(systemPrompt)}`;
     }
-    if (s.images !== undefined) {
-        if (!Array.isArray(s.images))
+    const images = s.images;
+    if (images !== undefined) {
+        if (!Array.isArray(images))
             throw new WorkflowScriptError("agent(spec): `images` must be an array");
-        safe.images = s.images.map(pickImageInput);
+        safe.images = mapUntrustedArray(images, "agent(spec): `images`", MAX_SCRIPT_IMAGES, "Each one is decoded and shipped on every request of the child's turn.", pickImageInput);
     }
-    if (s.limits !== undefined) {
-        if (typeof s.limits !== "object" || s.limits === null || Array.isArray(s.limits)) {
+    const limitsRaw = s.limits;
+    if (limitsRaw !== undefined) {
+        if (typeof limitsRaw !== "object" || limitsRaw === null || Array.isArray(limitsRaw)) {
             throw new WorkflowScriptError("agent(spec): `limits` must be an object { maxTurns?, maxWalltimeMs?, maxTokens?, maxCostUsd? }");
         }
-        const l = s.limits;
+        const l = limitsRaw;
         const limits = {};
         const readAxis = (field, what) => {
             const raw = l[field];
@@ -109,13 +219,38 @@ function pickWhitelist(scriptSpec) {
         readAxis("maxCostUsd", "spend ceiling");
         safe.limits = limits;
     }
+    if (s.readFace !== undefined) {
+        if (s.readFace === "roots") {
+            safe.readFace = "roots";
+        }
+        else {
+            stripped.total++;
+            stripped.sample.unshift({ key: "readFace", reason: "not_a_tightening_value" });
+            if (stripped.sample.length > MAX_STRIPPED_KEYS_ANNOUNCED)
+                stripped.sample.pop();
+        }
+    }
+    const readDenyPatternsRaw = s.readDenyPatterns;
+    if (readDenyPatternsRaw !== undefined) {
+        if (!Array.isArray(readDenyPatternsRaw)) {
+            throw new WorkflowScriptError('agent(spec): `readDenyPatterns` must be an array of deny entries (a "/"-separated segment run such as ".ssh", or { pattern, caseSensitive? })');
+        }
+        const entries = mapUntrustedArray(readDenyPatternsRaw, "agent(spec): `readDenyPatterns`", MAX_SCRIPT_DENY_ENTRIES, "Every entry is judged against every path the child reads, for the child's whole run; the built-in and deployment entries are always in force on top of these.", pickReadDenyEntry);
+        try {
+            compileReadDeny(entries, "agent(spec).readDenyPatterns");
+        }
+        catch (err) {
+            throw new WorkflowScriptError(err instanceof Error ? err.message : String(err));
+        }
+        safe.readDenyPatterns = entries;
+    }
     let modelName;
-    if (s.modelName !== undefined) {
-        if (typeof s.modelName !== "string")
+    if (modelNameRaw !== undefined) {
+        if (typeof modelNameRaw !== "string")
             throw new WorkflowScriptError("agent(spec): `modelName` must be a string (a model NAME, never a Model object)");
-        modelName = s.modelName;
+        modelName = modelNameRaw;
     }
-    return { safe, modelName };
+    return { safe, modelName, stripped };
 }
 function clampResourceLimits(safe, base, caps) {
     const trustedCandidates = [
@@ -172,8 +307,10 @@ function clampResourceLimits(safe, base, caps) {
         safe.limits = rebuilt;
     return notes;
 }
-export function buildGovernedChildSpec(scriptSpec, baseline, models, caps, onResourceClamp) {
-    const { safe, modelName } = pickWhitelist(scriptSpec);
+export function buildGovernedChildSpec(scriptSpec, baseline, models, caps, onResourceClamp, onNotice) {
+    const { safe, modelName, stripped } = pickWhitelist(scriptSpec);
+    if (stripped.total > 0)
+        emitStrippedKeysNotice(stripped, onNotice);
     if (modelName !== undefined) {
         safe.model = resolveModelName(modelName, baseline.workflowModelAllowlist, models);
     }

package/dist/orchestration/workflow-primitives.d.ts

@@ -22,6 +22,11 @@ export interface WorkflowGovernance {
     baseline: WorkflowGovernanceBaseline;
     models?: Record<string, Model>;
     caps?: WorkflowChildCaps;
+    /** The deployment's structured notice sink (`RunnerDeps.onNotice`), threaded here because the governed
+     *  build is the only place that can report which spec fields did NOT reach the child (see
+     *  `buildGovernedChildSpec`'s `onNotice` param). Only meaningful in governed mode — the trusted-dev lane
+     *  strips nothing. Absent ⇒ the notice falls back to `console.warn`. */
+    onNotice?: (n: import("../core/types.js").EngineNotice) => void;
 }
 /**
  * Build the flat {@link WorkflowPrimitives} a {@link WorkflowScriptRunner} runs the script against. The

package/dist/orchestration/workflow-primitives.js

@@ -29,7 +29,7 @@ export function buildWorkflowPrimitives(ctx, governance, onAgentSpawn, parentThi
         const agentOpts = safeAgentOptions(opts);
         const effectiveBaseline = (b) => agentOpts.isolation === "worktree" && b.worktreeBase !== undefined ? { ...b, base: { ...b.base, ...b.worktreeBase } } : b;
         const childSpec = governance
-            ? buildGovernedChildSpec(spec, effectiveBaseline(governance.baseline), governance.models, governance.caps, (notes) => ctx.log(formatResourceClampNote(notes)))
+            ? buildGovernedChildSpec(spec, effectiveBaseline(governance.baseline), governance.models, governance.caps, (notes) => ctx.log(formatResourceClampNote(notes)), governance.onNotice)
             : { ...spec };
         if (childSpec.thinking === undefined && parentThinking) {
             const inherited = parentThinking();

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -172,8 +172,32 @@ export interface CompoundReadonlyVerdict {
      *
      * `cd` is the one exception, and it fails closed: a glob there cannot be expanded into the single
      * directory the compound face must track as the new working directory, so it demotes (see {@link reason}).
+     *
+     * ALSO carries the {@link recursiveReadPaths} entries (a subset): both families are operands whose
+     * real read set is not in the command text, and the consumer contract above ("non-empty ⇒ ask, or
+     * resolve yourself") is stated over this one field so an auto-allow gate cannot honour one family
+     * and miss the other.
      */
     undecidedPaths?: readonly string[];
+    /**
+     * Operands of a RECURSIVE/EXPANDING read form (`grep -r`, `ls -R`, `du`, … — see
+     * {@link RECURSIVE_READ_FORMS}) judged with a {@link BashReadonlyRootBoundary.denyMatch} seat wired.
+     * The deny judge sees only the operand's own resolved spelling, but a recursive verb reads the
+     * operand's whole SUBTREE — `grep -r x /home/user` touches `/home/user/.ssh/*` while the judged
+     * spelling `/home/user` matches no deny pattern. The traversal's reach set is therefore not covered
+     * by the lexical check at all, and with zero I/O "provably not a directory" does not exist — so
+     * every such operand is UNDECIDED (no directory guessing, no bounded pre-check: both would be a
+     * false "resolved, inside" of exactly the kind {@link undecidedPaths} exists to prevent).
+     *
+     * Subset of {@link undecidedPaths} (same consumer contract: ask, never auto-allow); carried
+     * separately so a consumer minting prose can name the recursive-reach cause rather than the glob
+     * one. Minted ONLY when `denyMatch` is wired: without a deny judge there is nothing the traversal
+     * bypasses — the containment half already judges the operand itself, and its lexical residuals are
+     * recorded on {@link checkedPaths}. The `bash_readonly` face never wires `denyMatch` (v1 ruling,
+     * see that seat's note), so this field never appears there and its expand-and-verify execution
+     * path is unchanged.
+     */
+    recursiveReadPaths?: readonly string[];
 }
 /**
  * RB-412 — the single minting point for the out-of-root-read approval option text, so a gate rendering
@@ -224,10 +248,14 @@ export declare function classifyCompoundReadonlyDetailed(command: string, allow:
 export declare function classifySimpleCommandReadBoundary(command: string, boundary: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
 /**
  * design/154 — compound read-only classification, reason-only face. Returns the demotion reason, or
- * undefined when the command classifies read-only. RB-412 added the optional `boundary`: with it, an
- * allowlisted reader whose path arguments leave the allowed directories is demoted too (use
- * {@link classifyCompoundReadonlyDetailed} when the caller wants to know that WHY, e.g. to offer the
- * narrow "allow reading from <dir>" approval); without it the verdict is exactly what it always was.
+ * undefined when the command classifies read-only. ⚠️ `undefined` is NOT "safe to auto-execute":
+ * the detailed verdict may still carry `undecidedPaths` (operands whose unexpanded spelling — a
+ * glob — is what got checked), and this face discards that field. An auto-allow decision must read
+ * {@link classifyCompoundReadonlyDetailed} and treat a non-empty `undecidedPaths` as ask — the
+ * engine's own probe does exactly that (fs-bash.ts). RB-412 added the optional `boundary`: with it,
+ * an allowlisted reader whose path arguments leave the allowed directories is demoted too (use the
+ * detailed face when the caller wants to know WHY, e.g. to offer the narrow "allow reading from
+ * <dir>" approval); without it the verdict is exactly what it always was.
  */
 export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;
 /**

package/dist/tools/fs/bash-readonly-classifier.js

@@ -284,6 +284,90 @@ function takesSeparatedValue(name, tok) {
     }
     return false;
 }
+const RECURSIVE_READ_FORMS = {
+    grep: {
+        shortLetters: "rR",
+        valueOwners: "efmABCD",
+        longNames: ["recursive", "dereference-recursive"],
+        enumOptions: [{ shortLetter: "d", longName: "directories", recursiveValue: "recurse" }],
+        dashIsStdin: true,
+    },
+    ls: { shortLetters: "R", longNames: ["recursive"] },
+    du: { always: true },
+    find: { always: true },
+    rg: { always: true, dashIsStdin: true },
+    tree: { always: true },
+    ag: { always: true, dashIsStdin: true },
+    ack: { always: true, dashIsStdin: true },
+    tar: { shortLetters: "cru", valueOwners: "fCTXbg", longNames: ["create", "append", "update"], bundledModeLetters: "cru", dashIsStdin: true },
+    diff: { shortLetters: "r", valueOwners: "UCWISFXx", longNames: ["recursive"], dashIsStdin: true },
+};
+function segmentSelectsRecursiveRead(name, args) {
+    const model = RECURSIVE_READ_FORMS[name];
+    if (model === undefined)
+        return false;
+    if (model.always === true)
+        return true;
+    if (model.bundledModeLetters !== undefined) {
+        const first = args.find((t) => t.length > 0);
+        if (first !== undefined && !first.startsWith("-") && /^[A-Za-z]+$/.test(first) && [...first].some((ch) => model.bundledModeLetters.includes(ch))) {
+            return true;
+        }
+    }
+    let endOfOptions = false;
+    for (let k = 0; k < args.length; k++) {
+        const t = args[k];
+        if (endOfOptions)
+            continue;
+        if (t === "--") {
+            const prev = k > 0 ? args[k - 1] : undefined;
+            const prevMayOwnValue = prev !== undefined && prev.startsWith("--") && prev.length > 2 && !prev.includes("=");
+            if (!prevMayOwnValue)
+                endOfOptions = true;
+            continue;
+        }
+        if (t.startsWith("--")) {
+            const long = longOptionNameOf(t);
+            if (long === undefined)
+                continue;
+            if (model.longNames?.some((full) => isLongOptionAbbrevOf(long, full)) === true)
+                return true;
+            for (const en of model.enumOptions ?? []) {
+                if (en.longName === undefined || !isLongOptionAbbrevOf(long, en.longName))
+                    continue;
+                const eq = t.indexOf("=");
+                const v = eq >= 0 ? t.slice(eq + 1) : args[k + 1];
+                if (v !== undefined && v.length > 0 && en.recursiveValue.startsWith(v.toLowerCase()))
+                    return true;
+            }
+            continue;
+        }
+        if (!t.startsWith("-") || t === "-")
+            continue;
+        for (let i = 1; i < t.length; i++) {
+            const ch = t[i];
+            if (model.shortLetters?.includes(ch) === true)
+                return true;
+            const en = (model.enumOptions ?? []).find((e) => e.shortLetter === ch);
+            if (en !== undefined) {
+                const v = i === t.length - 1 ? args[k + 1] : t.slice(i + 1);
+                if (v !== undefined && v.length > 0 && en.recursiveValue.startsWith(v.toLowerCase()))
+                    return true;
+                if (i === t.length - 1)
+                    k++;
+                break;
+            }
+            if (model.valueOwners?.includes(ch) === true) {
+                if (i === t.length - 1)
+                    k++;
+                break;
+            }
+            if (!/[A-Za-z0-9]/.test(ch))
+                break;
+        }
+    }
+    return false;
+}
 function isGrepFileStdinLongOption(tok) {
     const eq = tok.indexOf("=");
     if (eq < 0 || tok.slice(eq + 1) !== "-")
@@ -327,6 +411,7 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
     const findings = [];
     const candidates = [];
     const bareWordOperands = [];
+    const positionalOperands = [];
     const argGlobs = (k) => {
         const raw = tokens.raw[k + 1];
         return raw !== undefined && hasUnquotedGlobMetachar(raw);
@@ -356,31 +441,47 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
         candidates.push({ text: target, globbed: false });
     }
     else {
-        const patternSuppliedByFlag = name === "grep" && args.some(isGrepPatternFlagToken);
+        const eoo = args.indexOf("--");
+        const patternSuppliedByFlag = name === "grep" && (eoo === -1 ? args : args.slice(0, eoo)).some(isGrepPatternFlagToken);
         let sawOperand = false;
+        let endOfOptions = false;
         for (let k = 0; k < args.length; k++) {
             const t = args[k];
-            if (name === "cut" && (t === "-d" || t === "--delimiter" || t === "--output-delimiter")) {
-                k++;
-                continue;
-            }
-            if (name === "cut" && (/^-d./.test(t) || isCutDelimiterPayloadLongOption(t)))
-                continue;
-            if (name === "grep" && (grepClusterValueOwner(t) === "e" || isGrepPatternPayloadLongOption(t)))
-                continue;
-            if (t.startsWith("-") && t !== "-") {
-                for (const payload of attachedOptionPayloads(t)) {
-                    if (isAbsolutePathForm(payload) || isPathShapedToken(payload))
-                        candidates.push({ text: payload, globbed: argGlobs(k) });
+            if (!endOfOptions) {
+                if (t === "--") {
+                    endOfOptions = true;
+                    continue;
+                }
+                if (name === "cut" && (t === "-d" || t === "--delimiter" || t === "--output-delimiter")) {
+                    k++;
+                    continue;
+                }
+                if (name === "cut" && (/^-d./.test(t) || isCutDelimiterPayloadLongOption(t)))
+                    continue;
+                if (name === "grep" && (grepClusterValueOwner(t) === "e" || isGrepPatternPayloadLongOption(t)))
+                    continue;
+                if (t.startsWith("-") && t !== "-") {
+                    for (const payload of attachedOptionPayloads(t)) {
+                        if (isAbsolutePathForm(payload) || isPathShapedToken(payload))
+                            candidates.push({ text: payload, globbed: argGlobs(k) });
+                    }
+                    continue;
                 }
-                continue;
             }
             const isGrepPatternSlot = name === "grep" && !patternSuppliedByFlag && !sawOperand;
             sawOperand = true;
-            if (t === "-")
+            if (t === "-") {
+                if (isGrepPatternSlot)
+                    continue;
+                const m = RECURSIVE_READ_FORMS[name];
+                if (m === undefined || m.dashIsStdin === true)
+                    continue;
+                positionalOperands.push(t);
                 continue;
+            }
             if (isGrepPatternSlot)
                 continue;
+            positionalOperands.push(t);
             if (isPathShapedToken(t))
                 candidates.push({ text: t, globbed: argGlobs(k) });
             else
@@ -416,6 +517,13 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
         if (!globbed && withinAnyRoot(boundary.roots, resolved))
             findings.push({ kind: "inside", path: resolved });
     }
+    if (boundary.denyMatch !== undefined && segmentSelectsRecursiveRead(name, args)) {
+        const roots = positionalOperands.length > 0 ? positionalOperands : ["."];
+        for (const operand of roots) {
+            const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], operand, boundary.homeDir);
+            findings.push({ kind: "recursive", path: resolved ?? operand });
+        }
+    }
     return findings;
 }
 export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
@@ -584,6 +692,7 @@ function evaluateReadBoundary(foldedSegments, boundary) {
     const outside = [];
     const inside = [];
     const undecided = [];
+    const recursive = [];
     for (const toks of foldedSegments) {
         for (const finding of collectSegmentBoundaryFindings(toks, boundary)) {
             if (finding.kind === "unresolvable")
@@ -604,6 +713,11 @@ function evaluateReadBoundary(foldedSegments, boundary) {
                     undecided.push(finding.path);
                 continue;
             }
+            if (finding.kind === "recursive") {
+                if (!recursive.includes(finding.path))
+                    recursive.push(finding.path);
+                continue;
+            }
             if (boundary.face === "open") {
                 if (!inside.includes(finding.path))
                     inside.push(finding.path);
@@ -613,7 +727,11 @@ function evaluateReadBoundary(foldedSegments, boundary) {
                 outside.push(finding);
         }
     }
-    const undecidedField = undecided.length > 0 ? { undecidedPaths: undecided } : {};
+    const undecidedAll = [...undecided, ...recursive.filter((p) => !undecided.includes(p))];
+    const undecidedField = {
+        ...(undecidedAll.length > 0 ? { undecidedPaths: undecidedAll } : {}),
+        ...(recursive.length > 0 ? { recursiveReadPaths: recursive } : {}),
+    };
     if (outside.length === 0)
         return inside.length > 0 ? { checkedPaths: inside, ...undecidedField } : { ...undecidedField };
     const paths = outside.map((o) => `"${o.path}"`).join(", ");
@@ -724,6 +842,9 @@ export function classifyBoundedReadonlyPollLoop(command, allow, boundary) {
     const verdict = classifyCompoundReadonlyDetailed(readSegments.join("; "), allow, boundary);
     if (verdict.reason !== undefined)
         return verdict.reason;
+    if (verdict.recursiveReadPaths !== undefined) {
+        return `the loop body reads recursively from ${verdict.recursiveReadPaths.join(", ")} — the traversal's reach is not covered by this lexical check, so it is not auto-allowed`;
+    }
     if (verdict.undecidedPaths !== undefined) {
         return `the loop body carries an unexpanded glob (${verdict.undecidedPaths.join(", ")}) — what a REPEATED read touches is decided at run time, so it is not auto-allowed`;
     }

package/dist/tools/fs/read-deny.d.ts

@@ -20,6 +20,11 @@ export interface NormalizedReadDenyEntry {
 /** A deny verdict: which entry's pattern matched. */
 export interface ReadDenyHit {
     pattern: string;
+    /** The view string the pattern actually matched (set by {@link CompiledReadDeny.matchTarget}: the
+     *  canonical key, or the lexical view when only the SPELLING matched). Disclosure must cite the
+     *  matched view — under a symlink/case alias the two strings differ, and naming the other one
+     *  sends the reader chasing a path the pattern does not match. */
+    matchedView?: string;
 }
 /** One compiled ripgrep glob flag for the traversal legs (`--iglob` = case-insensitive entry). */
 export interface ReadDenyRgGlob {

package/dist/tools/fs/read-deny.js

@@ -143,7 +143,15 @@ export function compileReadDeny(additions = [], layer = "additions") {
         entries: normalized,
         matchPath,
         matchTarget(canonicalKey, lexicalView) {
-            return matchPath(canonicalKey) ?? (lexicalView !== undefined ? matchPath(lexicalView) : null);
+            const canonical = matchPath(canonicalKey);
+            if (canonical !== null)
+                return { ...canonical, matchedView: canonicalKey };
+            if (lexicalView !== undefined) {
+                const lexical = matchPath(lexicalView);
+                if (lexical !== null)
+                    return { ...lexical, matchedView: lexicalView };
+            }
+            return null;
         },
         rgExclusionGlobs,
         rgProbeGlobs,

package/dist/tools/fs/read-face.d.ts

@@ -2,6 +2,12 @@
  *  `"open"` = the containment step is skipped (canonicalization, deny set, UNC out-of-set refusal
  *  and the type gates all still run). */
 export type ReadFace = "open" | "roots";
+/** Loud value gate (#123): a `readFace` seat carries exactly "open" | "roots" — anything else
+ *  (case variants, truthy garbage) refuses at wiring time, never folds to a default. Exported
+ *  module-internally (not on the package surface) so prepare's unconditional config-guard leg can
+ *  screen the seats on runs that never mount hands — the resolver only runs beside a mount, and a
+ *  garbage value must not become silently legal on the hands-less path (5.30 re-review). */
+export declare function assertReadFaceValue(v: unknown, seat: string): ReadFace | undefined;
 /** Inputs to {@link resolveReadFace} — all structural/declaration facts, never permission modes
  *  (a deliberate axis separation: this shape carries facts, not verdicts). */
 export interface ReadFaceInputs {

package/dist/tools/fs/read-face.js

@@ -1,4 +1,4 @@
-function assertReadFaceValue(v, seat) {
+export function assertReadFaceValue(v, seat) {
     if (v === undefined)
         return undefined;
     if (v === "open" || v === "roots")

package/dist/tools/fs/safety.d.ts

@@ -270,6 +270,7 @@ export declare function lexicalViewOf(spelled: string, base: string): string;
 export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRootsCanonical?: readonly string[], exactFileReadExemption?: (canonicalKey: string) => boolean, readDeny?: {
     matchTarget(canonicalKey: string, lexicalView?: string): {
         pattern: string;
+        matchedView?: string;
     } | null;
 }, readFace?: "open" | "roots"): Promise<{
     ok: true;

package/dist/tools/fs/safety.js

@@ -49,7 +49,7 @@ const PROC_SENSITIVE_SUFFIXES = ["/environ", "/cmdline", "/auxv", "/maps", "/mem
 function isProcSensitiveFile(key) {
     return key.startsWith("/proc/") && PROC_SENSITIVE_SUFFIXES.some((suf) => key.endsWith(suf));
 }
-const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.[^\\/]*)?$/i;
+const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[0-9¹²³]|LPT[0-9¹²³]|CONIN\$|CONOUT\$)(\.[^\\/]*)?$/i;
 export function isWinFormPath(p) {
     return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\") || (!p.startsWith("/") && p.includes("\\"));
 }
@@ -273,10 +273,21 @@ function stripWin32ExtendedPrefix(p) {
     if (!p.startsWith("\\\\?\\"))
         return p;
     const rest = p.slice(4);
-    const unc = /^UNC[\\/]/i.exec(rest);
-    if (unc)
-        return "\\\\" + rest.slice(unc[0].length);
-    return rest;
+    const unc = /^UNC\\/i.exec(rest);
+    const body = unc !== null ? rest.slice(unc[0].length) : /^[A-Za-z]:\\/.test(rest) ? rest.slice(3) : undefined;
+    if (body === undefined)
+        return p;
+    if (body !== "") {
+        for (const seg of body.split("\\")) {
+            if (seg === "" || seg === "." || seg === "..")
+                return p;
+            if (seg.endsWith(".") || seg.endsWith(" ") || seg.includes("/"))
+                return p;
+            if (WIN_RESERVED_RE.test(seg))
+                return p;
+        }
+    }
+    return unc ? "\\\\" + rest.slice(unc[0].length) : rest;
 }
 function foldUncLexically(p) {
     const body = p.slice(2);
@@ -295,7 +306,8 @@ function foldUncLexically(p) {
                 out.pop();
             continue;
         }
-        out.push(seg);
+        const stripped = seg.replace(/[. ]+$/, "");
+        out.push(stripped.length > 0 ? stripped : seg);
     }
     const anchor = `\\\\${host}${share !== undefined ? `\\${share}` : ""}`;
     return { key: out.length > 0 ? `${anchor}\\${out.join("\\")}` : anchor, climbedAboveShare: climbed };
@@ -329,11 +341,15 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
     if (readDeny !== undefined) {
         const hit = readDeny.matchTarget(key, lexicalViewOf(path, baseCwd ?? rootCanonical));
         if (hit !== null) {
+            const lexicalHit = hit.matchedView !== undefined && hit.matchedView !== key;
+            const judged = lexicalHit
+                ? `the requested path's spelling ("${hit.matchedView}") matches`
+                : `the target matches`;
             return {
                 ok: false,
                 violation: {
                     code: "read_path_denied",
-                    message: `reading "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}is refused: the target matches the sensitive-path read deny list (pattern "${hit.pattern}"). This list guards credential-class paths and applies regardless of the containment roots.`,
+                    message: `reading "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}is refused: ${judged} the sensitive-path read deny list (pattern "${hit.pattern}"). This list guards credential-class paths and applies regardless of the containment roots.`,
                     target: key,
                     pattern: hit.pattern,
                 },
@@ -373,6 +389,9 @@ export async function canonicalizeTarget(env, path, signal, baseCwd) {
         return { ok: false, message: `path "${path}" is a Win32 device-namespace path (\\\\.\\ names a raw device object, not a file); refused.` };
     }
     const unprefixed = stripWin32ExtendedPrefix(path);
+    if (unprefixed.startsWith("\\\\?\\")) {
+        return { ok: false, message: `path "${path}" is a Win32 extended-length namespace path with no DOS-path equivalent (only \\\\?\\<drive>: and \\\\?\\UNC\\ forms name files); refused.` };
+    }
     if (isUncPath(unprefixed) && isWinFormPath(unprefixed)) {
         const folded = foldUncLexically(unprefixed);
         if (folded.climbedAboveShare) {

package/dist/tools/fs/search.js

@@ -807,7 +807,8 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
     if (denyOut !== undefined && walked.denyPruned > 0) {
         denyOut.withheld = { kind: "pruned_count", count: walked.denyPruned, patterns: walked.denyPatterns };
     }
-    let caveat = walkCaveat(walked, true) + denyWithheldNote(walked);
+    let honestyCaveat = walkCaveat(walked, true);
+    const denyNote = denyWithheldNote(walked);
     let files = walked.files;
     files.sort();
     const cap = p.head_limit === 0 ? Infinity : Math.max(1, Math.floor(p.head_limit ?? GREP_DEFAULT_CAP));
@@ -962,11 +963,12 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
         if (multilineSkippedFiles > 0)
             extra.push(`${multilineSkippedFiles} file(s) skipped by multiline matching (content over ${longLineLimit} chars; the pattern's worst-case matching cost grows superlinearly with input length on the fallback engine)`);
         if (extra.length > 0) {
-            caveat = caveat.length > 0
-                ? caveat.replace(/\]$/, `; ${extra.join("; ")}]`)
+            honestyCaveat = honestyCaveat.length > 0
+                ? honestyCaveat.replace(/\]$/, `; ${extra.join("; ")}]`)
                 : `\n…[results may be incomplete: ${extra.join("; ")}]`;
         }
     }
+    const caveat = honestyCaveat + denyNote;
     const paged = (arr) => (off > 0 ? arr.slice(off, off + cap) : arr);
     const offNote = off > 0 ? `\n[offset ${off}]` : "";
     if (mode === "files_with_matches") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.30.0",
+  "version": "5.31.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",