@sema-agent/core 5.27.0 → 5.29.0

package/dist/core/session-policy-store.d.ts

@@ -16,7 +16,7 @@
  *   can't lose an update (mirrors the checkpoint store's `resolve` OCC).
  * - **structured fields only**: core interprets `toolAllow/Deny`, `allowDirs`, `commandAllow/Deny` (argv[0]
  *   names). A richer rule DSL is the service's/profile's job — core grows no rule interpreter.
- * - **NOT A SANDBOX**: command rules inherit the coarse argv[0] matching (wrappers like `sh -c`/`sudo` bypass);
+ * - **NOT A SANDBOX**: command rules inherit the coarse argv[0] matching (wrappers like `sh -c`/`sudo` circumvention);
  *   the real isolation boundary is the executionEnv, never these rules.
  */
 /** The structured per-session rules. All optional; an absent field imposes no constraint of that kind. */
@@ -86,11 +86,11 @@ export interface SessionPolicyStore {
 /**
  * LEXICAL path containment for the tighten gate. **Must agree with the runtime's view of what a dir IS** (the
  * runtime resolves `..`/`.`/`//` via `canonicalizeTarget`): both args are `posix.normalize`d FIRST so a
- * non-operator can't smuggle a write-confinement OUTSIDE the prior dir by writing `<prior>/../etc` — which is
+ * non-operator can't carry across a write-confinement OUTSIDE the prior dir by writing `<prior>/../etc` — which is
  * lexically "within `<prior>`" by a naive `startsWith` but canonicalizes to `/etc` at run time (the tighten
  * gate must never UNDER-report a loosening).
  *
- * The `..`-resolving `posix.normalize` pass is THIS function's own job (the tighten gate's `..`-smuggling
+ * The `..`-resolving `posix.normalize` pass is THIS function's own job (the tighten gate's `..`-carrying across
  * defense above) and is NOT shared with the runtime's `isWithin` (session-rule-policy.ts), which compares
  * already-canonicalized keys and never resolves `..` itself — the two functions agree on every OTHER input
  * (same win-family fold, same prefix semantics) but diverge on inputs that still carry an unresolved `..`,

package/dist/core/shared-memory/normalize.d.ts

@@ -4,7 +4,7 @@
  *
  * WHY A GATE AT ALL. A TypeScript annotation is a compile-time claim, and a Provider is third-party
  * (BYOM) code that may be plain JavaScript. Every value crossing this seam is therefore treated as
- * foreign data: exotic shapes, throwing getters and hostile metadata all have a defined verdict here,
+ * foreign data: exotic shapes, throwing getters and untrusted metadata all have a defined verdict here,
  * so no "shape outside the rules" can leak an exception into a tool body or a crafted string onto a
  * prompt line.
  *

package/dist/core/skill-tool-specifier.d.ts

@@ -35,7 +35,7 @@
  * admitting a second program smuggled in behind the first.
  *
  * Reusing that parser rather than writing a second tokenizer is deliberate: two argv[0] parsers drift,
- * and the drift shows up as a bypass rather than as a test failure.
+ * and the drift shows up as a circumvention rather than as a test failure.
  *
  * ## Scope: the shell-command lane only
  *

package/dist/core/task-notification.d.ts

@@ -6,7 +6,7 @@ export interface TaskNotificationPayload {
     task_id: string;
     /** design/144 §2: `"external"` is CORE-MINTED ONLY — `TaskStream.notify()` casts it onto every
      *  externally injected event, and the input type ({@link ExternalNotificationInput}) deliberately has
-     *  no `task_type` field, so an outside producer can never wear an internal lane's type (a forged
+     *  no `task_type` field, so an outside producer can never wear an internal lane's type (a caller-declared
      *  "background_bash completed" impersonating a real child). */
     task_type: "background_bash" | "workflow" | "background_agent" | "monitor" | "external";
     toolUseId?: string;
@@ -27,7 +27,7 @@ export interface TaskNotificationPayload {
      *     `cycleSeq`, or — on a tier-3 cross-process revival / a parked resume, which deliberately carry
      *     no retain entry — the durable row's own `seq`. ABSENT only when neither exists (retain OFF on a
      *     store-less spawn, an expired ledger with no durable row, the fork lane): the cycle count is not
-     *     knowable there, and an honest downgrade to the old single-cycle key beats a forged period
+     *     knowable there, and an honest downgrade to the old single-cycle key beats a caller-declared period
      *     number. So `seq` present does NOT imply a retain entry exists.
      *   - `external`: caller-supplied verbatim ({@link ExternalNotificationInput.seq}) — the injector's
      *     own dedup discriminator across same-task_id+status events.

package/dist/core/task-registry-agent.d.ts

@@ -14,14 +14,14 @@ export declare function ensureDurableHeartbeatLane(core: DurableAgentCore): void
  *     re-apply (the real terminal truth must beat a reaper's guess); only a row carrying a
  *     FOREIGN writerId poisons the lane (never clobber another writer). */
 export declare function durableAgentWriteLane(handle: BackgroundAgentTaskHandle, patch: Partial<BackgroundAgentRecord>, clear?: readonly (keyof BackgroundAgentRecord)[]): void;
-/** design/151 S1b — is this row's durable lane ARMED (store wired at registration, not poisoned)?
+/** design/151 S1b — is this row's durable lane ARMED (store wired at registration, not contaminated)?
  *  Observability/test face. ⚠️ NOT the lifecycle-flip key: arming says a row was ATTEMPTED, not
  *  that it EXISTS — release anchors gate on {@link durableAgentRowProbe} (codex r2 F2). */
 export declare function durableAgentArmedLane(core: DurableAgentCore, id: string): boolean;
 /** design/151 S1b (codex r2 F2) — the AWAITABLE lifecycle-flip key. Returns undefined when no
  *  lane was armed; otherwise a probe CLOSURE over the HANDLE (outlives its eviction from the map —
  *  retain-ledger TTL arms fire hours after terminal GC) that flushes the queued writes and answers
- *  whether a durable row actually EXISTS right now (initial put confirmed, not poisoned). A store
+ *  whether a durable row actually EXISTS right now (initial put confirmed, not contaminated). A store
  *  that never accepted the put answers false — the caller then RELEASES the session (pre-151 path)
  *  instead of stranding an unreachable transcript.
  *
@@ -102,13 +102,13 @@ export declare function bindBackgroundAgentSessionLane(core: DurableAgentCore, i
  * per leg at the injector-ready barrier (prepare has succeeded by then, so the verdict exists); a
  * revival cycle overwrites the previous cycle's record with its own, which the admission door
  * guarantees is a subset. Same durable write lane as every other post-registration fact — a
- * store-less registration is a no-op, and a poisoned lane stays poisoned.
+ * store-less registration is a no-op, and a contaminated lane stays contaminated.
  *
  * A DROPPED write is disclosed. This record is the only carrier a narrowing has across a process
  * boundary, so what stands on the row when the write does not land is the PREVIOUS leg's wider
- * verdict — which the next revival then seeds from. Two drop shapes, one message each: a poisoned
+ * verdict — which the next revival then seeds from. Two drop shapes, one message each: a contaminated
  * lane refuses at its front door, and an exhausted flush leaves the value unwritten with the lane
- * still armed. The channel is the same durable-agents warning channel the lane uses for the poison
+ * still armed. The channel is the same durable-agents warning channel the lane uses for the contamination
  * itself (that one says writes stopped; this one says WHICH fact stopped with them). The write
  * remains best-effort: no leg faults because its bookkeeping failed.
  *
@@ -197,7 +197,7 @@ export declare function rollbackParkedClaimLane(core: DurableAgentCore, stores:
  * design/153 §7.2d (件3c, codex 3c H-1) — the CONSUME FLIP, SERIALIZED THROUGH THE DURABLE LANE:
  * the guarded parked→running store CAS runs INSIDE the lane chain (ordered after every seeded
  * write — the session-bind CAS included), so no in-flight lane write can race it, CAS-fail on the
- * flip's rev bump, read the new epoch as foreign, and poison the lane (which would permanently
+ * flip's rev bump, read the new epoch as foreign, and contaminate the lane (which would permanently
  * drop finalize/terminal/re-park writes). On a won CAS the lane record/rev swap happens in the
  * SAME chain step and the live handle adopts (running, arbitration dropped — the token is
  * consumed; `parkClaimId` stays visible until finalize). Returns false when the row moved
@@ -284,7 +284,7 @@ export declare function markRetainedContinuationLane(core: DurableAgentCore, id:
  *  The DURABLE transition is a {@link claimTerminalRowForRevive} claim, awaited BEFORE the in-memory
  *  flip — the two orders are not equivalent: flipping memory first (the pre-arbitration shape, a plain lane
  *  write with no row guard) let a foreign claim win the row while this process kept serving
- *  `running`, and every later write of this cycle then died in the poisoned lane without a trace.
+ *  `running`, and every later write of this cycle then died in the contaminated lane without a trace.
  *  Three lane shapes, three treatments:
  *   - NO lane (store-less registration): the pre-arbitration in-memory-only transition, unchanged — there is
  *     no row, hence no arbitration domain and no competitor;
@@ -293,11 +293,11 @@ export declare function markRetainedContinuationLane(core: DurableAgentCore, id:
  *     the chain (row absent AND the put still unconfirmed after the chain drained), never by the
  *     entry-time flag: a put merely in flight, or one that committed under a failed response, would
  *     otherwise exempt a row that does exist — the split-brain window this claim exists to close;
- *   - POISONED lane (stale-flip ownership transfer / row reaped mid-write / heartbeat re-drive
+ *   - Contaminated lane (stale-flip ownership transfer / row reaped mid-write / heartbeat re-drive
  *     ceiling): the claim runs DIRECTLY through the store — the dead lane's chain is no longer a
  *     serialization point, the rev guard is. Re-arming that lane object in place is what is NOT
  *     done: an in-flight write from it would then see its own writerId on the re-claimed row and
- *     adopt it. It stays poisoned (its record keeps the pre-claim writerId/epoch, so its read-back
+ *     adopt it. It stays contaminated (its record keeps the pre-claim writerId/epoch, so its read-back
  *     answers "foreign" and it stops), and a row that cannot be claimed — gone, or live under
  *     another writer — REFUSES the revive rather than resuming with a durably unreachable row.
  *  A WON claim always hands the row to a FRESH lane for the claimed generation (both paths), for the
@@ -471,6 +471,15 @@ export declare function serveDurableAgentRowLane(row: BackgroundAgentRecord): Un
  *
  * No store configured (a deployment that never wired a `toolResultStore`) ⇒ returns `clipped` UNCHANGED
  * — the legal degrade design/158 §2.2 calls for, byte-identical to pre-S1 behavior.
+ *
+ * Backlog #169 — a FAILING `put` (throwing or rejecting; the store contract admits both dialects) is
+ * NOT fatal to the poll: the clipped text is still served, with {@link AGENT_SPILL_FAILED_NOTE} in
+ * place of the ref disclosure (advertising a ref nobody can read back would be a false promise), and
+ * `handle.spillFailed` latches so later polls of the same cycle repeat the honest note instead of
+ * retrying the write — see the catch below for why latch-not-retry. Same "store failure is never
+ * fatal" posture as the monitor/offload/budget/compaction write sites. A put that settles AFTER a
+ * revive (stale cycle) is generation-guarded: it answers its own caller honestly but never writes
+ * spill state onto the new cycle (see `mintCycle` below).
  */
 export declare function spillClippedAgentResult(handle: BackgroundAgentTaskHandle, full: string, clipped: string, store: ToolResultStore | undefined, sessionId: string | undefined): Promise<string>;
 export declare function pollBackgroundAgentLane(handle: BackgroundAgentTaskHandle, deadline?: number, signal?: AbortSignal, 

package/dist/core/task-registry-agent.js

@@ -981,6 +981,7 @@ export async function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.result = undefined;
     handle.resultFull = undefined;
     handle.spillRef = undefined;
+    handle.spillFailed = undefined;
     handle.error = undefined;
     handle.errorCode = undefined;
     handle.errorRetryable = undefined;
@@ -1226,17 +1227,33 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
         ...(row.status === "failed" ? { isError: true } : {}),
     };
 }
+const AGENT_SPILL_FAILED_NOTE = "\n\n[full output could not be spilled to the offload store (the write failed or went unconfirmed) — no ref is available to read the dropped middle back.]";
 export async function spillClippedAgentResult(handle, full, clipped, store, sessionId) {
     if (clipped === full)
         return clipped;
     if (store === undefined)
         return clipped;
-    if (handle.spillRef === undefined) {
-        const ref = buildToolResultRef(sessionId ?? "no-session", handle.id, `c${handle.reviveCycle ?? 0}`);
-        await store.put(ref, full, sessionId === undefined ? undefined : toolResultProvenanceOf(sessionId, handle.id));
-        handle.spillRef = ref;
+    const disclose = (ref) => `${clipped}\n\n[full output persisted — call ${OFFLOAD_TOOL_NAME} with ref "${ref}" to read it back.]`;
+    if (handle.spillRef !== undefined)
+        return disclose(handle.spillRef);
+    if (handle.spillFailed === true)
+        return `${clipped}${AGENT_SPILL_FAILED_NOTE}`;
+    const mintCycle = handle.reviveCycle ?? 0;
+    const ref = buildToolResultRef(sessionId ?? "no-session", handle.id, `c${mintCycle}`);
+    try {
+        await store.put(ref, full, sessionId === undefined ? undefined : toolResultProvenanceOf(sessionId));
+    }
+    catch {
+        if ((handle.reviveCycle ?? 0) === mintCycle) {
+            if (handle.spillRef !== undefined)
+                return disclose(handle.spillRef);
+            handle.spillFailed = true;
+        }
+        return `${clipped}${AGENT_SPILL_FAILED_NOTE}`;
     }
-    return `${clipped}\n\n[full output persisted — call ${OFFLOAD_TOOL_NAME} with ref "${handle.spillRef}" to read it back.]`;
+    if ((handle.reviveCycle ?? 0) === mintCycle)
+        handle.spillRef = ref;
+    return disclose(ref);
 }
 export async function pollBackgroundAgentLane(handle, deadline, signal, oneShot, store, sessionId) {
     while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
@@ -1256,10 +1273,23 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
             }),
         };
     }
