@sema-agent/core 5.28.0 → 5.30.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # Changelog
 
+## 5.30.0 — 2026-08-13
+
+No API-BREAKING changes (exports grow only: `resolveReadFace`, `ReadFace`, `ReadFaceInputs`,
+`READ_FACE_DEFAULT_DENY_ENTRIES`, `compileReadDeny`, `ReadDenyEntry`, `ReadDenyMatcher`,
+`NormalizedReadDenyEntry`; `TaskSpec`/`RunnerDeps`/`HandsToolkitOptions` gain `readFace`/
+`readDenyPatterns`). Narrowings are tighten-direction and named below.
+
+### Added
+
+- **A read-face containment knob (`readFace: "open" | "roots"`, default `"roots"` — byte-compatible
+  with prior behavior).** `TaskSpec`/`RunnerDeps`/`HandsToolkitOptions` each gain the seat; task-layer
+  may only tighten under governance, deployment-layer sets the default. Beside a read-only (verifier)
+  mount, a task-seat `"open"` is a genuine contradiction and refuses loudly; a deployment-seat
+  `"open"` there silently clamps to `"roots"` (a deployment default cannot override a load-bearing
+  containment wall). Every workflow/subagent/SendMessage delegation lane inherits the resolved face
+  tighten-only (stricter-wins), including `run_workflow`'s script-spawned children, which previously
+  did not inherit it at all. Checkpoint schema bumps to v9 (`FACE_CHECKPOINT_VERSION`) to carry the
+  resolved face across suspend/resume; an absent v9 section on an older checkpoint row is the default
+  posture (roots) — no existing row's behavior changes.
+- **A built-in sensitive-path READ deny set**, exported as `READ_FACE_DEFAULT_DENY_ENTRIES` (SSH
+  keys, cloud/VCS credential files, browser profile directories, crypto wallet files, shell history,
+  and similar). Enforced under BOTH containment modes — an `"open"` face does not exempt it — and not
+  shrinkable by any deployment configuration, including the `readFace: "roots"` compatibility seat
+  (the two axes are orthogonal). `.env`-family files are deliberately excluded (write-side guards
+  already cover them). Deployments may extend the table (`readDenyPatterns` on the same three seats,
+  additive-only; `compileReadDeny` lets a host pre-validate additions with the engine's own rules).
+
+### Narrowed (behavior)
+
+- **A UNC-rooted deployment's `..` can no longer walk out of its declared root.** Lexical folding now
+  normalizes `..` segments and Win32 device-namespace prefixes (`\\?\`, `\\.\`) before they reach the
+  containment check; this is a security repair with no compatibility escape hatch (unaffected by any
+  "keep old behavior" knob).
+- **`bashReversibilityProbe` no longer auto-executes an operand with an unexpanded shell glob
+  metacharacter it can't verify against the deny/boundary check.** A command whose read target is
+  undecided at the classifier layer now routes to the ask flow instead of running unattended.
+- **A hands-less resume no longer clones the `realApproval` governance marker onto an ungoverned
+  re-park.** The seed-carry now picks only `{face, denyEntries}`; previously, a worker resuming into a
+  plain (non-governed) ask could inherit a stale `realApproval: true` and permanently wedge the row on
+  its next resume (`real_approval_damaged`, fail-closed by design).
+- **The auto-mode classifier can no longer resolve an ask that originated from an explicit
+  user-written permission rule or a hook-raised promotion.** Both are now excluded from classifier
+  judgment and the persisted-rule-clearing lane, closing two asymmetric gaps against the existing
+  `decisionReason === "hook"` exclusion.
+- **`resolveAsk`'s object-arm reads share one exception boundary.** A throwing getter on `settledBy`/
+  `allow`/`updatedInput` now fails closed (deny) instead of propagating an unhandled rejection; a
+  non-boolean `allow` is refused loudly by name instead of silently rendering as a human refusal.
+
+### Fixed
+
+- `run_workflow`'s durable-store off switch (`spec.checkpointStore === null`) and design/148's
+  center-artifact inheritance (`centerArtifactDigest`/`centerSourceRevision`) were dead reads on the
+  tool's auto-mounted execute context (which never carries them) — neither ever reached a
+  script-spawned child. Both now fall back to a mount-time dependency, matching the tool's other two
+  ctx-or-deps fields.
+- Under `readFace: "open"`, compaction's attachment-reader legs (`readTaskFile`/
+  `normalizeAttachmentPath`) refused files the Read tool had already legitimately served out-of-root;
+  they now thread the resolved face like the structured read tools do.
+- `deleteBySession` joins the `ToolResultStore` contract kit as an honest optional member: when
+  implemented, the four-state semantics (same-session rows deleted, other-session rows untouched,
+  unowned rows counted not deleted, idempotent re-delete) are asserted; when absent, the contract
+  probe reports it by name instead of silently passing.
+
+## 5.29.0 — 2026-08-13
+
+No API-BREAKING changes (exports grow only: `AskOutcome.reason`, `AskRequest.isDelegatedChild`).
+
+### Changed (behavior)
+
+- **A human deny speaks a posture and can carry the decider's words.** The sync approval seat
+  `AskOutcome` gains `reason?: string` on its object arm: attached to a deny, the text reaches the
+  model inside the untrusted fence, bounded to 2048 code points — the same containment and bound as
+  the durable leg's reviewer note (whose four relay sites were previously unbounded and now share
+  the cap). Refusal messages fork on the issuing run's position (`AskRequest.isDelegatedChild`,
+  forks included): a parent-thread run is told to STOP and wait for the user, a delegated child is
+  told to adapt or report; the machine-greppable head line is unchanged. On an allow the seat is
+  never read; a non-string reason on a deny is refused loudly; timeout denials carry the note under
+  a neutral bridge. NOTE: the posture is model-facing text — making a parent-thread denial abort the
+  in-flight batch is registered follow-up work.
+- **`worktreeDir` never names a non-host path.** A remote isolated agent's sandbox cwd is no longer
+  recorded (`ResolvedWorkspace` gains a required `remote` key; absence on the record now means
+  "shared tree OR remote sandbox"), and a workspace observation is authoritative replacement state —
+  a local→remote retry clears the stale host path.
+- **Session freshness is judged by conversation content, not branch entries.** A pre-minted
+  sessionId or a host-pre-seeded marker (naming the chat, recording a model pick before the first
+  turn) no longer stamps `legacy_migration` on a brand-new session's first epoch pin — and no longer
+  silently costs such a session its published center prompt (the adoption arm shared the same
+  refuted entry-count proxy; all three freshness sites now share one predicate).
+- **The ask-question tool teaches previews.** The tool description carries the Preview feature block
+  (CC markdown variant, verbatim), so the preview card form — the only question form whose answer
+  carries user notes — is reachable.
+- The resident execution-environment prompt line about denied calls no longer instructs a blanket
+  "adjust and continue" — it defers to the denial message's own guidance (prompt golden re-frozen).
+
 ## 5.28.0 — 2026-08-12
 
 No API-BREAKING changes (exports grow only). Narrowings are tighten-direction and named below.
@@ -35,9 +129,11 @@ No API-BREAKING changes (exports grow only). Narrowings are tighten-direction an
 
 ### Added
 
-- `onNotice` structured notice seat (first two families: bash timeout, MATERIALIZE) — absent keeps
-  the `console.warn` text verbatim; a present non-function seat is announced once and falls back
-  loudly instead of silencing both channels.
+- `onNotice` structured notice seat (three families: `config.env_timeout_discarded`,
+  `config.materialize_env_discarded`, `tool_result.offload_put_failed` — this entry originally said
+  "first two families"; corrected 2026-08-12, the third family shipped in the same release) — absent
+  keeps the `console.warn` text verbatim; a present non-function seat is announced once and falls
+  back loudly instead of silencing both channels.
 - `tool_end.errorCode` now reads both discriminator spellings — `details.code` first (string), then
   `details.errorKind` — so loop-thrown error frames are classifiable; `code` wins when both exist.
 - `ToolResultStore.deleteBySession?` (optional member; File + in-memory implementations, not on the

package/dist/agents/cascade.d.ts

@@ -9,7 +9,7 @@ import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
  * APPLICABILITY: cascade only helps when the gate is **decidable** (a schema check, a verifier model, a
  * concrete assertion). Open-ended "completeness" tasks (find every bug, writing quality) have no oracle —
  * the gate keeps passing the first plausible cheap answer and escalation idles. Those want breadth /
- * adversarial debate (a `team`), not a depth ladder.
+ * falsification-style debate (a `team`), not a depth ladder.
  *
  * Cost note (design/27 §2): each rung is an independent COLD `runTask` — every escalation repays the
  * full input cost. Cascade wins when (a) the cheap rung usually passes and (b) the prompt isn't so large

package/dist/agents/observer.d.ts

@@ -36,11 +36,11 @@ export type ObserverDigestEvent = {
     type: "turn_ended";
     reason: string;
 };
-/** CC `S$r` — anti-injection: a forged envelope tag inside observed content is defused in place. */
+/** CC `S$r` — anti-injection: a caller-declared envelope tag inside observed content is defused in place. */
 export declare function escapeObserverTags(text: string): string;
 /**
  * CC `zZe` @8339092 — verbatim: `t.replace(new RegExp(`<(?=/?${e}(?:[>\\s/]|$))`, "gi"), "<\\")`.
- * Defuses a forged occurrence of ONE specific tag (opening AND closing) inside content — the second
+ * Defuses a caller-declared occurrence of ONE specific tag (opening AND closing) inside content — the second
  * escape layer CC applies to the DYNAMIC envelope tag (`<{slug}-activity>`) after joining, which the
  * static four-tag `escapeObserverTags` (Scg layer) cannot cover. Deviation from CC (hardening): the
  * tag is regex-escaped before entering the RegExp — CC interpolates raw, safe only because its slugs
@@ -281,7 +281,7 @@ export interface ObserverReportToolOptions {
  * `<${$Bt} from="${Yp(e)}">\n${zZe($Bt, t)}\n</${$Bt}>` with `$Bt = "agent-message"` @1344442.
  * Deviation from CC ($Bt=agent-message → observer-report, sovereign choice): we keep a dedicated
  * frame tag so the observed agent can tell an observer report from generic agent traffic. The
- * escape mechanics are CC-faithful: the frame tag itself is zZe-defused in the body (so a forged
+ * escape mechanics are CC-faithful: the frame tag itself is zZe-defused in the body (so a caller-declared
  * `</observer-report>` cannot break the frame) and the `from=` attribute value is Yp-escaped.
  * Additional hardening beyond CC: the body also rides through the four-event-tag Scg layer.
  *

package/dist/agents/peer-admission.d.ts

@@ -145,7 +145,7 @@ export declare function resetPeerAdmissionRegistryForTests(): void;
  * mounting is structurally single-sourced and survives any downstream projection of the payload).
  * Layered WITH the session-level `SUBAGENT_CONSENT_NOTICE` (prompts/default.ts), not replacing it:
  * that section governs COMMAND authority at session level; this block narrows AUTHORIZATION per
- * message. Placement per leg: OUTSIDE the `<teammate-message>` frame (a forged copy inside the
+ * message. Placement per leg: OUTSIDE the `<teammate-message>` frame (a caller-declared copy inside the
  * sender-controlled body arrives escaped, so position distinguishes the real block); the L3 resume
  * leg carries it in the TRUST-FRAME layer of the peer-resume prompt, never inside the data fence
  * (a load-bearing instruction inside a "this is DATA" fence would demote itself).

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

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

package/dist/agents/subagent.d.ts

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

package/dist/agents/subagent.js

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

package/dist/agents/teacher.d.ts

@@ -13,7 +13,7 @@ import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
  * creative quality — because there is no oracle for *completeness*: the verifier can't know how many bugs
  * the code has or which one was missed, so a student that finds one obvious issue passes the rubric while
  * silently missing others, and the escalation machinery idles (verified in practice: 0 escalations, the
- * verifier becomes pure added cost). Such tasks are solved by **breadth + adversarial debate** (a `team`
+ * verifier becomes pure added cost). Such tasks are solved by **breadth + falsification-style debate** (a `team`
  * council), not by **depth escalation** — the two are orthogonal. See design/12 §六 for the full reasoning.
  */
 /** Default teacher (advisor) system prompt — returns ONLY structured JSON guidance. */

package/dist/agents/teacher.js

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

package/dist/agents/verify.d.ts

@@ -3,7 +3,7 @@ import type { Runner, ResumeTaskConfig } from "../core/runner/runtask.js";
 import type { CheckpointGate, CheckpointToken, ResumeOutcome } from "../core/checkpoint-store.js";
 import type { ModelRef, TaskResult, TaskSpec, ToolSpec } from "../core/types.js";
 /**
- * Verification gate (developer mode, design/28 §4). An **independent adversarial verifier** runs after
+ * Verification gate (developer mode, design/28 §4). An **independent falsification-style verifier** runs after
  * an implementation task and tries to BREAK it — read-only, evidence-required, returning a structured
  * verdict — then the gate loops fix→re-verify until PASS or a round cap.
  *
@@ -20,7 +20,7 @@ import type { ModelRef, TaskResult, TaskSpec, ToolSpec } from "../core/types.js"
  * SKILL.md` closest to the code it covers … and if that file does not exist, create it." So upstream's
  * position is "verification is project-specific; teach the user's repo to describe its own", not "here
  * is a verifier". This primitive is therefore a SUPERSET of what upstream ships in a different
- * direction than the old note implied: a spawned adversarial verifier with a fix loop, bundled. It is
+ * direction than the old note implied: a spawned falsification-style verifier with a fix loop, bundled. It is
  * orthogonal to and composable with the Stop hook (wire the verdict into a stop() hook to make it a
  * hard completion gate).
  *
@@ -31,7 +31,7 @@ import type { ModelRef, TaskResult, TaskSpec, ToolSpec } from "../core/types.js"
  * per task via {@link runWithVerification} (or {@link runDeveloperTask}).
  *
  * Boundary vs teacher mode: teacher's Tier-1 is a *lenient* rubric verifier that triggers escalation to
- * an advisor (stuck/wrong recovery); this is a *strict adversarial* completion gate with a fix loop.
+ * an advisor (stuck/wrong recovery); this is a *strict falsification-style* completion gate with a fix loop.
  * Orthogonal, composable, not merged.
  */
 export declare const VERIFICATION_PROMPT = "You are a verification specialist. Your job is NOT to confirm the implementation works \u2014 it is to try to BREAK it.\n\nYou have two documented failure patterns. First, verification avoidance: faced with a check, you find reasons not to run it \u2014 you read code, narrate what you would test, declare \"PASS,\" and move on. Second, being seduced by the first 80%: a polished result or a passing test suite makes you inclined to pass it, not noticing the edge that crashes, the state that vanishes, the bad input that is unhandled. The first 80% is the easy part. Your entire value is in finding the last 20%.\n\n## Hard boundary \u2014 do not modify the project\nYou are STRICTLY a verifier. Do NOT create, modify, or delete project files; do NOT install packages; do NOT run version-control write operations. Use only the read/probe/execute tools available to you. (If you need a scratch file, use a temp directory, and clean up.)\n\n## Evidence is mandatory\nReading code is NOT verification. Every check must actually run something \u2014 execute the code, hit the endpoint, run the build/tests \u2014 and record the command and its real output. A \"PASS\" with no command output is a skip, not a pass.\n\n## Strategy (adapt to what changed)\n- Build/lib changes: build it, run the full test suite, exercise the public API as a consumer would.\n- Backend/API: start it, call endpoints, check response *shapes* (not just status codes), test error paths.\n- CLI/script: run with representative AND edge inputs (empty, malformed, boundary); check stdout/stderr/exit codes.\n- Bug fix: reproduce the original bug first, verify the fix, then check for regressions and side effects.\n- Refactor (no behavior change): the existing suite must pass unchanged; diff the public surface; same inputs \u2192 same outputs.\nRun the project's own build/tests/linters as a baseline, then apply the type-specific checks. Test results are context, not proof \u2014 the implementer is an LLM too; its tests may be happy-path or circular.\n\n## Adversarial probes (pick the ones that fit)\nBoundary values (0, -1, empty, very long, unicode, max), idempotency (same mutating call twice), orphan operations (ids that don't exist), concurrency (parallel create-if-not-exists). Your verdict must include at least one adversarial probe you actually ran and its result \u2014 even if it was handled correctly.\n\n## Before you FAIL\nCheck you haven't missed why it's actually fine: defensive code elsewhere, intentional behavior documented in comments/specs, or an unfixable external-contract limitation (note that as an observation, not a FAIL). Don't wave away real issues, but don't FAIL on intentional behavior.\n\n## Verdict\nSubmit exactly one verdict via the provided output tool:\n- PASS \u2014 you ran real checks (including \u22651 adversarial probe) and it holds up. Put the commands + observed output in `evidence`.\n- FAIL \u2014 something is broken. Put each concrete problem (with how to reproduce) in `findings`.\n- PARTIAL \u2014 environmental limitation only (no test framework, a tool/server unavailable). Not for \"I'm unsure\": if you can run the check, decide PASS or FAIL. Note what you couldn't verify and why in `findings`.";
@@ -202,7 +202,7 @@ export interface VerificationResult extends TaskResult {
     verification: VerificationOutcome;
 }
 /**
- * Verify an already-**completed** implementation `result` behind the independent adversarial verifier,
+ * Verify an already-**completed** implementation `result` behind the independent falsification-style verifier,
  * looping fix→re-verify until PASS (or a round cap) — **without re-running the implementation**. This is the
  * L3 entry for the L2+L3 composition (design/54 §4): in a fan-out, a worker's module has already been
  * produced, so the orchestrator runs the mechanical L2 gate ({@link runExecGate}), computes the diff, then
@@ -219,7 +219,7 @@ export interface VerificationResult extends TaskResult {
  */
 export declare function verifyCompleted(runner: Runner, result: TaskResult, specBase: ResumeTaskConfig, objective: string, config: VerifyConfig): Promise<VerificationResult>;
 /**
- * Run an implementation task, then gate it behind an independent adversarial verifier, looping
+ * Run an implementation task, then gate it behind an independent falsification-style verifier, looping
  * fix→re-verify until PASS (or a round cap). Returns the implementation result plus the
  * {@link VerificationOutcome}. The caller decides WHEN to use this (explicit opt-in) — it always
  * verifies once invoked. If the impl **suspends on a durable HITL gate**, it is surfaced as
@@ -232,7 +232,7 @@ export declare function runWithVerification(runner: Runner, implSpec: TaskSpec,
  * durable + HITL + verify integration (design/51 P1-b). The mirror of {@link runWithVerification} for the
  * resume path: `runWithVerification` surfaces a HITL suspend as failed-with-token; once the human
  * adjudicates, the caller calls this with the `token` + `outcome`, and it resumes the implementation and —
- * **if it COMPLETES** — runs the identical adversarial verifier + fix loop. If the resumed run suspends
+ * **if it COMPLETES** — runs the identical falsification-style verifier + fix loop. If the resumed run suspends
  * AGAIN (a later durable gate), it is surfaced as failed-with-token (`unverified`) for the caller to resume
  * once more. `objective` is the ORIGINAL task objective (the resume carries none of its own) — the verifier
  * needs it as context; pass the same objective the original `runWithVerification` ran with.

package/dist/agents/verify.js

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

package/dist/bench/metrics.d.ts

@@ -458,7 +458,7 @@ export interface PairedBinaryComparison {
 /**
  * codex B2 — compare two arms' delivered truly-correct as PAIRED binary. Pairs runs by the COMPOSITE
  * `(taskId, seed)` key (codex MAJOR-A: a bare `seed` collides across tasks — the same repeat index
- * recurs per task — so cross-task input would overwrite pairs and poison the McNemar sample);
+ * recurs per task — so cross-task input would overwrite pairs and contaminate the McNemar sample);
  * only rows where BOTH arms delivered (not withheld, both scored) form a pair — a
  * withheld run has no delivered binary to pair (it is scored in the withhold/avoided-loss axis, not
  * here). `mde` is the pre-registered minimum detectable effect (default 0.20 absolute = a 20pp swing).

package/dist/brain/retry.d.ts

@@ -13,7 +13,7 @@
  * - `Retry-After` (delta-seconds or HTTP-date), on any retryable response.
  * - `anthropic-ratelimit-unified-reset` (an absolute epoch-seconds stamp of when the rate-limit window
  *   reopens), read only off a 429 — it is a rate-limit signal.
- * When both are present the larger wins. Both are clamped so a hostile/buggy value
+ * When both are present the larger wins. Both are clamped so a untrusted/buggy value
  * (`Retry-After: 2147483647`, a reset stamp years out) cannot pin the caller for hours.
  */
 /** Parse a `Retry-After` header (delta-seconds or HTTP-date) to ms; undefined if absent/unparseable. */

package/dist/core/arg-summary.d.ts

@@ -52,7 +52,7 @@ export interface SummarizableFinding {
 export declare function summarizeRedactions(findings: readonly SummarizableFinding[]): string;
 /** The optional collector every redaction entry point accepts. `preexistingMarkers` (ANG-11) counts
  *  marker-shaped literals ALREADY present in the input before any pass ran — a nonzero value means the
- *  text arrived pre-redacted or carries forged markers, either way "marker present" is not proof this
+ *  text arrived pre-redacted or carries caller-declared markers, either way "marker present" is not proof this
  *  pipeline ran. Caller-owned: pass `{ findings: [] }` and read it back after the call. */
 export interface RedactionReport {
     findings: RedactionFinding[];

package/dist/core/ask-class.d.ts

@@ -8,7 +8,7 @@
  * self-reported "this ask is sandbox-local" field would be the same trust hole as the
  * `decisionReason:"safety"` self-declaration this codebase already refuses. Instead, BUILT-IN policy
  * factories register their instances here (private WeakMap brand — nothing a deployment policy can
- * forge by shaping its return value), and everything unregistered reads as `unknown`.
+ * self-declare by shaping its return value), and everything unregistered reads as `unknown`.
  *
  * Classes and their dominance (STRICT — merge keeps the strongest; only an all-`sandbox_local` set
  * may auto-admit):
@@ -27,7 +27,7 @@ export type AskClass = "sandbox_local" | "external_authority" | "hook" | "mandat
 /**
  * Brand a built-in policy instance with its ask class (engine factories only — not exported from the
  * package). The `check` binding is LOCKED as a non-writable, non-configurable DATA property before the
- * policy is returned (codex adversarial round 4, HIGH): reading `policy.check` and INVOKING it must
+ * policy is returned (codex falsification-style round 4, HIGH): reading `policy.check` and INVOKING it must
  * name the same callable, atomically. A plain `===` re-read was TOCTOU-able by an accessor — a getter
  * could return the branded function to `policyAskClassOf` and a deployment ask to the gate's
  * invocation. Locking the property makes the callable un-swappable and un-redefinable, so the class

package/dist/core/ask-question.d.ts

@@ -234,7 +234,7 @@ export declare function askQuestionContinuationCard(questionId: string, continua
  * The ONE shape validator for a question batch, shared by the tool body and by the engine's routing lane
  * (which validates BEFORE it puts anything in front of a person — a malformed batch must be refused to
  * the model, not rendered). Returns the model-facing error text, or `undefined` when the batch is well
- * formed. Total: it never throws on hostile field shapes.
+ * formed. Total: it never throws on untrusted field shapes.
  */
 export declare function validateAskQuestions(questions: unknown): string | undefined;
 /** design/173 件3 — engine-side options for the mounted tool (prepare wires them; a deployment

package/dist/core/ask-question.js

@@ -184,7 +184,20 @@ export function createAskUserQuestionTool(onQuestion, source, opts) {
             "Usage notes:\n" +
             '- Users will always be able to select "Other" to provide custom text input\n' +
             "- Use multiSelect: true to allow multiple answers to be selected for a question\n" +
-            '- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label',
+            '- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label' +
+            "\n" +
+            "\n" +
+            "Preview feature:\n" +
+            "Use the optional `preview` field on options when presenting concrete artifacts that users need to visually compare:\n" +
+            "- ASCII mockups of UI layouts or components\n" +
+            "- Code snippets showing different implementations\n" +
+            "- Diagram variations\n" +
+            "- Configuration examples\n" +
+            "\n" +
+            "Preview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. " +
+            "When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on " +
+            "the left and preview on the right. Do not use previews for simple preference questions where labels and " +
+            "descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).",
         parameters: Type.Object({
             questions: Type.Array(Type.Object({
                 question: Type.String({

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

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

package/dist/core/auto-compaction.js

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

package/dist/core/background-shell.d.ts

@@ -6,16 +6,16 @@
  * 这是一个 **env 上的可选能力**(非一种独立 env 类型),所以不 `extends ExecutionEnv` —— 用交叉类型挂到具体实现上,并经
  * {@link hasBackgroundShell} 运行时检测(对齐 remote-env.ts 的 `hasDestroy`/`isRemoteExecutionEnv` 模式,零 vendor 接口改动)。
  *
- * 设计裁定(经 codex + workflow 5-lens 双轨对抗复审收敛,design/103 v2):
+ * 设计裁定(经 codex + workflow 5-lens 双轨证伪式复审收敛,design/103 v2):
  * - **不跨 durable suspend**:后台进程在每条退出路径被 dispose;Runner 必须在 suspendVM **之前** 调
  *   {@link BackgroundShellCapability.disposeBackgroundShells}(detached job 不在 suspendVM 的 in-flight 契约射程内)。
- * - **越权隔离**:`pollBackground`/`killBackground` 的 shellId MUST 被校验为本 env 自己 spawn 过的;非本 env 走 `not_found`。
+ * - **越界隔离**:`pollBackground`/`killBackground` 的 shellId MUST 被校验为本 env 自己 spawn 过的;非本 env 走 `not_found`。
  * - **按-id-可重读**:实现 MUST 保证按 shellId 跨多次独立调用可重复读取累积/增量输出(execStream 的 consume-once 不满足)。
  */
 import type { ExecutionEnv, ExecutionEnvExecOptions, Result } from "../internal/harness-types.js";
 /**
  * 一个 long-running / detached 进程的句柄。**env-local、非 durable、对调用方不透明** —— adapter 内部把它映射到真实进程/
- * provider job,**绝不**把可猜的 raw provider job id 暴露成 shellId(否则跨租户可枚举,design/103 §3.8 越权红线)。
+ * provider job,**绝不**把可猜的 raw provider job id 暴露成 shellId(否则跨租户可枚举,design/103 §3.8 越界红线)。
  */
 export type BackgroundShellId = string & {
     readonly __brand: "BackgroundShellId";
@@ -105,11 +105,11 @@ export interface BackgroundShellCapability {
     /**
      * 读一个后台进程**自上次 poll 以来的新增**输出 + 当前状态(cursor 语义)。退出后仍可读残余 + exitCode,直到被 dispose/reap。
      *
-     * 🔴 越权契约:`shellId` MUST 被校验为**本 env 自己 spawnBackground 返回过**的;非本 env 一律 `not_found`,绝不解析外部 job id。
+     * 🔴 越界契约:`shellId` MUST 被校验为**本 env 自己 spawnBackground 返回过**的;非本 env 一律 `not_found`,绝不解析外部 job id。
      * 🔴 重读契约:实现 MUST 保证「按 shellId 跨多次独立调用可重复读取累积/增量」(remote 的 execStream consume-once 不满足 —— 见 design/103 §5.2 两条路径)。
      */
     pollBackground(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
-    /** 杀一个后台进程(幂等:杀已死的是 no-op,返回 ok)。`shellId` 同 {@link pollBackground} 的越权校验。 */
+    /** 杀一个后台进程(幂等:杀已死的是 no-op,返回 ok)。`shellId` 同 {@link pollBackground} 的越界校验。 */
     killBackground(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
     /**
      * 杀掉并清理**本 env 的所有**后台进程。Runner 在每条退出路径调:finish/abort/throw 在 run-loop tail finally,**suspend/