@sema-agent/core 5.27.0 → 5.28.0

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/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[];
@@ -851,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) {

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

@@ -48,8 +48,10 @@ export interface ToolResultStore {
      *     (session, tool call) is legitimately written by two different tasks of one session — the
      *     Runner shares one store across its tasks on purpose, and a BYOM brain may mint the same
      *     tool-call id in both — so stamping a `taskId` there would turn a designed sharing case into a
-     *     refusal. Write sites whose ref carries the task (the background-agent and monitor spills key
-     *     on the handle id) state it; the offload/budget/projection sites state the session only;
+     *     refusal. Every engine write site therefore states the session only (#167) — including the
+     *     background-agent and monitor spills, whose ref DOES carry the registry handle id: that id is
+     *     an addressing segment of the ref, not an ownership coordinate a read-face caller can present
+     *     (see {@link ToolResultProvenance.taskId} for the namespace rule);
      *   - an entry stored **without** provenance (written by an older engine, or by a call site that has
      *     none) stays UNOWNED: `put` never back-fills an owner onto it (that would be adoption by a party
      *     that cannot prove it wrote it) and {@link ownerOf} keeps answering `undefined`, which a read face
@@ -72,12 +74,77 @@ export interface ToolResultStore {
      * that cannot answer this cannot back a host read face at all.
      */
     ownerOf?(ref: string): Promise<ToolResultProvenance | undefined> | ToolResultProvenance | undefined;
+    /**
+     * Erase every entry this store recorded as belonging to `sessionId` — the DELETE half of the same
+     * ownership coordinate {@link ownerOf} answers on. Without it a durable backend keeps a deleted
+     * session's offloaded and spilled results on its media indefinitely: `put`/`get` alone give a
+     * deployment no way to complete a session deletion, and the engine ships no scheduler that would
+     * eventually collect them.
+     *
+     * Rules every implementation follows:
+     *   - **selection is by RECORDED PROVENANCE, never by parsing the ref.** A ref is an opaque handle:
+     *     its session segment may be folded ({@link buildToolResultRef}), refs minted before the
+     *     injective form decompose two ways (`tr_team_blue_x` is both ("team","blue_x") and
+     *     ("team_blue","x")), and a caller may mint its own. Prefix-matching a ref therefore both
+     *     misses rows and reaches rows of a NEIGHBOURING session, and over-deletion here destroys a
+     *     live session's readable bytes. The owner recorded at the winning write is the one coordinate
+     *     that means exactly one thing, and it is the same one a read face authorizes against;
+     *   - **`taskId` is ignored in the match.** A stored `{sessionId, taskId}` is a NARROWING of the
+     *     same session, not a different owner — write sites stamped one before the namespace rule
+     *     settled the shape (#167), and such rows still belong to the session being deleted;
+     *   - **an UNOWNED entry is never deleted.** A row whose write stated no provenance (an older
+     *     engine, a call site that has none, or a two-object backend interrupted between publishing
+     *     content and owner) belongs to no session this sweep can name, and it is still READABLE via
+     *     `get` — deleting it on a guess would destroy another session's output. It is counted instead
+     *     ({@link ToolResultDeletionReport.unattributable}) so the caller learns the deletion was
+     *     incomplete rather than being told a clean "done";
+     *   - **idempotent**: deleting a session with no entries is a no-op, and a repeat call after a
+     *     partial (loudly failed) sweep resumes it;
+     *   - **concurrency-tolerant**: an entry that disappears between enumeration and removal is honest
+     *     absence, not an error.
+     *
+     * Typed OPTIONAL, and deliberately NOT part of the published contract kit
+     * (`toolResultStoreContract`): unlike `ownerOf`, a backend that cannot enumerate by owner is still
+     * a usable offload store, so its absence must stay a checkable fact rather than a contract breach.
+     * Present ⇒ the store can complete a session deletion; absent ⇒ the deployment owns that gap.
+     *
+     * Implementing it does NOT make a store `retention: "managed"` — that declaration promises the whole
+     * {@link import("./retention.js").ManagedRetentionCapability} (domain enumeration, tombstones,
+     * audit receipts, scheduled execution), of which this is one caller-driven erase.
+     */
+    deleteBySession?(sessionId: string): Promise<ToolResultDeletionReport> | ToolResultDeletionReport;
+}
+/**
+ * What a {@link ToolResultStore.deleteBySession} sweep actually did. A count, not a `void`, because the
+ * sweep has a documented INCOMPLETE outcome (unowned entries it must not delete) and a caller running a
+ * session-deletion face has to be able to tell "the session's results are gone" from "some rows survive
+ * that no session can clear".
+ */
+export interface ToolResultDeletionReport {
+    /** Entries removed by THIS call. A retry of an already-swept session reports `0`, not an error. */
+    readonly deleted: number;
+    /**
+     * Entries the sweep could not attribute to ANY session and therefore left in place: stored without
+     * provenance, or with an owner record that is present but unreadable. Store-wide, not
+     * session-specific — an unowned row may or may not have been this session's, which is precisely why
+     * it cannot be deleted — so the same figure recurs on every session's sweep until a migration or an
+     * operator clears those rows.
+     */
+    readonly unattributable: number;
 }
 /**
  * Backlog #119 — WHO a stored tool result belongs to. Structured (not a single opaque string) because
  * the read face authorizes by COMPARING fields it already knows; `taskId` is present when the write site
  * has one (it is a narrowing of the session, never a substitute for it).
  *
+ * #167 (namespace rule): a stamped `taskId` must name a coordinate the read face's CALLER presents —
+ * the host's own task/run id — never an engine-internal registry handle id. A handle id lives in a
+ * namespace only the engine's in-memory registry can resolve, so an owner stamped with one compares
+ * unequal to every caller coordinate forever: the entry becomes readable by NOBODY across the wire
+ * (fail-closed, but pointlessly — the disclosure text tells the caller to read it back). The engine's
+ * own write sites all state the session only; the handle id, where a ref needs it, is an ADDRESSING
+ * segment of the ref, not part of the owner.
+ *
  * Deliberately NOT part of it: `toolCallId`. It is a retention/addressing coordinate, not an ownership
  * one — two different tool calls in one session are the same owner.
  */
@@ -262,6 +329,12 @@ export declare class InMemoryToolResultStore implements ToolResultStore {
     /** #119 — the owner recorded at the winning write; `undefined` for unknown AND for unowned entries,
      *  which a read face treats identically (fail-closed). */
     ownerOf(ref: string): ToolResultProvenance | undefined;
+    /** Erase this session's entries, selected on the owner recorded at the winning write (the interface
+     *  states the rules). Implemented here as well as on the durable backends so the bundled pair does
+     *  not answer the same operation two ways: the entry holds content and owner as ONE value, so the
+     *  same provenance match applies with none of the file backend's two-object bookkeeping. Deleting
+     *  from a Map while iterating it is defined (a removed key is simply not revisited). */
+    deleteBySession(sessionId: string): ToolResultDeletionReport;
     /** design/80 D-2: true when NOTHING has been offloaded — a durable suspend can then proceed safely even on
      *  this in-memory store, because a cross-replica resume has no offloaded result to deref to null. */
     isEmpty(): boolean;
@@ -316,12 +389,35 @@ export declare function isVolatileOffloadStore(store: ToolResultStore): boolean;
 export declare const OFFLOAD_TOOL_NAME = "ReadToolResult";
 /**
  * RB-469-d — the runner's clear-with-offload persist, as ONE construction point (the closure used to
- * live inline in prepare-task). Fire-and-forget by design (the caller returns the ref synchronously),
- * but a failed put no longer strands the model with a ref pointing at nothing: a tiny lost-marker is
- * written under the same ref so the page-back face reports the true cause (C6 — "lost at write" and
- * "expired" are different answers). If the marker write fails too, the generic miss remains.
+ * live inline in prepare-task). Fire-and-forget by design (the caller returns the ref synchronously).
+ *
+ * #167 (A-025.17) — a failed put REPORTS the loss, it never writes under the ref. The previous arm
+ * wrote a lost-marker row under the SAME ref "so the page-back face reports the true cause", and that
+ * one write carried two defects:
+ *   - **revival**: the put and a session purge can race. When the put loses, the marker write lands
+ *     AFTER the purge — re-inserting a row into a session the deployment just deleted, alive until the
+ *     backend's own TTL. A failure arm must not be able to out-write a deletion;
+ *   - **retry poisoning**: the per-request re-clear legitimately re-invokes this persist with the same
+ *     (toolCallId, fullText) — the write-once retry path. With a marker occupying the ref, that
+ *     retry's put of the REAL bytes hit the write-once no-op (same owner ⇒ keep what is there), so a
+ *     transient first failure served the marker forever even though the full text was still in hand.
+ * Now the failure arm writes NOTHING (a later persist call retries the real bytes against an empty
+ * ref) and announces the failed write loudly instead: through the deployment's structured notice sink
+ * when one is wired, else `console.warn` (the loud-bad-value announcement dialect — a silent catch
+ * here would be a silent data loss). The announcement claims only what this arm can know: THIS
+ * attempt stored nothing — the same (toolCallId, fullText) persist recurs per request (write-once
+ * idempotent re-put), so an EARLIER attempt may already have landed the row and a rejected re-put is
+ * then no loss at all; declaring "the ref is empty" here would fabricate a data-loss incident on a
+ * transient outage. Page-back of a ref no attempt ever landed serves the generic miss, which is
+ * honest: nothing is stored under it.
  */
-export declare function createOffloadPersist(store: ToolResultStore, sessionId: string): (toolCallId: string, fullText: string) => string;
+export declare function createOffloadPersist(store: ToolResultStore, sessionId: string, 
+/** Structured sink for the loss announcement, delivered through the shared guarded form
+ *  (`deliverEngineNotice`, #170): a wired FUNCTION seat REPLACES the console line, swallow-guarded
+ *  (a throwing/rejecting sink never turns an announcement into a failure); a present NON-function
+ *  seat falls back to `console.warn` plus the once-per-process seat-defect announcement; absent ⇒
+ *  `console.warn`. */
+onNotice?: (notice: import("./types.js").EngineNotice) => void): (toolCallId: string, fullText: string) => string;
 /** Backlog #119 — build the provenance a write site records, from the two coordinates every write site
  *  already has in hand. `taskId` is omitted (not `undefined`-valued) when the run declares none, so the
  *  stored shape compares equal across a durable round-trip. */
@@ -388,6 +484,11 @@ export declare function buildPreview(full: string, ref: string, sizes?: {
  * wake needs a durable store (the default in-memory store loses the full text — the preview still stands).
  * Image blocks are left untouched; only text is offloaded. Forwards the `onUpdate` progress callback so a
  * wrapped (e.g. MCP) streaming tool isn't broken.
+ *
+ * Backlog #175 — a failing store NEVER turns the wrapped tool's success into a failure: the content face
+ * falls back to the original (un-offloaded) result, and the `details` walk to a ref-free notice per lost
+ * member (see the two arms for why the degrades differ). The wrapper adds a storage step to a tool that
+ * has already run; it must not be able to invalidate that run.
  */
 export declare function withToolResultOffload(tool: AgentTool, store: ToolResultStore, thresholdChars: number, sessionId: string, 
 /** RB-374① — LIVE accessor for the session's currently CALLABLE tool set (evaluated per offload,

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "./tools.js";
+import { deliverEngineNotice } from "./types.js";
 import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
 export const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
 export class ToolResultRefConflictError extends Error {
@@ -94,6 +95,22 @@ export class InMemoryToolResultStore {
     ownerOf(ref) {
         return this.map.get(ref)?.provenance;
     }
+    deleteBySession(sessionId) {
+        let deleted = 0;
+        let unattributable = 0;
+        for (const [ref, entry] of this.map) {
+            if (entry.provenance === undefined) {
+                unattributable++;
+                continue;
+            }
+            if (entry.provenance.sessionId !== sessionId)
+                continue;
+            this.map.delete(ref);
+            this.totalChars -= entry.content.length;
+            deleted++;
+        }
+        return { deleted, unattributable };
+    }
     isEmpty() {
         return this.map.size === 0;
     }
@@ -152,14 +169,23 @@ export function isVolatileOffloadStore(store) {
     return store instanceof InMemoryToolResultStore;
 }
 export const OFFLOAD_TOOL_NAME = "ReadToolResult";
-export function createOffloadPersist(store, sessionId) {
+export function createOffloadPersist(store, sessionId, onNotice) {
     const provenance = toolResultProvenanceOf(sessionId);
     return (toolCallId, fullText) => {
         const ref = buildToolResultRef(sessionId, toolCallId, toolResultContentSegment(fullText));
-        void Promise.resolve(store.put(ref, fullText, provenance)).catch((err) => {
+        const reportFailedWrite = (err) => {
             const cause = err instanceof Error ? err.message : String(err);
-            void Promise.resolve(store.put(ref, `[offload LOST at write time: ${cause} — the inline preview is all that survived]`, provenance)).catch(() => undefined);
-        });
+            const message = `tool-result offload: persisting ref "${ref}" failed (${cause}) — this write attempt stored nothing; ` +
+                `unless an earlier attempt already stored this ref, the inline preview is all that survived. ` +
+                `A later re-clear of the same result retries the write.`;
+            deliverEngineNotice(onNotice, { code: "tool_result.offload_put_failed", message, detail: { ref, sessionId, cause } });
+        };
+        try {
+            void Promise.resolve(store.put(ref, fullText, provenance)).catch(reportFailedWrite);
+        }
+        catch (err) {
+            reportFailedWrite(err);
+        }
         return ref;
     };
 }
@@ -236,7 +262,12 @@ export function withToolResultOffload(tool, store, thresholdChars, sessionId, re
         if (full.length <= PREVIEW_HEAD_CHARS + PREVIEW_TAIL_CHARS)
             return withDetails(res);
         const ref = buildToolResultRef(sessionId, toolCallId, toolResultContentSegment(full));
-        await store.put(ref, full, provenance);
+        try {
+            await store.put(ref, full, provenance);
+        }
+        catch {
+            return withDetails(res);
+        }
         const images = res.content.filter((b) => b.type !== "text");
         return withDetails({ ...res, content: [{ type: "text", text: buildPreview(full, ref, undefined, reachableTools?.()) }, ...images] });
     };
@@ -249,19 +280,34 @@ export function isOffloadedDetailReplacement(s) {
     return s.includes(`\n${OFFLOADED_DETAIL_NOTICE_PREFIX}`);
 }
 async function offloadOversizedDetailStrings(details, store, thresholdChars, sessionId, toolCallId, provenance) {
-    const puts = [];
-    const onStack = new Set();
     const isPlainObject = (v) => {
         if (typeof v !== "object" || v === null)
             return false;
         const p = Object.getPrototypeOf(v);
         return p === Object.prototype || p === null;
     };
+    const onStack = new Set();
+    const pending = [];
+    const rebuilt = new Set();
     const replace = (full, path) => {
         const detailRef = buildToolResultRef(sessionId, toolCallId, path, toolResultContentSegment(full));
-        puts.push(Promise.resolve(store.put(detailRef, full, provenance)));
-        return (`${full.slice(0, OFFLOADED_DETAIL_HEAD_CHARS)}\n` +
-            `${OFFLOADED_DETAIL_NOTICE_PREFIX}${full.length} chars total; ref "${detailRef}"; the remainder is retained in this run's tool-result store and reads back through the deployment's tool-results face]`);
+        let done;
+        try {
+            done = Promise.resolve(store.put(detailRef, full, provenance));
+        }
+        catch (err) {
+            done = Promise.reject(err);
+        }
+        const marker = {};
+        pending.push({
+            marker,
+            done,
+            render: (stored) => `${full.slice(0, OFFLOADED_DETAIL_HEAD_CHARS)}\n${OFFLOADED_DETAIL_NOTICE_PREFIX}${full.length} chars total; ` +
+                (stored
+                    ? `ref "${detailRef}"; the remainder is retained in this run's tool-result store and reads back through the deployment's tool-results face]`
+                    : `persisting the remainder to this run's tool-result store failed or went unconfirmed, so no ref is offered — the text above is all this field carries]`),
+        });
+        return marker;
     };
     const memo = new Map();
     const walk = (v, segs) => {
@@ -275,14 +321,21 @@ async function offloadOversizedDetailStrings(details, store, thresholdChars, ses
                 return done;
             onStack.add(v);
             let changed = false;
-            const next = v.map((item, i) => {
+            const len = v.length;
+            const next = new Array(len);
+            for (let i = 0; i < len; i++) {
+                if (!(i in v))
+                    continue;
+                const item = v[i];
                 const w = walk(item, [...segs, i]);
                 if (w !== item)
                     changed = true;
-                return w;
-            });
+                Object.defineProperty(next, i, { value: w, enumerable: true, writable: true, configurable: true });
+            }
             onStack.delete(v);
             const result = changed ? next : v;
+            if (changed)
+                rebuilt.add(next);
             memo.set(v, result);
             return result;
         }
@@ -303,14 +356,41 @@ async function offloadOversizedDetailStrings(details, store, thresholdChars, ses
             }
             onStack.delete(v);
             const result = changed ? next : v;
+            if (changed)
+                rebuilt.add(next);
             memo.set(v, result);
             return result;
         }
         return v;
     };
     const value = walk(details, []);
-    await Promise.all(puts);
-    return { value };
+    const settled = await Promise.allSettled(pending.map((p) => p.done));
+    const notices = new Map();
+    pending.forEach((p, i) => void notices.set(p.marker, p.render(settled[i].status === "fulfilled")));
+    const seen = new Set();
+    const finalize = (node) => {
+        if (typeof node !== "object" || node === null)
+            return node;
+        const notice = notices.get(node);
+        if (notice !== undefined)
+            return notice;
+        if (!rebuilt.has(node) || seen.has(node))
+            return node;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (let i = 0; i < node.length; i++) {
+                if (!Object.hasOwn(node, i))
+                    continue;
+                Object.defineProperty(node, i, { value: finalize(node[i]), enumerable: true, writable: true, configurable: true });
+            }
+            return node;
+        }
+        const obj = node;
+        for (const k of Object.keys(obj))
+            Object.defineProperty(obj, k, { value: finalize(obj[k]), enumerable: true, writable: true, configurable: true });
+        return node;
+    };
+    return { value: finalize(value) };
 }
 export function createReadToolResultTool(store) {
     return defineTool({