@sema-agent/core 5.25.0 → 5.26.0

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

@@ -1,8 +1,9 @@
+import { sep } from "node:path";
 import { admitMemoryScopes } from "../memory-admission.js";
-import { adoptLegacyRepoDirs, deriveRepoControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.js";
+import { adoptLegacyRepoDirs, canonicalize, deriveRepoControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, isContainedIn, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.js";
 import { classifyScopePlanes, derivePersonalControlDir, derivePersonalMemoryDir, mergeHarvestReports, mergeInjections, needsDualRoots, parsedProjectPlane } from "../memory-engine/dual-root.js";
 import { normalizeMemorySpec } from "../memory.js";
-import { MEMORY_PREFERENCE_DISCIPLINE, MEMORY_RECALL_DISCIPLINE, MemoryEngine } from "../memory-engine/engine.js";
+import { MEMORY_ANNOUNCEMENT_READONLY_CODA, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_RECALL_DISCIPLINE, MemoryEngine } from "../memory-engine/engine.js";
 import { createMemoryEngineTools } from "../memory-engine/tools.js";
 import { assertScopeContractPlacement, parseScopeKey, resolveProjectId } from "../memory-engine/scope-contract.js";
 import { FileMemoryEngineBackend } from "../memory-engine/file-backend.js";
@@ -113,10 +114,12 @@ export async function prepareMemory(input) {
             }
             const personalMemoryDir = derivePersonalMemoryDir(engineRoot);
             const personalControlDir = derivePersonalControlDir(engineRoot);
-            const createPersonalEngine = () => {
-                const personalBackend = typeof pinned === "string" && pinned
-                    ? new FileMemoryEngineBackend(personalMemoryDir, { controlDir: personalControlDir })
-                    : backend;
+            const effectiveControlDir = (b, fallback) => {
+                const pinnedCtl = b.controlPlaneRoot;
+                return typeof pinnedCtl === "string" && pinnedCtl ? pinnedCtl : fallback;
+            };
+            const choosePersonalBackend = () => typeof pinned === "string" && pinned ? new FileMemoryEngineBackend(personalMemoryDir, { controlDir: personalControlDir }) : backend;
+            const createPersonalEngine = (personalBackend) => {
                 return {
                     engine: new MemoryEngine({ backend: personalBackend, memoryDir: personalMemoryDir, controlDir: personalControlDir, onIncident: onEngineIncident }),
                     backend: personalBackend,
@@ -131,17 +134,43 @@ export async function prepareMemory(input) {
             };
             let writeEngine;
             let writeHandle;
+            let readOnlyEngine;
+            let readOnlyHandle;
             let injectFn;
             let harvestBoth;
             let toolPlanes;
+            const admitNothingOpts = input.memoryPersistenceDeclared === false
+                ? { admitNothing: { reason: "harvest admitted nothing: memory persistence is declared unavailable for this session (memoryPersistenceCapable: false)" } }
+                : {};
             if (dual) {
+                const personalBackendChosen = choosePersonalBackend();
+                {
+                    const projCtl = effectiveControlDir(backend, identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot));
+                    const persCtl = effectiveControlDir(personalBackendChosen, personalControlDir);
+                    const overlap = (a, b) => isContainedIn(a, b) || isContainedIn(b, a);
+                    const refuse = (what, a, b) => {
+                        const e = new Error(`memory dual-root configuration error: ${what} overlap (${canonicalize(a)} vs ${canonicalize(b)}) — the planes' data roots and control planes must all be disjoint.`);
+                        e.code = "config.memory_dual_root_overlap";
+                        throw e;
+                    };
+                    if (overlap(memoryDir, personalMemoryDir))
+                        refuse("the project and personal memory roots", memoryDir, personalMemoryDir);
+                    if (overlap(projCtl, persCtl))
+                        refuse("the project and personal control planes", projCtl, persCtl);
+                    for (const [ctlName, ctl] of [["project control plane", projCtl], ["personal control plane", persCtl]]) {
+                        for (const [rootName, dataRoot] of [["project memory root", memoryDir], ["personal memory mount", personalMemoryDir]]) {
+                            if (overlap(ctl, dataRoot))
+                                refuse(`the ${ctlName} and the ${rootName}`, ctl, dataRoot);
+                        }
+                    }
+                }
                 const projectEngine = new MemoryEngine({
                     backend,
                     memoryDir,
                     controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
                     onIncident: onEngineIncident,
                 });
-                const personal = createPersonalEngine();
+                const personal = createPersonalEngine(personalBackendChosen);
                 const personalEngine = personal.engine;
                 const p = planes;
                 const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null);
@@ -149,6 +178,8 @@ export async function prepareMemory(input) {
                 const writeIsPersonal = p.writePlane === "personal";
                 writeEngine = writeIsPersonal ? personalEngine : projectEngine;
                 writeHandle = writeIsPersonal ? personalHandle : projectHandle;
+                readOnlyEngine = writeIsPersonal ? projectEngine : personalEngine;
+                readOnlyHandle = writeIsPersonal ? projectHandle : personalHandle;
                 injectFn = () => mergeInjections(projectEngine.inject(projectHandle, { writeToolMounted: input.writeToolsMounted }), personalEngine.inject(personalHandle, { writeToolMounted: input.writeToolsMounted }));
                 toolPlanes = [
                     {
@@ -167,7 +198,7 @@ export async function prepareMemory(input) {
                 harvestBoth = async () => {
                     const writeFirst = writeIsPersonal ? [personalEngine, personalHandle] : [projectEngine, projectHandle];
                     const readOther = writeIsPersonal ? [projectEngine, projectHandle] : [personalEngine, personalHandle];
-                    const writeReport = await writeFirst[0].harvest(writeFirst[1], { ...pollutedOpts(writeFirst[0]), sessionId });
+                    const writeReport = await writeFirst[0].harvest(writeFirst[1], { ...pollutedOpts(writeFirst[0]), sessionId, ...admitNothingOpts });
                     let readReport;
                     let readFailure;
                     try {
@@ -183,13 +214,13 @@ export async function prepareMemory(input) {
                 };
             }
             else if (personalOnly) {
-                const personal = createPersonalEngine();
+                const personal = createPersonalEngine(choosePersonalBackend());
                 const personalEngine = personal.engine;
                 const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope);
                 writeEngine = personalEngine;
                 writeHandle = handle;
                 injectFn = () => personalEngine.inject(handle, { writeToolMounted: input.writeToolsMounted });
-                harvestBoth = () => personalEngine.harvest(handle, { ...pollutedOpts(personalEngine), sessionId });
+                harvestBoth = () => personalEngine.harvest(handle, { ...pollutedOpts(personalEngine), sessionId, ...admitNothingOpts });
                 toolPlanes = [
                     {
                         backend: retrievalBackend(personal.backend),
@@ -210,7 +241,7 @@ export async function prepareMemory(input) {
                 writeEngine = engine;
                 writeHandle = handle;
                 injectFn = () => engine.inject(handle, { writeToolMounted: input.writeToolsMounted });
-                harvestBoth = () => engine.harvest(handle, { ...pollutedOpts(engine), sessionId });
+                harvestBoth = () => engine.harvest(handle, { ...pollutedOpts(engine), sessionId, ...admitNothingOpts });
                 toolPlanes = [
                     {
                         backend: retrievalBackend(backend),
@@ -220,7 +251,25 @@ export async function prepareMemory(input) {
                     },
                 ];
             }
-            memoryWriteGateRef.current = (w) => writeEngine.gateWrite(writeHandle, w.key, w.content);
+            memoryWriteGateRef.current = (w) => {
+                if (readOnlyEngine !== undefined && readOnlyHandle !== undefined) {
+                    const ro = readOnlyEngine.gateWrite(readOnlyHandle, w.key, w.content);
+                    if (!ro.ok)
+                        return ro;
+                }
+                if (input.memoryPersistenceDeclared === false) {
+                    const root = writeHandle.writableRoot;
+                    if (w.key === root || w.key.startsWith(`${root}${sep}`)) {
+                        return {
+                            ok: false,
+                            code: "read_only_layering",
+                            reason: `memory persistence is declared unavailable for this session (memoryPersistenceCapable: false) — writes into the memory store are refused. Nothing was written.`,
+                            muted: false,
+                        };
+                    }
+                }
+                return writeEngine.gateWrite(writeHandle, w.key, w.content);
+            };
             const harvestSafe = async (phase = "terminal") => {
                 try {
                     const report = await harvestBoth();
@@ -261,7 +310,10 @@ export async function prepareMemory(input) {
                 memoryTools = createMemoryEngineTools({ planes: toolPlanes });
         }
         catch (err) {
-            if (typeof err.code === "string" && (err.code.startsWith("config.memory_scope") || err.code.startsWith("config.memory_project"))) {
+            if (typeof err.code === "string" &&
+                (err.code.startsWith("config.memory_scope") ||
+                    err.code.startsWith("config.memory_project") ||
+                    err.code === "config.memory_dual_root_overlap")) {
                 throw err;
             }
             deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "memory", sessionId });
@@ -275,15 +327,31 @@ export async function prepareMemory(input) {
     }
     if (memoryEngineSession) {
         const injection = memoryEngineSession.inject();
-        if (injection.block.trim())
-            memoryBlock = injection.block;
+        let blockBody = injection.block;
+        if (!input.rosterCanPersist && injection.instruction === "" && injection.readOnlyNotice === undefined) {
+            blockBody = blockBody.trim() ? `${MEMORY_READONLY_NOTICE}\n\n${blockBody}` : MEMORY_READONLY_NOTICE;
+        }
+        else if (!input.rosterCanPersist && injection.instruction !== "") {
+            blockBody = [MEMORY_READONLY_NOTICE, injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+        }
+        else if (input.memoryPersistenceDeclared === true && injection.readOnlyNotice !== undefined) {
+            blockBody = [injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+        }
+        if (!input.rosterCanPersist &&
+            (injection.announceBlock?.trim() ?? "") !== "" &&
+            blockBody.includes(injection.announceBlock) &&
+            !blockBody.trimEnd().endsWith(MEMORY_ANNOUNCEMENT_READONLY_CODA)) {
+            blockBody = `${blockBody}\n\n${MEMORY_ANNOUNCEMENT_READONLY_CODA}`;
+        }
+        if (blockBody.trim())
+            memoryBlock = blockBody;
         if (memoryTools !== undefined) {
             memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${MEMORY_RECALL_DISCIPLINE}` : MEMORY_RECALL_DISCIPLINE;
         }
-        if (memoryEngineSession.handle.writeScope !== null && input.writeToolsMounted) {
+        if (memoryEngineSession.handle.writeScope !== null && input.writeToolsMounted && input.rosterCanPersist) {
             memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${MEMORY_PREFERENCE_DISCIPLINE}` : MEMORY_PREFERENCE_DISCIPLINE;
         }
-        if (memoryBlock !== undefined && injection.indexSeed !== undefined)
+        if (memoryBlock !== undefined && injection.indexSeed !== undefined && input.rosterCanPersist)
             seedFiles = [injection.indexSeed];
     }
     return { memoryEngineSession, memoryBlock, admittedOrgScopes, ownOrgVerdict, ...(memoryTools !== undefined ? { memoryTools } : {}), ...(seedFiles !== undefined ? { seedFiles } : {}) };

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

@@ -352,6 +352,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         e.code = "config.tool_materialize_invalid";
         throw e;
     }
+    if (spec.memoryPersistenceCapable !== undefined && typeof spec.memoryPersistenceCapable !== "boolean") {
+        const e = new Error(`memoryPersistenceCapable must be a boolean when present (got ${JSON.stringify(spec.memoryPersistenceCapable)}) — a non-boolean would silently read as capable.`);
+        e.code = "config.memory_persistence_invalid";
+        throw e;
+    }
     if (spec.toolMaterializeStrategy === "static" && spec.deferSelfResolve === false) {
         const e = new Error(`toolMaterializeStrategy "static" cannot be combined with deferSelfResolve: false — with the direct-call ` +
             `lane disabled a placeholder is never swapped and never self-resolves, so no deferred tool could ever be ` +
@@ -1154,6 +1159,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             ...(spec.additionalDirectories !== undefined ? { additionalDirectories: Object.freeze([...spec.additionalDirectories]) } : {}),
             ...(spec.additionalReadDirectories !== undefined ? { additionalReadDirectories: Object.freeze([...spec.additionalReadDirectories]) } : {}),
             ...(spec.envFacts !== undefined ? { envFacts: { ...spec.envFacts } } : {}),
+            ...(spec.memoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: spec.memoryPersistenceCapable } : {}),
             getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
             parentCwd: taskRootPath,
             ...(centerAdoption !== undefined ? { centerArtifactDigest: centerAdoption.artifact.artifactDigest } : {}),
@@ -1687,20 +1693,24 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     `Set spec.shellGate to "classify" or "always" if this deployment expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
             }
             if (shellGate !== "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
-                shellGatedBash = !egressTools.has("Bash") && !irreversibilityTier.has("Bash");
-                irreversibilityTier.set("Bash", shellGate === "always" ? "always" : "maybe");
+                const bashTierBefore = irreversibilityTier.get("Bash");
+                shellGatedBash = !egressTools.has("Bash") && bashTierBefore !== "always" && bashTierBefore !== "maybe";
+                const bashEffectiveTier = shellGate === "always" || bashTierBefore === "always" ? "always" : "maybe";
+                irreversibilityTier.set("Bash", bashEffectiveTier);
                 irreversibleTools.add("Bash");
                 const shellReadBoundary = () => ({
                     roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
                     ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
                 });
-                if (shellGate === "classify")
+                if (shellGate === "classify" && shellGatedBash)
                     reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
                 if (backgroundTaskToolsActive) {
-                    shellGatedMonitor = !egressTools.has("Monitor") && !irreversibilityTier.has("Monitor");
-                    irreversibilityTier.set("Monitor", shellGate === "always" ? "always" : "maybe");
+                    const monitorTierBefore = irreversibilityTier.get("Monitor");
+                    shellGatedMonitor = !egressTools.has("Monitor") && monitorTierBefore !== "always" && monitorTierBefore !== "maybe";
+                    const monitorEffectiveTier = shellGate === "always" || monitorTierBefore === "always" ? "always" : "maybe";
+                    irreversibilityTier.set("Monitor", monitorEffectiveTier);
                     irreversibleTools.add("Monitor");
-                    if (shellGate === "classify")
+                    if (shellGate === "classify" && shellGatedMonitor)
                         reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
                 }
             }
@@ -1936,7 +1946,21 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             sessionId,
             taskRootPath,
             memoryWriteGateRef,
-            writeToolsMounted: tools.some((t) => t.name === "Write") && !(toolFaceSnapshot.exclude?.includes("Write") ?? false),
+            writeToolsMounted: tools.some((t) => t.name === "Write") &&
+                !(toolFaceSnapshot.exclude?.includes("Write") ?? false) &&
+                !(handsEnabled && isRemoteExecutionEnv(executionEnv) && spec.memoryPersistenceCapable !== true),
+            memoryPersistenceDeclared: spec.memoryPersistenceCapable,
+            rosterCanPersist: spec.memoryPersistenceCapable ??
+                tools.some((t) => {
+                    if (toolFaceSnapshot.exclude?.includes(t.name) ?? false)
+                        return false;
+                    const effect = (t.effect ?? toolEffects.get(t.name) ?? "write");
+                    if (effect === "read")
+                        return false;
+                    if (t.name !== "Write" && t.name !== "Edit" && t.name !== "NotebookEdit" && t.name !== "Bash")
+                        return false;
+                    return !(handsEnabled && isRemoteExecutionEnv(executionEnv));
+                }),
             memorySearchToolsPlanned,
             admissionCtx: {
                 orgMemoryDenied: complianceDenies.has("org_memory_mount"),

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

@@ -12,5 +12,11 @@ import { type ContractAssertionRunner } from "./contract-harness.js";
  * with a narrower native key space owns an injective encoding, not a rejection). Before 2.1.0 the
  * bundled backends genuinely diverged on both halves (dev-green / deployment-red), so running this
  * kit against a pre-2.1.0-modeled backend is expected to go red on those two entries.
+ *
+ * Backlog #119 adds the provenance leg: `put`'s third argument and the `ownerOf` read face. `ownerOf`
+ * is typed OPTIONAL on the interface (source compatibility for a backend written against an older
+ * engine), but this kit REQUIRES it — a backend that cannot say who owns a ref cannot authorize a
+ * host-side read face, and an optional parameter one store honors while another drops it silently is
+ * exactly the divergence the two legs above exist to prevent.
  */
 export declare function toolResultStoreContract(make: () => ToolResultStore, runAssertion?: ContractAssertionRunner): Promise<void>;

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

@@ -31,5 +31,29 @@ export async function toolResultStoreContract(make, runAssertion) {
         }
         assert.equal((await store.get("tr_sess_call:1")).content, "payload-tr_sess_call:1");
     });
+    run("#119 provenance: content+owner are one write; ownerOf answers; a different owner is a TYPED refusal; unowned rows stay unowned", async () => {
+        const store = make();
+        assert.equal(typeof store.ownerOf, "function", "a backend must implement ownerOf — a store that cannot say who owns a ref cannot back a host read face");
+        const ownerOf = (ref) => Promise.resolve(store.ownerOf(ref));
+        const ref = "tr_s1~c1";
+        await store.put(ref, "0123456789", { sessionId: "sess-A", taskId: "task-1" });
+        assert.deepEqual(await ownerOf(ref), { sessionId: "sess-A", taskId: "task-1" }, "the winning write's owner round-trips");
+        await store.put(ref, "IGNORED", { sessionId: "sess-A", taskId: "task-1" });
+        assert.equal((await store.get(ref)).content, "0123456789");
+        assert.deepEqual(await ownerOf(ref), { sessionId: "sess-A", taskId: "task-1" });
+        await store.put(ref, "IGNORED");
+        assert.deepEqual(await ownerOf(ref), { sessionId: "sess-A", taskId: "task-1" }, "an ownerless put must not clear the owner");
+        for (const other of [{ sessionId: "sess-B" }, { sessionId: "sess-A", taskId: "task-2" }]) {
+            await assert.rejects((async () => store.put(ref, "other tenant's bytes", other))(), (err) => err.code === "tool_result.ref_conflict", `put(${JSON.stringify(other)}) on an occupied ref must reject with code tool_result.ref_conflict`);
+        }
+        assert.equal((await store.get(ref)).content, "0123456789", "a refused put must not have overwritten anything");
+        const unowned = "tr_no_owner~c";
+        await store.put(unowned, "bytes from a write site that stated no owner");
+        assert.equal(await ownerOf(unowned), undefined, "a row stored without provenance is UNOWNED");
+        await store.put(unowned, "bytes from a write site that stated no owner", { sessionId: "sess-A" });
+        assert.equal(await ownerOf(unowned), undefined, "put must not back-fill an owner onto an unowned row");
+        assert.equal((await store.get(unowned)).content, "bytes from a write site that stated no owner");
+        assert.equal(await ownerOf("tr_never~written"), undefined);
+    });
     await settle();
 }

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

@@ -6,7 +6,7 @@ import { shutdownDebug } from "./shutdown-debug.js";
 import { delimitUntrusted } from "./untrusted-text.js";
 import { boundedRedactedSummary } from "./untrusted-egress.js";
 import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
-import { buildToolResultRef, OFFLOAD_TOOL_NAME } from "./tool-result-store.js";
+import { buildToolResultRef, OFFLOAD_TOOL_NAME, toolResultProvenanceOf } from "./tool-result-store.js";
 export function ensureDurableHeartbeatLane(core) {
     if (core.durableHeartbeatTimer !== undefined)
         return;
@@ -1232,8 +1232,8 @@ export async function spillClippedAgentResult(handle, full, clipped, store, sess
     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);
+        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;
     }
     return `${clipped}\n\n[full output persisted — call ${OFFLOAD_TOOL_NAME} with ref "${handle.spillRef}" to read it back.]`;

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

@@ -1,6 +1,6 @@
 import { delimitUntrusted } from "./untrusted-text.js";
 import { assertOwnership, defaultMonitorTimers, MONITOR_MAX_TIMEOUT_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_BATCH_WINDOW_MS, MONITOR_MAX_BATCHES_PER_MINUTE, MONITOR_STORM_BURST, MONITOR_STORM_KILL_AFTER_MS, MONITOR_LINE_BUF_CAP, MONITOR_SPILL_CAP_CHARS, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, clipMonitorLine, terminalTaskSummary, accountDroppedBytes, renderSpoolBody, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.js";
-import { buildToolResultRef, OFFLOAD_TOOL_NAME } from "./tool-result-store.js";
+import { buildToolResultRef, OFFLOAD_TOOL_NAME, toolResultProvenanceOf } from "./tool-result-store.js";
 export function registerMonitorLane(core, input) {
     assertOwnership(input, "registerMonitor");
     const id = core.mintTaskId("monitor");
@@ -61,14 +61,15 @@ function spillRolledMonitorChunk(handle, stream, dropped) {
         return;
     }
     const n = stream === "out" ? (handle.spillSegCount ?? 0) : (handle.spillErrSegCount ?? 0);
-    const ref = buildToolResultRef(handle.spillSessionId ?? "no-session", `${handle.id}_${stream}_seg${n}`);
+    const ref = buildToolResultRef(handle.spillSessionId ?? "no-session", handle.id, `${stream}_seg${n}`);
     handle.spillCharsUsed = used + dropped.length;
     if (stream === "out")
         handle.spillSegCount = n + 1;
     else
         handle.spillErrSegCount = n + 1;
     try {
-        void Promise.resolve(store.put(ref, dropped)).catch(() => {
+        const provenance = handle.spillSessionId === undefined ? undefined : toolResultProvenanceOf(handle.spillSessionId, handle.id);
+        void Promise.resolve(store.put(ref, dropped, provenance)).catch(() => {
             handle.spillFailed = true;
         });
     }
@@ -83,8 +84,8 @@ function monitorSpillNote(handle) {
         return "";
     const sid = handle.spillSessionId ?? "no-session";
     const segLabel = (stream, n) => {
-        const first = buildToolResultRef(sid, `${handle.id}_${stream}_seg0`);
-        return n <= 1 ? `ref "${first}"` : `refs "${first}" .. "${buildToolResultRef(sid, `${handle.id}_${stream}_seg${n - 1}`)}"`;
+        const first = buildToolResultRef(sid, handle.id, `${stream}_seg0`);
+        return n <= 1 ? `ref "${first}"` : `refs "${first}" .. "${buildToolResultRef(sid, handle.id, `${stream}_seg${n - 1}`)}"`;
     };
     const clauses = [];
     if (outN > 0)

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

@@ -10,7 +10,7 @@ import { type ToolResultStore } from "./tool-result-store.js";
  * **Simpler than CC by construction (§24.2):** a request-only, non-destructive transform (returns a new
  * array; the durable session keeps full results) applied in the existing `harness.on("context")` hook —
  * the same per-query point as `clearStaleToolResults` (the mirror of CC's query.ts:379). It is DETERMINISTIC
- * (stable `ref = tr_<sessionId>_<toolCallId>` + deterministic {@link buildPreview}), so re-running it every
+ * (stable `ref = tr_<sessionId>~<toolCallId>` + deterministic {@link buildPreview}), so re-running it every
  * query yields byte-identical previews → prompt-cache safe **without** CC's ContentReplacementState freeze
  * machine (the determinism IS the freeze), and resume-free (the transcript holds originals; this re-applies
  * on replay). Reuses design/30's offload store + preview format; with no store it falls back to a

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

@@ -1,5 +1,5 @@
 import { isToolResult } from "./message-utils.js";
-import { buildPreview, buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX } from "./tool-result-store.js";
+import { buildPreview, buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX, toolResultContentSegment, toolResultProvenanceOf, } from "./tool-result-store.js";
 export const AGGREGATE_TOOL_RESULT_BUDGET_CHARS = 200_000;
 const HEAD = 1_000;
 const TAIL = 1_000;
@@ -61,13 +61,13 @@ export async function capAggregateToolResults(messages, opts) {
             const previewOne = async (k, before, head, tail, fromOriginal) => {
                 const m = out[k];
                 const full = textOf((fromOriginal ? messages[k] : m).content);
-                const ref = buildToolResultRef(opts.sessionId, m.toolCallId ?? `idx${k}`);
+                const ref = buildToolResultRef(opts.sessionId, m.toolCallId ?? `idx${k}`, toolResultContentSegment(full));
                 const sizes = head === HEAD && tail === TAIL ? undefined : { head, tail };
                 let previewText;
                 let storeFallback;
                 if (opts.store) {
                     try {
-                        await opts.store.put(ref, full);
+                        await opts.store.put(ref, full, toolResultProvenanceOf(opts.sessionId));
                         previewText = buildPreview(full, ref, sizes);
                         storeFallback = false;
                     }