-    const fullResult = handle.result ? (handle.resultFull ?? handle.result) : undefined;
+    const snap = {
+        status: handle.status,
+        result: handle.result,
+        resultIsPartial: handle.resultIsPartial,
+        error: handle.error,
+        errorKind: handle.errorKind,
+        errorCode: handle.errorCode,
+        errorRetryable: handle.errorRetryable,
+        errorRetryAfterMs: handle.errorRetryAfterMs,
+        cycleSeq: handle.cycleSeq,
+        stoppedBy: handle.stoppedBy,
+        completionId: handle.completionId,
+    };
+    const fullResult = snap.result ? (handle.resultFull ?? snap.result) : undefined;
     const resultText = fullResult !== undefined ? await spillClippedAgentResult(handle, fullResult, clipTaskOutput(fullResult, handle.outputFile), store, sessionId) : undefined;
-    const kindClause = handle.status === "failed" && handle.errorKind !== undefined && handle.errorRetryable !== undefined
-        ? ` (error_kind: ${handle.errorKind}, retryable: ${handle.errorRetryable}${handle.errorRetryAfterMs !== undefined ? `, retry_after_ms: ${handle.errorRetryAfterMs}` : ""})`
+    const kindClause = snap.status === "failed" && snap.errorKind !== undefined && snap.errorRetryable !== undefined
+        ? ` (error_kind: ${snap.errorKind}, retryable: ${snap.errorRetryable}${snap.errorRetryAfterMs !== undefined ? `, retry_after_ms: ${snap.errorRetryAfterMs}` : ""})`
         : "";
     const body = running
         ? oneShot === true
