@sema-agent/core 5.26.0 → 5.28.0

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

@@ -126,7 +126,12 @@ export async function prepareMemory(input) {
                 };
             };
             const onEngineIncident = (err) => deps.onError?.(err, { phase: "memory", sessionId });
-            const retrievalBackend = (b) => b.retrievalView?.() ?? b;
+            const adoptionRestricted = input.memoryPersistenceDeclared === false;
+            const retrievalBackend = (b, planeRestricted) => planeRestricted
+                ? (b.restrictedAdoptionView?.({ audit: false }) ??
+                    b.retrievalView?.() ??
+                    b)
+                : (b.retrievalView?.() ?? b);
             const planeScopes = (scopes, write) => [...new Set([...scopes, ...(write !== null ? [write] : [])])];
             const pollutedOpts = (engine) => {
                 const rec = engine.sessionPollution(sessionId);
@@ -173,8 +178,8 @@ export async function prepareMemory(input) {
                 const personal = createPersonalEngine(personalBackendChosen);
                 const personalEngine = personal.engine;
                 const p = planes;
-                const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null);
-                const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null);
+                const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null, { adoptionRestricted });
+                const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null, { adoptionRestricted });
                 const writeIsPersonal = p.writePlane === "personal";
                 writeEngine = writeIsPersonal ? personalEngine : projectEngine;
                 writeHandle = writeIsPersonal ? personalHandle : projectHandle;
