@sema-agent/core 5.30.0 → 5.32.0

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Changelog
 
+## 5.32.0 — 2026-08-14
+
+No BREAKING changes. One additive disclosure surface; zero resolution-result changes (the read-face
+clamp VERDICT is unchanged since 5.30.0 — only its occurrence is now announced).
+
+### Added
+
+- `config.read_face_deployment_clamped` EngineNotice family (#237): a deployment-wide
+  `readFace: "open"` beside a read-only (verifier) mount clamps to `"roots"` (stricter-wins);
+  the clamp's occurrence is now announced instead of silent. The trigger fires only when the
+  deployment seat was the deciding one — an explicit task-level `"roots"` reaches the same value
+  with or without the mount (no false-cause claim), and the task-seat `"open"` contradiction still
+  refuses loudly. Delivery: the prepare station announces once per `onNotice` SINK (the listener,
+  not the deps object — the Runner rebuilds its deps and `runTask` builds a Runner per call, so a
+  deps-keyed ledger would repeat per task; unwired console arm latches once per process); a
+  library-direct `createHandsToolkit({ readFace: "open", readOnly: true })` announces at toolkit
+  creation through its own `HandsToolkitOptions.onNotice` seat (absent ⇒ the same line via
+  `console.warn`). `detail: { seat, declared, inForce, cause }`. New export:
+  `deploymentReadFaceClampNotice` (the one shared notice builder).
+
+### Fixed
+
+- `HandsToolkitOptions.readFace` JSDoc (ships in the `.d.ts`) stopped promising a loud refusal
+  beside `readOnly: true` — stale since the 96ef89d seat distinction (5.30.0): the deps-shaped
+  seat clamps and announces; the loud refusal belongs to `TaskSpec.readFace`. Wording only, two
+  sites; the runtime behavior was already as now documented.
+
+### Docs
+
+- The recursive-verb table (`RECURSIVE_READ_FORMS`) declares its KNOWN OPEN SET with the standing
+  sweep obligation, and `StripSurvey` states consumer guidance for truncated samples (the two
+  5.31.0 review deductions; wording only).
+
+## 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 +118,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.d.ts

@@ -30,6 +30,8 @@ import type { NestedUsageAccum, RunnerDeps, TaskEvent, TaskLimits, TaskResult, T
 import type { RepairBundle } from "../../agents/repair-loop.js";
 /** Test seam (mirrors `__resetBashTimeoutAnnouncements`): never called by production code. */
 export declare function __resetMaterializeEnvAnnouncements(): void;
+/** Test seam (mirrors `__resetMalformedNoticeSeatAnnouncement`): never called by production code. */
+export declare function __resetReadFaceClampAnnouncement(): void;
 /**
  * design/164 — validate `TaskSpec.limits` at the door and return it unchanged.
  *

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, deploymentReadFaceClampNotice, 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";
@@ -97,6 +97,11 @@ export function __resetMaterializeEnvAnnouncements() {
 function emitMaterializeEnvNotice(onNotice, message, detail) {
     deliverEngineNotice(onNotice, { code: "config.materialize_env_discarded", message, detail });
 }
+const readFaceClampAnnouncedSinks = new WeakSet();
+let readFaceClampConsoleAnnounced = false;
+export function __resetReadFaceClampAnnouncement() {
+    readFaceClampConsoleAnnounced = false;
+}
 const RECONCILE_MAX_RETRIES = 3;
 const DEFAULT_MAX_SUSPENDS = 5;
 const TASK_LIMIT_KEY_DICT = {
@@ -342,6 +347,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 +1395,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 +1660,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);
                 }
@@ -1697,10 +1697,32 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 readOnlyMount: handsReadOnly,
                 orgGoverned: deps.permissionRuleOrg !== undefined,
                 fullShellReachable,
+                onDeploymentClamp: () => {
+                    const sink = deps.onNotice;
+                    if (typeof sink === "function") {
+                        if (readFaceClampAnnouncedSinks.has(sink))
+                            return;
+                        readFaceClampAnnouncedSinks.add(sink);
+                    }
+                    else {
+                        if (readFaceClampConsoleAnnounced)
+                            return;
+                        readFaceClampConsoleAnnounced = true;
+                    }
+                    deliverEngineNotice(sink, deploymentReadFaceClampNotice());
+                },
             });
             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,23 @@ 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.
+     *  - `"config.read_face_deployment_clamped"` (#237) — a deployment-wide `readFace: "open"` is not
+     *    in force beside a read-only (verifier) mount: it clamps to "roots" without throwing
+     *    (stricter-wins; the clamp verdict stands, only its occurrence was undisclosed). Announced
+     *    once per `onNotice` SINK at the prepare station (the verifier lane would otherwise repeat it
+     *    every spawn; the sink — not the deps object — is the unit because the Runner rebuilds its
+     *    deps and `runTask` builds a Runner per call), unwired console arm once per process;
+     *    a library-direct `createHandsToolkit` mount announces at toolkit creation (one per mount,
+     *    through the band-local `HandsToolkitOptions.onNotice` seat, absent ⇒ `console.warn`);
+     *    `detail: { seat, declared, inForce, cause }`. */
     code: string;
     /** The exact human-readable line the unwired build prints via `console.warn` — same words, one text. */
     message: string;

package/dist/index.d.ts

@@ -88,7 +88,7 @@ export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW,
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, compileReadDeny, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, } from "./tools/fs/index.js";
-export { resolveReadFace, type ReadFace, type ReadFaceInputs } from "./tools/fs/index.js";
+export { deploymentReadFaceClampNotice, resolveReadFace, type ReadFace, type ReadFaceInputs } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, type ToolResultDeletionReport, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, type UsageWindow, type UsageWindowStore, type UsageWindowReading, type UsageWindowRecord, type UsageSlot, type UsageBucketRow, } from "./core/usage-window-store.js";

package/dist/index.js

@@ -69,7 +69,7 @@ export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW,
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, compileReadDeny, } from "./tools/fs/index.js";
-export { resolveReadFace } from "./tools/fs/index.js";
+export { deploymentReadFaceClampNotice, resolveReadFace } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, } from "./core/usage-window-store.js";

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;