@@ -1267,26 +1297,26 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
 This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput({ task_id: "${handle.id}", block: true }). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget.`
             : `status: running
 The agent is still working — you will be notified when it completes.`
-        : `status: ${handle.status}
-${handle.error ? `error: ${handle.error}${kindClause}
-` : ""}${handle.result ? `--- result${handle.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
+        : `status: ${snap.status}
+${snap.error ? `error: ${snap.error}${kindClause}
+` : ""}${snap.result ? `--- result${snap.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
 ${resultText}` : "(no result text)"}`;
     return {
         content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
         details: buildAgentPollDetails({
             taskId: handle.id,
-            status: handle.status,
+            status: snap.status,
             retrievalStatus: retrieval,
-            ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
-            ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
-            ...(handle.error !== undefined ? { error: handle.error } : {}),
-            ...(handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
-            ...(handle.errorRetryable !== undefined ? { errorRetryable: handle.errorRetryable } : {}),
-            ...(handle.errorRetryAfterMs !== undefined ? { errorRetryAfterMs: handle.errorRetryAfterMs } : {}),
-            ...(handle.resultIsPartial === true ? { resultIsPartial: true } : {}),
-            ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+            ...(snap.cycleSeq !== undefined ? { seq: snap.cycleSeq } : {}),
+            ...(snap.stoppedBy !== undefined ? { stoppedBy: snap.stoppedBy } : {}),
+            ...(snap.error !== undefined ? { error: snap.error } : {}),
+            ...(snap.errorCode !== undefined ? { errorCode: snap.errorCode } : {}),
+            ...(snap.errorRetryable !== undefined ? { errorRetryable: snap.errorRetryable } : {}),
+            ...(snap.errorRetryAfterMs !== undefined ? { errorRetryAfterMs: snap.errorRetryAfterMs } : {}),
+            ...(snap.resultIsPartial === true ? { resultIsPartial: true } : {}),
+            ...(snap.completionId !== undefined ? { completionId: snap.completionId } : {}),
         }),
-        ...(handle.status === "failed" ? { isError: true } : {}),
+        ...(snap.status === "failed" ? { isError: true } : {}),
     };
 }
 export async function stopBackgroundAgentLane(core, handle) {

package/dist/core/task-registry-monitor.js

@@ -68,7 +68,7 @@ function spillRolledMonitorChunk(handle, stream, dropped) {
     else
         handle.spillErrSegCount = n + 1;
     try {
-        const provenance = handle.spillSessionId === undefined ? undefined : toolResultProvenanceOf(handle.spillSessionId, handle.id);
+        const provenance = handle.spillSessionId === undefined ? undefined : toolResultProvenanceOf(handle.spillSessionId);
         void Promise.resolve(store.put(ref, dropped, provenance)).catch(() => {
             handle.spillFailed = true;
         });

package/dist/core/task-registry-shared.d.ts

@@ -68,7 +68,7 @@ export interface UnifiedTaskOutput {
  * (`noTask`/`noTaskForStop`/`formatWorkflowRun`/`serveDurableAgentRow`/`pollTask`/`stopTask` and every
  * per-task-kind poll/stop arm). `UnifiedTaskOutput` (the `details` face) has no isError channel of its
  * own — it is a REQUIRED-field wire shape consumed by callers beyond these two tools too, so isError is
- * carried as a sibling on the WRAPPER instead (trap avoidance per the E1 sweep: never smuggle isError
+ * carried as a sibling on the WRAPPER instead (trap avoidance per the E1 sweep: never carry across isError
  * through a narrower helper contract). Optional, absent/false = success — `createTaskOutputTool`/
  * `createTaskStopTool` forward it onto the real `ToolReturn` at the tool boundary. Every internal helper
  * keeps constructing `content`/`details` exactly as before; this only adds a place to say "and this one
@@ -97,8 +97,8 @@ export interface SemaTaskHandle {
 /** P1-3(黑板 [1920]/[1921]/[1924]/[1925]) — mint a cross-channel completion correlation id ONCE per
  *  handle/record, fill-once (first writer wins): every settle/direct-terminal-flip site calls this
  *  instead of writing `completionId` directly, so no matter how many terminal-transition sites a lane
- *  has (settle / TaskStop bypass / backfill), the value is minted exactly once and every later caller
- *  (including an idempotent re-call from a bypass path that already ran) gets back the SAME id. `string`
+ *  has (settle / TaskStop circumvention / backfill), the value is minted exactly once and every later caller
+ *  (including an idempotent re-call from a circumvention path that already ran) gets back the SAME id. `string`
  *  is intentionally loose (any object with an optional `completionId` field) so the same helper serves
  *  both a `RegisteredTaskHandle` and a `WorkflowRun` (orchestration/workflow.ts — a different module,
  *  no shared base type, same fill-once shape). */
@@ -324,6 +324,15 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
      *  eventual spill lands under a DIFFERENT ref rather than colliding with (and being silently refused
      *  by the write-once store under) cycle 1's. */
     spillRef?: string;
+    /** Backlog #169 — the spill `put` for the CURRENT revive cycle threw or rejected. One-time latch,
+     *  scoped to the cycle ({@link import("./task-registry-agent.js").reviveBackgroundAgentLane} clears
+     *  it in lockstep with `spillRef`): later polls serve the clipped text with an honest ref-free loss
+     *  note instead of retrying the write — the ref is minted deterministically, so the known permanent
+     *  failure class (the store's write-once/provenance conflict) would fail identically on every poll,
+     *  each retry a guaranteed-failure round trip to a durable backend. The monitor lane's
+     *  `spillFailed` twin (same degrade discipline, different write shape — that one is fire-and-forget,
+     *  this one is awaited). */
+    spillFailed?: true;
     error?: string;
     /** RB-386② ([2090]) — the machine-readable failure code beside `error`, threaded from the settle
      *  mint point (subagent.ts computes it ONCE from the child's TaskResult.errorCode taxonomy /
@@ -825,7 +834,7 @@ export interface RegisterBackgroundAgentInput extends TaskAccess {
      *  pre-consume window keeps the live face's checkpoint arbitration; the consume flip
      *  {@link TaskRegistry.adoptParkedResume} is the only path to running). Pass the ticket's token
      *  and a stop-arbitration closure alongside. Also licenses replacing an in-process PARKED prior
-     *  handle of the same id (the planned park→resume handoff; lane poisoned like the terminal replace). */
+     *  handle of the same id (the planned park→resume handoff; lane contaminated like the terminal replace). */
     initialStatus?: "parked";
     /** design/153 §7.2d — the parked checkpoint token this parked-born handle waits on. */
     parkedCheckpointToken?: string;

package/dist/core/tool-errors.d.ts

@@ -77,7 +77,7 @@ export declare function formatToolError(error: unknown): string;
  *                   in-presence condition) for that one code, or the errorCode's own doc for every other
  *                   member (`env.lifetime_expired`'s doc says "retrying needs a NEW environment, not a
  *                   smaller budget" — there is no `retryAfterMs` for it, by design: an expiring
- *                   environment has no return time to give). Codex adversarial review (rounds 2 and 4)
+ *                   environment has no return time to give). Codex falsification review (rounds 2 and 4)
  *                   twice suggested a distinct governance/platform class or leaving these `unknown`
  *                   instead — rejected both times: (a) explicit calling-convention direction; (b)
  *                   `WorkerErrorClass` is a small CLOSED public exported union — adding a member is an
@@ -86,7 +86,7 @@ export declare function formatToolError(error: unknown): string;
  *                   terminal codes, not foreign ones); (c) pre-existing precedent (`config.compliance_required`,
  *                   NOT part of this diff) already folds a transient/retryable governance code into `config`.
  *                   `memory.admission_required`/`_denied`/`env.lifetime_expired` are EXACT codes, not broad
- *                   `memory.`/`env.` prefixes — codex adversarial review (A-005.3 follow-up) caught an
+ *                   `memory.`/`env.` prefixes — codex falsification review (A-005.3 follow-up) caught an
  *                   earlier draft folding EVERY `memory.*`/`env.*` code here, which misclassified the
  *                   memory-engine's non-governance incident codes (`memory.secret_detected` et al.,
  *                   explicitly listed as NON-governance in `NON_GOVERNANCE_MEMORY_CODES` — a content-safety

package/dist/core/tool-policy.d.ts

@@ -78,7 +78,8 @@ export interface ToolCallRequest {
  *   - `"org_unavailable"` — an org-governed deployment could not adjudicate against a snapshot, so the
  *     whole decision boundary failed closed (see `ORG_UNAVAILABLE_DECISION_REASON`, the single
  *     spelling this word is minted from). */
-export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier" | "persisted_rule" | "sandbox" | "org_rule" | "org_unavailable";
+declare const DECISION_REASONS: readonly ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable"];
+export type DecisionReason = (typeof DECISION_REASONS)[number];
 /**
  * WHO (or what) ENDED an approval — the machine-readable twin of a settlement's human-readable text,
  * so a consumer tells "a person decided this" from "nobody answered" without prose-matching a sentence.
@@ -109,7 +110,7 @@ export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier"
  * be reported as a person's refusal.
  *
  * ABSENT means this settlement named no source: an older caller that predates the field, or a verdict
- * that settled no wait at all (a policy POSTURE — headless auto-deny, a blanket bypass — where nobody
+ * that settled no wait at all (a policy POSTURE — headless auto-deny, a blanket circumvention — where nobody
  * was ever asked). A consumer MUST NOT read a semantic out of the absence; render the text instead.
  */
 export type ApprovalSettledBy = "human" | "timeout" | "aborted";
@@ -128,7 +129,7 @@ export declare function isApprovalSettledBy(v: unknown): v is ApprovalSettledBy;
  *    stale un-redacted ones.
  *  - `ask` requests human confirmation; with no approver wired it resolves deterministically to deny
  *    (headless auto-deny, see `RunnerDeps.onAsk`). `requiresRealApproval: true` (RB-203 codex review,
- *    confirmed P1) additionally refuses to let a BLANKET `onAsk: "allow"` bypass clear it — that
+ *    confirmed P1) additionally refuses to let a BLANKET `onAsk: "allow"` circumvention clear it — that
  *    configuration is "no approver looked at this at all", indistinguishable from headless, for a rule
  *    whose whole point is that a blanket policy setting must not be the thing that clears it (see
  *    {@link resolveAsk}). A live auto-mode classifier verdict (tried earlier in the gate, if configured)
@@ -336,8 +337,39 @@ export declare function constraintChainDigest(chain: readonly ConstraintChainEnt
  * out-of-contract decision object, so it is not a rewrite this layer is willing to report as audited.
  * (A rewrite from an EARLIER, contract-shaped policy still rides out — {@link combinePolicies} adds it
  * on the deny path per the observer contract.)
+ *
+ * The second arm screens `decisionReason` against the closed set ({@link DecisionReason}): a
+ * deployment-authored `ToolPolicy.check` returning a value outside it would otherwise ride silently
+ * into every consumer that BRANCHES on the word — provenance-keyed exclusions, audit rows, checkpoint
+ * discriminants — each of which would treat the unclassifiable value as "none of the reasons I know",
+ * a meaning the producing policy never chose. Same doctrine as the retired-field arm: out-of-contract
+ * input to the permission face is refused loudly, not passed through as an accidental tenth reason.
+ * An ABSENT `decisionReason` stays legal (it is optional; `undefined` is the typed spelling of
+ * absence), and hook results never reach here with a foreign word — the hook seam stamps its own
+ * (`hooks.ts`) — so this arm's live producers are exactly the deployment policies the tripwire exists
+ * to screen. Unlike the retired-field arm this one reads the property PLAINLY (prototype chain
+ * included), because it answers a different question: the retired arm asks whether the AUTHOR wrote
+ * the old field (own property = authorship), this arm asks what a CONSUMER would read — and every
+ * consumer branches on a plain `d.decisionReason` read, which the prototype can satisfy.
+ *
+ * SCOPE of the carrier check (ruled after three review rounds converged on the same root): it screens
+ * STRUCTURALLY unstable carriers — getters, prototype-supplied values — i.e. shapes an ordinary
+ * deployment can write by accident. It does NOT try to defeat a Proxy whose descriptor trap reports a
+ * data property while its get trap stays stateful: same-process JavaScript has no trust boundary a
+ * function can enforce (an untrusted party who ships such a Proxy can as easily patch this module), so
+ * chasing that shape adds complexity without adding a guarantee. The screen's promise is against
+ * drift and accident, not against a untrusted co-resident.
+ *
+ * `reasonIsNonInput` (the HOOK seam's spelling — merged-code scan, 5.28 window): at that seam the
+ * field is documented as DISCARDED — every mint point downstream unconditionally re-stamps
+ * `decisionReason:"hook"` (fold, deny arm, delegated twin), and the allow path never reads it — so
+ * both reason arms are skipped there: refusing a value that cannot travel would fail-close a call
+ * over a field with no consumer, which inverted the discard contract the stamp exists to enforce.
+ * The retired-`reason` arm still applies (that one is about the MESSAGE channel, which does travel).
  */
-export declare function refuseOutOfContractDecision(d: PermissionResult): PermissionResult;
+export declare function refuseOutOfContractDecision(d: PermissionResult, opts?: {
+    reasonIsNonInput?: boolean;
+}): PermissionResult;
 /** The raw tool-name lists a name-keyed policy was built from (audit feed, see block note above). */
 export interface ToolPolicyNameSets {
     readonly allow?: readonly string[];
@@ -443,14 +475,14 @@ export declare const COARSE_SHELL_TOOLS: string[];
  * design/center §10 — a COARSE allow/deny gate keyed on the LEADING command NAME (`argv[0]`) of a single
  * simple shell command. It reuses the ONE shared simple-command parser
  * ({@link import("../tools/fs/index.js").parseLeadingCommandName}) — it does NOT re-implement argv[0] parsing
- * (a second parser would drift and open a bypass). For a `bash`/`bash_readonly` call it extracts the leading
+ * (a second parser would drift and open a circumvention). For a `bash`/`bash_readonly` call it extracts the leading
  * command name and:
  *  - if the name is in `deny` → `deny` (deny-wins, matching {@link createAllowDenyPolicy}; NOT last-match-wins,
  *    which would fight {@link combinePolicies}'s deny>ask>allow fold);
  *  - else if `allow` is provided and the name is NOT in it → `defaultAction` (`"ask"` default, or `"deny"`);
  *  - else → `allow`.
  * A command the parser cannot reduce to a single bare name (it has shell operators / a path-prefix / a leading
- * env-assignment) is treated by `defaultAction` (fail-toward-gate): such a command is exactly what would bypass
+ * env-assignment) is treated by `defaultAction` (fail-toward-gate): such a command is exactly what would circumvent
  * an argv[0] filter, so it should not silently `allow`. NON-shell tools are out of scope → `allow` (this gate
  * only speaks about shell command names; compose it with other policies for the rest).
  *
@@ -458,7 +490,7 @@ export declare const COARSE_SHELL_TOOLS: string[];
  * injected by the profile/config/deployment.
  *
  * ⚠️ **NOT A SANDBOX — coarse filter / defense-in-depth only.** This matches `argv[0]` NAME and nothing else,
- * so the bypass surface is large and the gate MUST NOT be relied on as containment:
+ * so the circumvention surface is large and the gate MUST NOT be relied on as containment:
  *   - command substitution / subshells (`$(curl …)`, backticks), pipes, redirects, `;`/`&&` chaining — all
  *     rejected as un-parseable here (→ `defaultAction`), so they don't sneak past `allow`, but that is a GATE
  *     not a guarantee of safety;
@@ -542,7 +574,7 @@ export declare function findUnverifiableRecursiveDelete(command: string, safeVar
  *
  * codex review (confirmed P1): the one piece of NEW plumbing this DOES need — `requiresRealApproval: true`
  * (see {@link PermissionResult}'s `ask` doc) — closes a real gap the first cut of this fix missed. A
- * deployment using the documented `onAsk: "allow"` bypass mode (sandbox-is-the-boundary posture, the
+ * deployment using the documented `onAsk: "allow"` circumvention mode (sandbox-is-the-boundary posture, the
  * shape a sandboxed autonomy container runs) would otherwise have this rule's `ask` rubber-stamped by that blanket
  * configuration with NO classifier ever consulted and NO judgment of any kind applied — silently WEAKER
  * than the unconditional deny it replaced, for exactly the deployments that opted into the most permissive
@@ -670,7 +702,7 @@ export interface AskRequest {
     readonly sourceTaskId?: string;
     /** design/153 §1 (RB-39②) — Runner-filled: present (`true`) exactly when the gate raising this ask
      *  belongs to a DELEGATED SUBAGENT (the prepareTask `isSubagent` fact — trusted `internals.parentTaskId`
-     *  presence; a child cannot forge or suppress it, internals never ride a TaskSpec). Undefined ⇒ the
+     *  presence; a child cannot self-declare or suppress it, internals never ride a TaskSpec). Undefined ⇒ the
      *  host / a top-level task. THE explicit "from a background agent" discriminator (replaces presence-
      *  or equality-heuristics on {@link sourceTaskId}). `readonly`, sync-path-only, S1d posture. */
     readonly fromSubagent?: true;
@@ -679,6 +711,20 @@ export interface AskRequest {
      *  (the spawning model chooses names): redact + bound before rendering; never adjudication input.
      *  `readonly`, same posture as {@link fromSubagent}. */
     readonly sourceAgentName?: string;
+    /** Runner-filled: present (`true`) exactly when the issuing run is a **delegated child** — ANY
+     *  spawn leg, FORK INCLUDED (the trusted `RunInternals.isDelegatedChild` fact, set unconditionally
+     *  by every core spawn path). It selects which REFUSAL POSTURE a human deny speaks back to this
+     *  run's model: a parent-thread run is told to stop and wait for the user (its transcript has a
+     *  user turn coming), a delegated child is told to adapt or report the limitation. A fork is
+     *  deliberately IN: it inherits the parent's authority (design/110 — which is why the RB-330
+     *  `isDelegatedNonForkChild` derivation, serving the authority/context faces, excludes it), but
+     *  its interaction contract is one-shot — "report once and stop … no waiting for the user"
+     *  (FORK_DIRECTIVE_FRAME) — so a stop-and-wait refusal would instruct it to do the impossible
+     *  (codex adversarial round, confirmed). NOT the same fact as {@link fromSubagent} either: that is
+     *  the design/153 attribution discriminator (`parentTaskId` presence), which a directly-started
+     *  workflow's children lack even though refusals must still speak the child posture to them.
+     *  `readonly`, trusted (internals never ride a TaskSpec), sync-path-only like its siblings. */
+    readonly isDelegatedChild?: true;
     /** RB-203 (codex review, confirmed P1) — carried from the originating {@link PermissionResult}'s ask
      *  variant of the same name: `true` ⇒ {@link resolveAsk} must not let a blanket `onAsk: "allow"`
      *  clear this ask (see that field's doc). `readonly`, filled by the gate from the decision, never a
@@ -730,7 +776,7 @@ export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal)
  *    untyped bridge is a fail-closed deny naming the defect (the historical truthy leniency was a
  *    fail-open on the security face with no live producer).
  *  - `"unavailable"` — the G1 per-ask routing verdict (see {@link OnAsk}).
- *  - `{ allow, updatedInput?, settledBy? }` — verdict PLUS an operator EDIT of the presented args
+ *  - `{ allow, updatedInput?, settledBy?, reason? }` — verdict PLUS an operator EDIT of the presented args
  *    (whole-replacement form, e.g. ctrl+g "edit script in $EDITOR"): the human approved a MODIFIED
  *    action, and executing the un-edited args would betray that consent. `allow` folds STRICTLY
  *    (`allow === true`) — an object arm is a deliberate caller, so no truthy leniency — and
@@ -751,11 +797,30 @@ export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal)
  * `"aborted"` is deliberately NOT accepted here — that word names the engine's OWN fail-closed ends
  * (abort, throw, unavailable, out-of-contract value), each already stamped at its own arm, and a
  * self-reported one would let a host relabel its refusal as an engine failure.
+ *
+ * `reason` — the SYNCHRONOUS leg's seat for a model-readable reason attached to a deny, the exact
+ * counterpart of the durable leg's `ResumeOutcome` `policy_ask` `reason` ("Model-readable reason
+ * attached to a deny"): the words the decider typed with their "no" (an approval card's rejection
+ * input), relayed to the model so it can follow the person's direction instead of guessing. In-place
+ * conditions, all screened at {@link resolveAsk}:
+ *  - meaningful ONLY on a deny (`allow: false`); on an allow the seat is NEVER READ (accepted and
+ *    unused, literally — codex round: a junk value or a throwing accessor riding an approval cannot
+ *    destroy the approval). Same net posture as the durable leg, where a `reason` on an `allow` row
+ *    is never rendered;
+ *  - UNTRUSTED input (a human's free text riding a callback): it reaches the model only inside a
+ *    `delimitUntrusted` fence, the same containment the durable resume's reviewer note gets, and
+ *    bounded to `REVIEWER_NOTE_MAX_BODY` code points (an oversized note arrives truncated with an
+ *    ellipsis, never verbatim and never silently dropped — both legs share the one bound);
+ *  - on a deny, a present non-string is refused loudly (fail-closed deny naming the defect — the
+ *    domain the durable leg enforces pre-CAS for the same field), a THROWING read is a fail-closed
+ *    deny naming the true cause (never a raw rejection out of the gate), and the empty string reads
+ *    as absent (truthiness, the durable consumer's own read).
  */
 export type AskOutcome = boolean | "unavailable" | {
     allow: boolean;
     updatedInput?: unknown;
     settledBy?: Extract<ApprovalSettledBy, "human" | "timeout">;
+    reason?: string;
 };
 /**
  * ruled 2026-08-04 — forward an approver into a delegated child, stamping every ask it raises with the
@@ -802,7 +867,7 @@ export declare function tryCloneArgs<T>(v: T): {
 };
 /**
  * A label for a value that was THROWN at us, safe to put in a fail-closed refusal. Never coerces: `String(x)`
- * throws on a null-prototype object or a hostile `toString`/`Symbol.toPrimitive`, and the thrower here is
+ * throws on a null-prototype object or a untrusted `toString`/`Symbol.toPrimitive`, and the thrower here is
  * deployment-supplied (a getter inside the args can throw any object at `structuredClone`, an approver can
  * throw one at the gate). A coercion failure inside the catch would escape `resolveAsk` as a raw TypeError —
  * turning a classified fail-closed DENY into an unclassified crash, i.e. the failing input escaping the very
@@ -819,7 +884,7 @@ export declare function tryCloneArgs<T>(v: T): {
  *
  * Exported for the durable half of the same boundary (the runner's park mint), which now has a SECOND
  * way a deployment-supplied value can throw at capture time — the target backend's own codec refusing to
- * encode it. One containment point, so the two refusals cannot differ on how much of a hostile value's
+ * encode it. One containment point, so the two refusals cannot differ on how much of a untrusted value's
  * text they let through. Not part of the package's public surface.
  */
 export declare function describeThrown(err: unknown): string;
@@ -851,3 +916,4 @@ export type ResolvedAsk = PermissionResult & {
  * have ended, and `decisionReason: "mode"` is already the honest word for what produced them.
  */
 export declare function resolveAsk(req: AskRequest, onAsk: OnAsk | undefined, signal?: AbortSignal): Promise<ResolvedAsk>;
+export {};