@@ -183,13 +188,13 @@ export async function prepareMemory(input) {
                 injectFn = () => mergeInjections(projectEngine.inject(projectHandle, { writeToolMounted: input.writeToolsMounted }), personalEngine.inject(personalHandle, { writeToolMounted: input.writeToolsMounted }));
                 toolPlanes = [
                     {
-                        backend: retrievalBackend(backend),
+                        backend: retrievalBackend(backend, adoptionRestricted || p.writePlane !== "project"),
                         scopes: planeScopes(p.project, p.writePlane === "project" ? memorySpec.writeScope : null),
                         recordRetrieved: (ids) => projectEngine.recordRetrieved(ids),
                         challengeExclusions: () => projectEngine.readChallengeExclusions(),
                     },
                     {
-                        backend: retrievalBackend(personal.backend),
+                        backend: retrievalBackend(personal.backend, adoptionRestricted || p.writePlane !== "personal"),
                         scopes: planeScopes(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null),
                         recordRetrieved: (ids) => personalEngine.recordRetrieved(ids),
                         challengeExclusions: () => personalEngine.readChallengeExclusions(),
@@ -216,14 +221,14 @@ export async function prepareMemory(input) {
             else if (personalOnly) {
                 const personal = createPersonalEngine(choosePersonalBackend());
                 const personalEngine = personal.engine;
-                const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope);
+                const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted });
                 writeEngine = personalEngine;
                 writeHandle = handle;
                 injectFn = () => personalEngine.inject(handle, { writeToolMounted: input.writeToolsMounted });
                 harvestBoth = () => personalEngine.harvest(handle, { ...pollutedOpts(personalEngine), sessionId, ...admitNothingOpts });
                 toolPlanes = [
                     {
-                        backend: retrievalBackend(personal.backend),
+                        backend: retrievalBackend(personal.backend, adoptionRestricted || memorySpec.writeScope === null),
                         scopes: planeScopes(memorySpec.scopes, memorySpec.writeScope),
                         recordRetrieved: (ids) => personalEngine.recordRetrieved(ids),
                         challengeExclusions: () => personalEngine.readChallengeExclusions(),
@@ -237,14 +242,14 @@ export async function prepareMemory(input) {
                     controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
                     onIncident: onEngineIncident,
                 });
-                const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope);
+                const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted });
                 writeEngine = engine;
                 writeHandle = handle;
                 injectFn = () => engine.inject(handle, { writeToolMounted: input.writeToolsMounted });
                 harvestBoth = () => engine.harvest(handle, { ...pollutedOpts(engine), sessionId, ...admitNothingOpts });
                 toolPlanes = [
                     {
-                        backend: retrievalBackend(backend),
+                        backend: retrievalBackend(backend, adoptionRestricted || memorySpec.writeScope === null),
                         scopes: planeScopes(memorySpec.scopes, memorySpec.writeScope),
                         recordRetrieved: (ids) => engine.recordRetrieved(ids),
                         challengeExclusions: () => engine.readChallengeExclusions(),

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

@@ -354,7 +354,10 @@ export interface Prepared {
      *  deferred; a caller with no accessor has no deferred family to describe. */
     staticFaceFor?: (name: string) => boolean;
     /**
-     * design/138 S1 — the MemoryEngine session (present iff `deps.memoryBackend` + `spec.memory.enabled`).
+     * design/138 S1 — the MemoryEngine session. Present when `deps.memoryBackend` + `spec.memory.enabled`
+     * hold AND the engine mount succeeded: a materialize failure without a `config.memory_*` code is
+     * fail-open (reported via `deps.onError`, the task runs memory-less), leaving this absent even though
+     * both flags hold.
      * `harvest` is the swallow-guarded boundary hook (task terminal in runtask + the checkpoint mint
      * point in commitSuspendSaga): it runs the FULL gate set (containment/secret/caps/deletion fuse),
      * commits entry patches to the backend, self-heals the derived index, and re-baselines (a second
@@ -1296,8 +1299,11 @@ export interface RunInternals {
      * design/99 (nested-subagent live tree) — an OPT-IN, DISPLAY-ONLY event sink a deployment sets on the TOP run to
      * receive a subagent's live `task_progress` ticks (which otherwise stay in the child's ISOLATED stream). Threaded
      * recursively down the delegation tree (via `ctx.forwardEvent`), so every nested subagent's ticks bubble to the
-     * SAME sink. The Runner forwards ONLY `task_progress` through it; the child stream is NEVER merged into the
-     * parent's MODEL context (this is purely a render channel). Absent unless the deployment opted in.
+     * SAME sink. The Runner's ctx wrapper forwards `task_progress` always; when the run's spec sets
+     * `forwardSubagentEvents: true` it ALSO forwards the child's content events (`text_delta` / `reasoning_delta` /
+     * `tool_start` / `tool_end` — the subagent viewing pane, carrying the same UNTRUSTED-RAW/consumer-must-redact
+     * contract as the main stream's tool events). Either way the child stream is NEVER merged into the parent's
+     * MODEL context (this is purely a render channel). Absent unless the deployment opted in.
      */
     onForwardEvent?: (event: TaskEvent) => void;
     /**

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

@@ -29,7 +29,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { policyAskClassOf } from "../ask-class.js";
 import { emitTrace } from "../trace.js";
 import { createSessionRulePolicy } from "./session-rule-policy.js";
-import { cloneObserverInput, createHookEnvCapabilities, createPreToolUseConstraintPolicy, formatHookFeedback, runToolGate } from "../hooks.js";
+import { cloneObserverInput, createHookEnvCapabilities, createPreToolUseConstraintPolicy, formatHookFeedback, persistedRuleMandateOf, runToolGate } from "../hooks.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
 import { reconcileInterruptedSession } from "../session-reconcile.js";
 import { CacheBreakDetector, toolsToFingerprintInputs } from "../cache-break-detector.js";
@@ -89,10 +89,14 @@ import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, ORG_ADMISSION_CHECKPOI
 import { boundInputHashOf } from "../canonical-json.js";
 import { countElicitOptIns, deriveAskEffective, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam } from "../wiring-manifest.js";
 import { GLOBAL_USAGE_KEY, resolveUsageWindows, usageRetryAfterMs } from "../usage-window-store.js";
+import { deliverEngineNotice } from "../types.js";
 const announcedMaterializeEnv = new Set();
 export function __resetMaterializeEnvAnnouncements() {
     announcedMaterializeEnv.clear();
 }
+function emitMaterializeEnvNotice(onNotice, message, detail) {
+    deliverEngineNotice(onNotice, { code: "config.materialize_env_discarded", message, detail });
+}
 const RECONCILE_MAX_RETRIES = 3;
 const DEFAULT_MAX_SUSPENDS = 5;
 const TASK_LIMIT_KEY_DICT = {
@@ -1659,6 +1663,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ...(sessionId !== undefined ? { sessionId } : {}),
                 ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
                 ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
+                ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
                 pdfModelCapabilities: pdfModelCapabilitiesOf(model),
                 ...(deps.hands?.bashReadonlyAllow !== undefined ? { bashReadonlyAllow: deps.hands.bashReadonlyAllow } : {}),
                 ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
@@ -2606,7 +2611,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 const line = `SEMA_TOOL_MATERIALIZE_STRATEGY=${JSON.stringify(raw)} is not "swap" or "static" — inert on this task (no deferred tools), but a deferring task WITHOUT an explicit spec strategy will refuse to prepare under it (an explicit legal spec outranks and discards it, loudly). Fix or unset the flag.`;
                 if (!announcedMaterializeEnv.has(line)) {
                     announcedMaterializeEnv.add(line);
-                    console.warn(line);
+                    emitMaterializeEnvNotice(deps.onNotice, line, { raw });
                 }
             }
         }
@@ -2628,7 +2633,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 const line = `SEMA_TOOL_MATERIALIZE_STRATEGY=${JSON.stringify(rawEnvStrategy)} was ignored — not "swap" or "static", and the task spec pins toolMaterializeStrategy=${JSON.stringify(spec.toolMaterializeStrategy)} which outranks it. Fix or unset the env flag.`;
                 if (!announcedMaterializeEnv.has(line)) {
                     announcedMaterializeEnv.add(line);
-                    console.warn(line);
+                    emitMaterializeEnvNotice(deps.onNotice, line, { raw: rawEnvStrategy, specStrategy: spec.toolMaterializeStrategy });
                 }
             }
             const envStrategy = envStrategyInvalid ? undefined : rawEnvStrategy;
@@ -3260,9 +3265,25 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 },
             };
         })();
-        const ruleSuggestionsOf = (toolName, args) => {
+        const ruleSuggestionsOf = (toolName, args, ask) => {
             if (permissionRuleLane === undefined || toolName !== PERSISTED_RULE_TOOL)
                 return {};
+            if ((spec.principal === undefined || spec.principal === "") && deps.localOwnerRules !== true)
+                return {};
+            if (ask?.requiresRealApproval === true ||
+                ask?.persistedRuleShadowed !== undefined ||
+                ask?.decisionReason === "hook" ||
+                ask?.inheritedUnresolved === true ||
+                ask?.ancestorResolved === true) {
+                return {};
+            }
+            if (persistedRuleMandateOf({
+                egress: egressTools.has(toolName),
+                irreversibility: irreversibilityTier.get(toolName),
+                shellGated: shellGatedBash,
+            }) !== undefined) {
+                return {};
+            }
             const command = args?.command;
             if (typeof command !== "string")
                 return {};
@@ -3315,7 +3336,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     toolName: creq.toolName,
                     toolCallId: creq.toolCallId,
                     args: editArgs,
-                    ...ruleSuggestionsOf(creq.toolName, editArgs),
+                    ...ruleSuggestionsOf(creq.toolName, editArgs, { ...(re ?? {}), ancestorResolved: true }),
                     message: re.message ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                     ...askSourceIdentity(),
                     ...riskAxesOf(creq.toolName),
@@ -3400,7 +3421,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             toolName: creq.toolName,
                             toolCallId: creq.toolCallId,
                             args: presentedArgs,
-                            ...ruleSuggestionsOf(creq.toolName, presentedArgs),
+                            ...ruleSuggestionsOf(creq.toolName, presentedArgs, { ...(first.action === "ask" ? first : {}), ancestorResolved: true }),
                             message: first.message ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                             ...askSourceIdentity(),
                             ...riskAxesOf(creq.toolName),
@@ -3487,7 +3508,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             toolName: creq.toolName,
                             toolCallId: creq.toolCallId,
                             args: presentedArgs,
-                            ...ruleSuggestionsOf(creq.toolName, presentedArgs),
+                            ...ruleSuggestionsOf(creq.toolName, presentedArgs, { ...(decision.action === "ask" ? decision : {}), ancestorResolved: true }),
                             message: decision.message ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                             ...askSourceIdentity(),
                             ...riskAxesOf(creq.toolName),
@@ -3800,7 +3821,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         const preview = approvalPreviewOf(req.toolName, req.args);
                         return preview !== undefined ? { preview } : {};
                     })(),
-                    ...ruleSuggestionsOf(req.toolName, req.args),
+                    ...ruleSuggestionsOf(req.toolName, req.args, decision.action === "ask" ? decision : undefined),
                     message: decision.message ?? `approval required for "${req.toolName}"`,
                     ...askSourceIdentity(),
                     ...riskAxesOf(req.toolName),
@@ -4287,7 +4308,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 }
             };
             const suspendAsk = parkLaneArmed && checkpointStore !== undefined
-                ? async (req, postHookArgs, safety, liveFaceUnavailable, realApproval, shadowedRule) => {
+                ? async (req, postHookArgs, safety, liveFaceUnavailable, realApproval, shadowedRule, askDecisionReason) => {
                     const syncFirstEligible = req.toolName === ASK_USER_QUESTION_TOOL_NAME ? contentAskRoutable(req.toolCallId) : isLiveApproverSeat(onAsk);
                     if (syncFirstEligible &&
                         runtimeCaps?.forceDurableGate !== true &&
@@ -4442,7 +4463,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                                     const preview = approvalPreviewOf(req.toolName, parkedArgs);
                                     return preview !== undefined ? { preview } : {};
                                 })(),
-                                ...ruleSuggestionsOf(req.toolName, parkedArgs),
+                                ...ruleSuggestionsOf(req.toolName, parkedArgs, {
+                                    ...(realApproval !== undefined ? { requiresRealApproval: true } : {}),
+                                    ...(shadowedRule !== undefined ? { persistedRuleShadowed: shadowedRule } : {}),
+                                    ...(askDecisionReason !== undefined ? { decisionReason: askDecisionReason } : {}),
+                                    ...(inheritedUnavailableAsks.has(req.toolCallId) ? { inheritedUnresolved: true } : {}),
+                                }),
                                 boundInputHash: boundInputHashOf(parkedArgs),
                                 batchToolCallIds,
                                 completedCallIds,
@@ -4710,7 +4736,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ...(offloadStore
                     ? {
                         offload: {
-                            persist: createOffloadPersist(offloadStore, sessionId),
+                            persist: createOffloadPersist(offloadStore, sessionId, deps.onNotice),
                         },
                     }
                     : {}),

package/dist/core/runner/runtask.d.ts

@@ -250,7 +250,14 @@ export declare class Runner {
      *   env_failed re-resume supplied a decision ≠ the persisted winner), `reopened_concurrently` (the
      *   optimistic-concurrency `rev` changed under a concurrent resolve/reopen — re-resume against current
      *   state), `unsupported_version` (checkpoint newer than this worker / remote handle with no factory),
-     *   `already_resolved` (lost the CAS — idempotent no-op).
+     *   `already_resolved` (lost the CAS — idempotent no-op), `walltime_axis_retired` (pre-CAS: the
+     *   persisted ledger carries the retired wall-clock budget axis — a worker of the previous release can
+     *   still finish it), `resume_aborted` (the caller's signal was already aborted at entry, or aborted
+     *   during the resume — pre-CAS/edit-re-adjudication legs leave the checkpoint pending and resumable,
+     *   the post-claim leg leaves it consumed; the message says which), `reopen_failed` (an aborted resume
+     *   needed to reopen the checkpoint and the store refused, or the reopen failed in flight — the message
+     *   distinguishes terminally-consumed from state-unprovable). Each code's full contract is on
+     *   {@link CheckpointError.code}.
      */
     resume(token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, 
     /** RB-48② (1.404): same TRUSTED run-internals seam as {@link resumeStream} — the convenience wrapper

package/dist/core/runner/runtask.js

@@ -131,7 +131,10 @@ const DEFERRED_REISSUE = "[DEFERRED] This tool call shared a batch with a call t
 function toolEndBodyFrom(result, isError, settledBy) {
     const o = toolOutputFrom(result);
     const st = structuredFrom(result);
-    const code = isError ? result?.details?.code : undefined;
+    const det = isError ? result?.details : undefined;
+    const codeRaw = det?.code;
+    const kindRaw = det?.errorKind;
+    const code = typeof codeRaw === "string" ? codeRaw : typeof kindRaw === "string" ? kindRaw : undefined;
     return {
         ...(o !== undefined ? { output: o.output, ...(o.truncated ? { truncated: true } : {}), ...(o.totalChars !== undefined ? { totalChars: o.totalChars } : {}) } : {}),
         ...(st !== undefined ? { structured: st } : {}),
@@ -1412,6 +1415,10 @@ export class Runner {
         return runSideQuery(spec, { brain: this.deps.brain, models: this.deps.models, roles: this.deps.roles });
     }
     runTaskStream(spec, resume, internals) {
+        if (resume !== undefined && (typeof resume !== "object" || resume.outcome === undefined)) {
+            throw new TypeError("runTaskStream: `resume` must be a ResumeRun carrying `outcome` — got a value without one. " +
+                "(Note the parameter order: runTaskStream(spec, resume?, internals?) — internals is the THIRD parameter.)");
+        }
         const entryActor = spec.actor === undefined ? undefined : snapshotActorAssertion(spec.actor);
         const queue = new PushQueue();
         const detachHub = new ToolDetachHub();

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

@@ -415,9 +415,10 @@ export declare function notFoundRunningAgentsTail(footer: {
  *  so a structured consumer lost the failure FACT at exactly the moment it could no longer reach the
  *  live handle, left to scrape the prose body's `error:` line.
  *
- *  The status GATES live here too (killed ⇒ stoppedBy, failed ⇒ error/errorCode/retryable) rather than
- *  at the call sites: which facts a given status may carry is part of the same contract, and a gate
- *  copied per face is the same drift with extra steps. `error` is model/provider-influenceable text, so
+ *  The fact gates live here too (failed ⇒ error/errorCode/retryable/retryAfterMs; `stoppedBy` rides
+ *  whenever the ROW carries it, on any status — a reaper-settled `failed` row keeps its attribution,
+ *  see the widening note in the builder) rather than at the call sites: which facts a given row may
+ *  carry is part of the same contract, and a gate copied per face is the same drift with extra steps. `error` is model/provider-influenceable text, so
  *  the fencing + bounding (RB-386②'s posture) happens once, here, for both faces.
  *  The parked projection is this builder with fewer facts, not a third literal. */
 export interface AgentPollDetailsInput {
@@ -470,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

@@ -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 /

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

@@ -33,8 +33,10 @@ export interface RegisterBackgroundBashInput extends TaskAccess {
     /** CC 2.1.209 对齐批A A5: the task's OUTPUT FILE — the launch receipt advertises it and the watcher
      *  mirrors every polled increment into it (append-only, unbounded — unlike the rolling in-memory
      *  spool), so "Read the output file path" is a real alternative to TaskOutput. Terminal
-     *  task-notifications carry the same path (`output_file`). Only meaningful with `onTerminal` (the
-     *  watcher is the writer); callers create the file (empty) before registering. */
+     *  task-notifications carry the same path (`output_file`). Primarily meaningful with `onTerminal`
+     *  (only the watcher mirrors increments live); a watcher-less row still gets ONE final best-effort
+     *  append at TaskStop/run-teardown (the tail drain), so the file is written even without a watcher —
+     *  there is just no live mirror. Callers create the file (empty) before registering. */
     outputFile?: string;
 }
 export interface TaskPollOptions {
@@ -369,7 +371,8 @@ export declare class TaskRegistry {
      *  BEFORE the abort()/status flip — the ordering is load-bearing: the guard below refuses markers on a
      *  non-running handle, so a caller that flips first loses its claim and attribution falls back to
      *  "system". First-marker-wins: an earlier marker (e.g. a service-wire "user") is never overwritten.
-     *  Applies to background_agent AND background_bash (same class); workflow cancellation is out of scope. */
+     *  Applies to background_agent, background_bash AND monitor handles (the markable kinds — the monitor
+     *  watcher/stop lanes mark and read it too); workflow cancellation is out of scope. */
     markStopSource(id: string, source: StopSource): void;
     /**
      * [1712] / RB-164 — attribute an ENV-LEVEL blanket sweep before it runs.

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.
@@ -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 adversary 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 hostile 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[];
@@ -632,9 +664,16 @@ export interface AskRequest {
     /**
      * design/179 §4 — the persistable allow-rule forms this exact call could be covered by, so a surface can
      * offer "allow, and stop asking me this" with something concrete behind it. Present only when a
-     * persisted allow-rule lane is armed AND the call is one the lane can speak for: a compound, a
+     * persisted allow-rule lane is armed AND the call is one the lane can speak for (a compound, a
      * redirection or a substitution yields NO suggestion, which is the honest answer rather than an option
-     * that would be refused on redemption.
+     * that would be refused on redemption) AND the ask is one a persisted rule could actually clear — a
+     * mandated ask (operator shellGate:"always", the tool's own egress/irreversibility marks, a
+     * `requiresRealApproval` demand) and an ask carrying {@link persistedRuleShadowed} offer none.
+     *
+     * CONTRACT — array order is display order, narrowest first: the EXACT form is always index 0, a
+     * broader reviewed PREFIX form (at most one) follows. Basis ≤ 2. Selection indices and redemption
+     * tickets are keyed against this order, and the durable park row carries the same array under the
+     * same contract.
      *
      * ADVISORY display metadata, never adjudication input, and never a rule by itself: minting one is a
      * separate act that goes through the approval-record protocol, so a surface that ignores this field
@@ -844,3 +883,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 {};

package/dist/core/tool-policy.js

@@ -7,6 +7,8 @@ import { boundInputHashOf } from "./canonical-json.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { parsePermissionRule } from "./permission-rules.js";
 import { isAbsolutePathForm, isWinFormPath, writeTargetPath } from "../tools/fs/safety.js";
+const DECISION_REASONS = ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable"];
+const DECISION_REASON_SET = new Set(DECISION_REASONS);
 export const APPROVAL_SETTLED_BY_VALUES = ["human", "timeout", "aborted"];
 export function isApprovalSettledBy(v) {
     return typeof v === "string" && APPROVAL_SETTLED_BY_VALUES.includes(v);
@@ -79,12 +81,44 @@ const ALLOW = { action: "allow" };
 const RETIRED_TEXT_FIELD = "reason";
 const RETIRED_TEXT_FIELD_DENY_MESSAGE = `a permission decision carries the retired "${RETIRED_TEXT_FIELD}" field — rename it to "message" (the one text field ` +
     `a decision carries); denied fail-closed rather than executing a decision whose text this layer cannot read`;
-export function refuseOutOfContractDecision(d) {
+export function refuseOutOfContractDecision(d, opts) {
     if (typeof d !== "object" || d === null)
         return d;
-    if (!Object.prototype.hasOwnProperty.call(d, RETIRED_TEXT_FIELD))
+    if (Object.prototype.hasOwnProperty.call(d, RETIRED_TEXT_FIELD)) {
+        return { action: "deny", message: RETIRED_TEXT_FIELD_DENY_MESSAGE, decisionReason: "rule" };
+    }
+    if (opts?.reasonIsNonInput === true)
+        return d;
+    const dr = d.decisionReason;
+    if (dr === undefined)
         return d;
-    return { action: "deny", message: RETIRED_TEXT_FIELD_DENY_MESSAGE, decisionReason: "rule" };
+    if (!DECISION_REASON_SET.has(dr)) {
+        let rendered;
+        try {
+            rendered = JSON.stringify(String(dr).slice(0, 64));
+        }
+        catch {
+            rendered = `[unprintable ${typeof dr}]`;
+        }
+        return {
+            action: "deny",
+            message: `a permission decision carries an unrecognized "decisionReason" value (${rendered}) — ` +
+                `the closed set is ${DECISION_REASONS.join("/")}; denied fail-closed rather than letting consumers ` +
+                `branch on a value this layer cannot classify`,
+            decisionReason: "rule",
+        };
+    }
+    const carrier = Object.getOwnPropertyDescriptor(d, "decisionReason");
+    if (carrier === undefined || !("value" in carrier)) {
+        return {
+            action: "deny",
+            message: `a permission decision supplies "decisionReason" through ${carrier === undefined ? "its prototype" : "an accessor"} — ` +
+                `contract fields must be own data properties, so consumers re-reading the field cannot be shown a ` +
+                `different value than this screen validated; denied fail-closed`,
+            decisionReason: "rule",
+        };
+    }
+    return d;
 }
 const DEADLINE_ELAPSED = Symbol("approval.deadline_elapsed");
 function withTimeout(p, ms, onTimeout) {