@sema-agent/core 2.3.0 → 2.4.0

package/dist/core/store-contracts/mailbox-store-contract.js

@@ -0,0 +1,193 @@
+import { strict as assert } from "node:assert";
+import { beginContract } from "./contract-harness.js";
+export const MAILBOX_CONTRACT_SCOPE = "default";
+const msg = (content, sentAt = 1000) => ({ content, sentAt });
+async function withStores(mk, fn) {
+    const live = [];
+    const make = () => {
+        const s = mk();
+        live.push(s);
+        return s;
+    };
+    try {
+        await fn(make);
+    }
+    finally {
+        for (const s of live.splice(0))
+            s.close?.();
+    }
+}
+export async function mailboxStoreContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    const S = MAILBOX_CONTRACT_SCOPE;
+    run("append 铸单调 seq;claimLease 取全部可见消息(不删);ack 才删;活租约=单消费者", async (make) => {
+        const s = make();
+        assert.equal(await s.append(S, "a1", msg("m1")), 1);
+        assert.equal(await s.append(S, "a1", msg("m2")), 2);
+        assert.equal(await s.peekCount(S, "a1"), 2);
+        const lease = await s.claimLease(S, "a1", "w1", 60_000, 10_000);
+        assert.deepEqual(lease.messages.map((m) => m.content), ["m1", "m2"]);
+        assert.equal(lease.maxSeq, 2);
+        assert.equal(await s.claimLease(S, "a1", "w2", 60_000, 20_000), null);
+        assert.equal(await s.peekCount(S, "a1"), 2);
+        await s.ack(S, "a1", "w1", 2);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    run("X-1 无损:lease 过期/release 后消息按原 seq 回可见;seq 在箱的一生中永不复用", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const l1 = await s.claimLease(S, "a1", "w1", 1_000, 10_000);
+        assert.equal(l1.maxSeq, 1);
+        const l2 = await s.claimLease(S, "a1", "w2", 1_000, 20_000);
+        assert.deepEqual(l2.messages.map((m) => m.seq), [1]);
+        await s.releaseLease(S, "a1", "w2");
+        const l3 = await s.claimLease(S, "a1", "w3", 1_000, 20_500);
+        assert.deepEqual(l3.messages.map((m) => m.seq), [1]);
+        await s.ack(S, "a1", "w3", 1);
+        assert.equal(await s.append(S, "a1", msg("m2")), 2);
+    });
+    run("lease 窗内 append:后到消息在下次 claim 时可见(lease 只覆盖 claim 时刻快照)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const l = await s.claimLease(S, "a1", "w1", 60_000, 10_000);
+        assert.equal(l.maxSeq, 1);
+        await s.append(S, "a1", msg("m2"));
+        await s.ack(S, "a1", "w1", l.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 1);
+        const next = await s.claimLease(S, "a1", "w2", 60_000, 20_000);
+        assert.deepEqual(next.messages.map((m) => m.content), ["m2"]);
+    });
+    run("drop 清整箱;reap 按最新消息龄整箱老化", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("old", 1_000));
+        await s.append(S, "a2", msg("fresh", 90_000));
+        assert.equal(await s.reap(S, 100_000, { maxAgeMs: 50_000 }), 1);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+        assert.equal(await s.peekCount(S, "a2"), 1);
+        await s.drop(S, "a2");
+        assert.equal(await s.peekCount(S, "a2"), 0);
+    });
+    run("RB-86 空箱 ⇒ null:没消息就不发租约(既不假装投递,也不 fence 掉后来真正的消费者)", async (make) => {
+        const s = make();
+        assert.equal(await s.claimLease(S, "never-written", "o1", 60_000, 1_000), null, "从未写过的箱");
+        await s.append(S, "a1", msg("m1"));
+        const first = await s.claimLease(S, "a1", "o1", 60_000, 1_000);
+        await s.ack(S, "a1", "o1", first.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+        assert.equal(await s.claimLease(S, "a1", "o1", 60_000, 2_000), null, "全部 ack 后箱内零可见消息");
+        assert.equal(await s.claimLease(S, "a2", "ghost", 60_000, 3_000), null);
+        await s.append(S, "a2", msg("real", 4_000));
+        const real = await s.claimLease(S, "a2", "o2", 60_000, 4_000);
+        assert.deepEqual(real?.messages.map((m) => m.content), ["real"], "空取不该留下 fence 后来者的幽灵租约");
+    });
+    run("RB-261 守恒律:一条消息在被 ack 消费之前必须至少投递过一次(maxSeq 不得覆盖未投递项)", async (make) => {
+        const s = make();
+        const appended = ["m1", "m2", "m3"];
+        for (const [i, c] of appended.entries())
+            await s.append(S, "a1", msg(c, 1_000 + i));
+        const delivered = new Set();
+        let round = 0;
+        while ((await s.peekCount(S, "a1")) > 0) {
+            round += 1;
+            assert.ok(round < 10, "要么有限轮内收敛,要么就是投递不动了");
+            const owner = `w${round}`;
+            const lease = await s.claimLease(S, "a1", owner, 60_000, 10_000 + round);
+            assert.notEqual(lease, null, "还有可见消息时 claimLease 不得返回 null");
+            for (const m of lease.messages)
+                delivered.add(m.content);
+            await s.ack(S, "a1", owner, lease.maxSeq);
+        }
+        assert.deepEqual([...delivered].sort(), [...appended].sort(), "每条被消费掉的消息都必须先被投递过");
+    });
+    run("releaseLease owner-fenced:非持有者的 release 是 no-op(活租约的单消费者窗口不被外人撬开)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const held = await s.claimLease(S, "a1", "owner-A", 60_000, 10_000);
+        assert.equal(held.messages.length, 1);
+        await s.releaseLease(S, "a1", "not-the-owner");
+        assert.equal(await s.claimLease(S, "a1", "rival", 60_000, 11_000), null, "A 的活租约必须仍然 fence 住 rival");
+        await s.releaseLease(S, "a1", "owner-A");
+        const after = await s.claimLease(S, "a1", "rival", 60_000, 12_000);
+        assert.deepEqual(after?.messages.map((m) => m.seq), [1], "归还后同一条按原 seq 回可见");
+    });
+    await settle();
+}
+export async function mailboxAckOwnershipContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    const S = MAILBOX_CONTRACT_SCOPE;
+    run("a non-holder's ack does not delete messages held under another owner's LIVE lease", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.append(S, "a1", { content: "m2", sentAt: 2 });
+        const lease = await s.claimLease(S, "a1", "consumer-A", 60_000, 10_000);
+        assert.equal(lease?.messages.length, 2);
+        await s.ack(S, "a1", "stale-actor", lease.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 2, "the messages must survive — this caller never held the lease");
+    });
+    run("angle 4 — internal consistency: releaseLease and ack now apply the SAME owner fence (was the asymmetry that proved this was an oversight)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.claimLease(S, "a1", "real-owner", 60_000, 10_000);
+        await s.releaseLease(S, "a1", "wrong-owner");
+        await s.ack(S, "a1", "wrong-owner", 1);
+        assert.equal(await s.peekCount(S, "a1"), 1, "neither operation should have touched anything");
+    });
+    run("angle 5 — ack with no lease EVER claimed is a no-op, not a silent wipe", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.ack(S, "a1", "nobody", Number.MAX_SAFE_INTEGER);
+        assert.equal(await s.peekCount(S, "a1"), 1);
+    });
+    run("the legitimate holder's own ack still works (regression check — the fix must not break the happy path)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "m1", sentAt: 1 });
+        await s.append(S, "a1", { content: "m2", sentAt: 2 });
+        const lease = await s.claimLease(S, "a1", "consumer-A", 60_000, 10_000);
+        await s.ack(S, "a1", "consumer-A", lease.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    run("angle 3 in detail — the real loss sequence (stale owner outlives its own expired lease, a NEW owner has since taken over): the new owner's custody survives", async (make) => {
+        const s = make();
+        await s.append(S, "a1", { content: "ship-the-release", sentAt: 1 });
+        await s.append(S, "a1", { content: "notify-oncall", sentAt: 2 });
+        const leaseA = await s.claimLease(S, "a1", "consumer-A", 1_000, 1_000);
+        assert.equal(leaseA?.messages.length, 2);
+        const leaseB = await s.claimLease(S, "a1", "consumer-B", 60_000, 5_000);
+        assert.equal(leaseB?.messages.length, 2);
+        await s.ack(S, "a1", "consumer-A", leaseA.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 2, "B's live custody must survive A's stale ack");
+        await s.ack(S, "a1", "consumer-B", leaseB.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    await settle();
+}
+export async function mailboxBundledOnlyContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    run("RB-251(黑板 [1937]):handle 含 NUL 被两个后端一致拒绝,且不得跨 (scope,handle) 串箱", async (make) => {
+        const s = make();
+        const NUL = String.fromCharCode(0);
+        await assert.rejects(s.append("s", `a${NUL}b`, msg("secret")));
+        assert.equal(await s.peekCount(`s${NUL}a`, "b"), 0, "歧义键下不得出现串箱可读");
+        await s.append("s", "plain", msg("ok"));
+        assert.equal(await s.peekCount("s", "plain"), 1);
+    });
+    run("多租户:同名 handle 在不同 scope 下是两个互不可见的箱(各自独立铸 seq)", async (make) => {
+        const s = make();
+        assert.equal(await s.append("tenant-a", "shared-handle", msg("for-a")), 1);
+        assert.equal(await s.append("tenant-b", "shared-handle", msg("for-b")), 1, "另一个 scope 的箱独立铸号");
+        assert.equal(await s.peekCount("tenant-a", "shared-handle"), 1);
+        const a = await s.claimLease("tenant-a", "shared-handle", "w", 60_000, 10_000);
+        assert.deepEqual(a.messages.map((m) => m.content), ["for-a"]);
+        const b = await s.claimLease("tenant-b", "shared-handle", "w", 60_000, 10_000);
+        assert.deepEqual(b.messages.map((m) => m.content), ["for-b"]);
+        await s.ack("tenant-a", "shared-handle", "w", a.maxSeq);
+        assert.equal(await s.peekCount("tenant-a", "shared-handle"), 0);
+        assert.equal(await s.peekCount("tenant-b", "shared-handle"), 1, "跨 scope 的 ack 不得越界");
+        await s.drop("tenant-b", "shared-handle");
+        assert.equal(await s.peekCount("tenant-b", "shared-handle"), 0);
+    });
+    await settle();
+}

package/dist/core/store-contracts/session-repo-contract.d.ts

@@ -0,0 +1,3 @@
+import type { SessionRepo } from "../../internal/harness-types.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function sessionRepoContract(make: () => SessionRepo, runAssertion?: ContractAssertionRunner): Promise<void>;

package/dist/core/store-contracts/session-repo-contract.js

@@ -0,0 +1,36 @@
+import { strict as assert } from "node:assert";
+import { beginContract } from "./contract-harness.js";
+const SESSION_ENTRY = (id, parentId) => ({
+    id,
+    parentId,
+    type: "message",
+    timestamp: "2026-07-30T00:00:00.000Z",
+    message: { role: "user", content: [{ type: "text", text: `t-${id}` }], timestamp: 1785340800000 },
+});
+export async function sessionRepoContract(make, runAssertion) {
+    const { run, settle } = beginContract(runAssertion);
+    const A = "0198fa00-0000-7000-8000-00000000000a";
+    run("RB-360 create({id}) on an id that ALREADY has history is an idempotent REOPEN — never a wipe", async () => {
+        const repo = make();
+        const sess = await repo.create({ id: A });
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e2", "e1"));
+        const again = await repo.create({ id: A });
+        const entries = await again.getStorage().getEntries();
+        assert.deepEqual(entries.map((e) => e.id), ["e1", "e2"]);
+        const exported = (await repo.exportEntries?.(A)) ?? [];
+        assert.deepEqual(exported.map((e) => e.id), ["e1", "e2"]);
+    });
+    run("create({id}) fresh → open() sees appended entries (round-trip floor)", async () => {
+        const repo = make();
+        const sess = await repo.create({ id: A });
+        await sess.getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        const opened = await repo.open({ id: A, createdAt: "" });
+        assert.deepEqual((await opened.getStorage().getEntries()).map((e) => e.id), ["e1"]);
+    });
+    run("open(missing) throws not_found — never a silent create", async () => {
+        const repo = make();
+        await assert.rejects(repo.open({ id: "0198fa00-0000-7000-8000-0000000000ff", createdAt: "" }), /not.?found/i);
+    });
+    await settle();
+}

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

@@ -0,0 +1,3 @@
+import type { ToolResultStore } from "../tool-result-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function toolResultStoreContract(make: () => ToolResultStore, runAssertion?: ContractAssertionRunner): Promise<void>;

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

@@ -0,0 +1,35 @@
+import { strict as assert } from "node:assert";
+import { beginContract } from "./contract-harness.js";
+export async function toolResultStoreContract(make, runAssertion) {
+    const { run, settle } = beginContract(runAssertion);
+    run("put/get full + sliced; write-once no-op; unknown → undefined", async () => {
+        const store = make();
+        const ref = "tr_s_c";
+        await store.put(ref, "0123456789");
+        assert.deepEqual(await store.get(ref), { content: "0123456789", offset: 0, totalChars: 10 });
+        assert.deepEqual(await store.get(ref, { offset: 2, limit: 3 }), { content: "234", offset: 2, totalChars: 10 });
+        await store.put(ref, "IGNORED");
+        assert.equal((await store.get(ref)).content, "0123456789");
+        assert.equal(await store.get("tr_unknown"), undefined);
+    });
+    run("RB-266 unsafe refs are rejected at the WRITE by every backend; the read face degrades instead", async () => {
+        const store = make();
+        const NUL = String.fromCharCode(0);
+        const unsafe = ["", ".", "..", "a/b", "../escape", "dir\\ref", `tr_x${NUL}y`];
+        for (const ref of unsafe) {
+            await assert.rejects((async () => store.put(ref, "payload"))(), `put(${JSON.stringify(ref)}) must reject — a durable backend cannot key it`);
+            assert.equal(await store.get(ref), undefined, "get of an unsafe ref degrades to undefined");
+        }
+        await store.put("tr_sess-1_call.7", "ok");
+        assert.equal((await store.get("tr_sess-1_call.7")).content, "ok");
+    });
+    run("RB-273 a ref the contract ACCEPTS round-trips on every backend (no backend is stricter than the rule)", async () => {
+        const store = make();
+        for (const ref of ["tr_sess_call:1", "tr_sess_call%2F1", "tr_sess_call 1", "tr_sess_日本語"]) {
+            await store.put(ref, `payload-${ref}`);
+            assert.equal((await store.get(ref))?.content, `payload-${ref}`, `put(${JSON.stringify(ref)}) must round-trip here`);
+        }
+        assert.equal((await store.get("tr_sess_call:1")).content, "payload-tr_sess_call:1");
+    });
+    await settle();
+}

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

@@ -10,6 +10,8 @@ export interface TaskNotificationPayload {
     source?: string;
     stoppedBy?: "user" | "parent" | "system" | (string & {});
     summary: string;
+    error?: string;
+    errorCode?: string;
     exitCode?: number;
     result?: string;
     partial?: boolean;

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

@@ -66,6 +66,8 @@ export declare function settleBackgroundAgentLane(core: DurableAgentCore, id: st
     result?: string;
     resultFull?: string;
     error?: string;
+    errorCode?: string;
+    retryable?: boolean;
     stoppedBy?: StopSource;
     seq?: number;
 }): "completed" | "failed" | "killed" | undefined;
@@ -98,6 +100,8 @@ export declare function settleRevivedAgentLane(core: DurableAgentCore, id: strin
     result?: string;
     resultFull?: string;
     error?: string;
+    errorCode?: string;
+    retryable?: boolean;
 }): "completed" | "failed" | "killed" | undefined;
 export declare function unmarkRetainedContinuationLane(core: DurableAgentCore, id: string): void;
 export declare function attachAgentNotifyLane(core: DurableAgentCore, id: string, notify: NonNullable<BackgroundAgentTaskHandle["notify"]>, cycle?: number): void;

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

@@ -3,6 +3,7 @@ import { uuidv7 } from "../internal/harness.js";
 import { canAccessAgentRecord, BackgroundAgentStoreError, } from "./background-agent-store.js";
 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";
 export function ensureDurableHeartbeatLane(core) {
@@ -636,6 +637,7 @@ export async function consumeParkedFlipLane(core, id, stores, ticket) {
     handle.resolveParkedStop = undefined;
     handle.updatedAt = Date.now();
     handle.completionId = undefined;
+    handle.terminalNotified = undefined;
     if (flipped.seq !== undefined)
         handle.cycleSeq = flipped.seq;
     return true;
@@ -681,6 +683,7 @@ export function settleBackgroundAgentLane(core, id, outcome) {
     handle.status = outcome.status;
     mintCompletionId(handle);
     handle.notify = undefined;
+    handle.onReapTerminal = undefined;
     for (const [, , qResolve] of handle.preAttachQueue ?? [])
         qResolve?.({ ok: false, reason: "not_running" });
     handle.preAttachQueue = undefined;
@@ -699,6 +702,10 @@ export function settleBackgroundAgentLane(core, id, outcome) {
     }
     if (outcome.error !== undefined && !(outcome.status === "killed" && outcome.error === BG_AGENT_REAP_STOP_ERROR)) {
         handle.error = outcome.error;
+        if (outcome.errorCode !== undefined)
+            handle.errorCode = outcome.errorCode;
+        if (outcome.retryable !== undefined)
+            handle.errorRetryable = outcome.retryable;
     }
     handle.updatedAt = Date.now();
     if (outcome.seq !== undefined)
@@ -840,6 +847,7 @@ export function reviveBackgroundAgentLane(core, id, access, abort) {
     handle.resultIsPartial = undefined;
     handle.stopSource = undefined;
     handle.completionId = undefined;
+    handle.terminalNotified = undefined;
     handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;
     handle.cycleSeq = (handle.cycleSeq ?? 1) + 1;
     handle.updatedAt = Date.now();
@@ -1076,6 +1084,11 @@ ${resultText}` : "(no result text)"}`;
             retrieval_status: retrieval,
             ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
             ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            ...(handle.status === "failed" && handle.error !== undefined
+                ? { error: delimitUntrusted("agent error", boundedRedactedSummary(handle.error, 300)) }
+                : {}),
+            ...(handle.status === "failed" && handle.errorCode !== undefined ? { errorCode: handle.errorCode } : {}),
+            ...(handle.status === "failed" && handle.errorRetryable !== undefined ? { retryable: handle.errorRetryable } : {}),
             ...(handle.resultIsPartial ? { partial_result: true } : {}),
             ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
         },

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

@@ -1,5 +1,5 @@
 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_BYTES, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, clipMonitorLine, terminalTaskSummary, accountDroppedBytes, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.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, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.js";
 import { buildToolResultRef, OFFLOAD_TOOL_NAME } from "./tool-result-store.js";
 export function registerMonitorLane(core, input) {
     assertOwnership(input, "registerMonitor");
@@ -49,14 +49,14 @@ function spillRolledMonitorChunk(handle, stream, dropped) {
     const store = handle.toolResultStore;
     if (store === undefined)
         return;
-    const used = handle.spillBytesUsed ?? 0;
-    if (used >= MONITOR_SPILL_CAP_BYTES) {
+    const used = handle.spillCharsUsed ?? 0;
+    if (used >= MONITOR_SPILL_CAP_CHARS) {
         handle.spillCapped = true;
         return;
     }
     const n = stream === "out" ? (handle.spillSegCount ?? 0) : (handle.spillErrSegCount ?? 0);
     const ref = buildToolResultRef(handle.spillSessionId ?? "no-session", `${handle.id}_${stream}_seg${n}`);
-    handle.spillBytesUsed = used + dropped.length;
+    handle.spillCharsUsed = used + dropped.length;
     if (stream === "out")
         handle.spillSegCount = n + 1;
     else
@@ -88,7 +88,7 @@ function monitorSpillNote(handle) {
     const coverage = handle.spillFailed === true
         ? " — a write failed partway through; the ref chain may be INCOMPLETE, read what is there"
         : handle.spillCapped === true
-            ? ` — spill cap (${MONITOR_SPILL_CAP_BYTES} bytes) reached; earlier segments retained, later rolls were not spilled`
+            ? ` — spill cap (${MONITOR_SPILL_CAP_CHARS} chars) reached; earlier segments retained, later rolls were not spilled`
             : "";
     return `; spilled to ${clauses.join(", ")} (read back via ${OFFLOAD_TOOL_NAME})${coverage}`;
 }
@@ -359,7 +359,7 @@ function explicitStopTerminalNote(handle, alreadyGone) {
         task_type: "monitor",
         ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
         status: "killed",
-        stoppedBy: handle.stoppedBy,
+        ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
         summary: `${terminalTaskSummary("monitor", label, "killed")} — ${detail}${droppedGapNote(handle.spool)}`,
         ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
     });

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

@@ -16,6 +16,8 @@ export interface UnifiedTaskOutput {
     retrieval_status: TaskRetrievalStatus;
     content?: string;
     error?: string;
+    errorCode?: string;
+    retryable?: boolean;
     stoppedBy?: StopSource;
     seq?: number;
     partial_result?: boolean;
@@ -135,9 +137,13 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
     resultFull?: string;
     spillRef?: string;
     error?: string;
+    errorCode?: string;
+    errorRetryable?: boolean;
     resultIsPartial?: boolean;
     stopSource?: StopSource;
     stoppedBy?: StopSource;
+    onReapTerminal?: () => void;
+    terminalNotified?: true;
 }
 export interface MonitorTimers {
     setInterval: (fn: () => unknown, ms: number) => unknown;
@@ -188,7 +194,7 @@ export interface MonitorTaskHandle extends SemaTaskHandle {
     spillSessionId?: string;
     spillSegCount?: number;
     spillErrSegCount?: number;
-    spillBytesUsed?: number;
+    spillCharsUsed?: number;
     spillCapped?: true;
     spillFailed?: true;
 }
@@ -237,7 +243,7 @@ export declare function statusFromBackground(status: string, exitCode?: number):
 export declare function rollSpoolText(spool: {
     rolledChars: number;
 }, s: string, cap: number, onDrop?: (dropped: string) => void): string;
-export declare const MONITOR_SPILL_CAP_BYTES: number;
+export declare const MONITOR_SPILL_CAP_CHARS: number;
 export declare function accountDroppedBytes(spool: {
     droppedBytes?: number;
     dropUnknown?: true;

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

@@ -94,7 +94,7 @@ export function rollSpoolText(spool, s, cap, onDrop) {
     onDrop?.(dropped);
     return s.slice(0, half) + s.slice(s.length - half);
 }
-export const MONITOR_SPILL_CAP_BYTES = 64 * 1024 * 1024;
+export const MONITOR_SPILL_CAP_CHARS = 64 * 1024 * 1024;
 export function accountDroppedBytes(spool, poll) {
     const d = poll.bytesDroppedBeforeCursor ?? 0;
     if (d > 0)

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

@@ -133,6 +133,8 @@ export declare class TaskRegistry {
         result?: string;
         resultFull?: string;
         error?: string;
+        errorCode?: string;
+        retryable?: boolean;
         stoppedBy?: StopSource;
         seq?: number;
     }): "completed" | "failed" | "killed" | undefined;
@@ -166,9 +168,13 @@ export declare class TaskRegistry {
         result?: string;
         resultFull?: string;
         error?: string;
+        errorCode?: string;
+        retryable?: boolean;
     }): "completed" | "failed" | "killed" | undefined;
     unmarkRetainedContinuation(id: string): void;
     attachAgentNotify(id: string, notify: NonNullable<BackgroundAgentTaskHandle["notify"]>, cycle?: number): void;
+    attachAgentTerminalNotifier(id: string, fn: () => void): void;
+    claimAgentTerminalNotify(id: string): boolean;
     deliverToRunningAgent(id: string, access: TaskAccess, notification: import("./task-notification.js").TaskNotificationPayload, opts?: {
         priority?: import("./task-notification.js").SystemInjectionPriority;
     }): Promise<{

package/dist/core/task-registry.js

@@ -52,6 +52,23 @@ function bashMirrorGapNote(handle) {
         ? " [!] The output file is INCOMPLETE (one or more writes to it failed) — trust the result text / TaskOutput over the file."
         : "";
 }
+function explicitStopBashTerminalNote(handle, alreadyGone) {
+    const resultText = handle.spool !== undefined ? bashTerminalResult(handle.spool) : "";
+    const detail = alreadyGone
+        ? "killed before completion (stopped via TaskStop; the process was already gone)"
+        : "killed before completion (stopped via TaskStop)";
+    handle.onTerminal?.({
+        task_id: handle.id,
+        task_type: "background_bash",
+        ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
+        ...(handle.outputFile !== undefined ? { output_file: handle.outputFile } : {}),
+        status: "killed",
+        ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+        summary: `${terminalTaskSummary("bash", (handle.description ?? "background command").slice(0, 200), "killed")} — ${detail}${bashMirrorGapNote(handle)}${handle.spool !== undefined ? droppedGapNote(handle.spool) : ""}`,
+        ...(resultText.length > 0 ? { result: resultText, partial: true } : {}),
+        ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+    });
+}
 function monitorInTimeoutWindow(handle) {
     return handle.status === "running" && handle.deadlineAt !== undefined && handle.timers.now() < handle.deadlineAt;
 }
@@ -145,6 +162,23 @@ export class TaskRegistry {
     attachAgentNotify(id, notify, cycle) {
         return attachAgentNotifyLane(this.core, id, notify, cycle);
     }
+    attachAgentTerminalNotifier(id, fn) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "background_agent")
+            return;
+        if (handle.status !== "running" && handle.status !== "parked" && handle.status !== "pending")
+            return;
+        handle.onReapTerminal = fn;
+    }
+    claimAgentTerminalNotify(id) {
+        const handle = this.handles.get(id);
+        if (!handle || handle.type !== "background_agent")
+            return true;
+        if (handle.terminalNotified === true)
+            return false;
+        handle.terminalNotified = true;
+        return true;
+    }
     async deliverToRunningAgent(id, access, notification, opts) {
         return deliverToRunningAgentLane(this.core, id, access, notification, opts);
     }
@@ -471,8 +505,17 @@ export class TaskRegistry {
             if (!canAccess(handle, access))
                 continue;
             this.markStopSource(handle.id, "system");
+            const reapTerminalNote = handle.onReapTerminal;
             handle.abort.abort();
             this.settleBackgroundAgent(handle.id, { status: "killed", error: "session released" });
+            if (reapTerminalNote !== undefined && handle.terminalNotified !== true) {
+                handle.terminalNotified = true;
+                try {
+                    reapTerminalNote();
+                }
+                catch {
+                }
+            }
             reaped++;
         }
         this.pokeBgQuiescence(sessionId);
@@ -1122,7 +1165,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                 handle.status = "killed";
                 handle.updatedAt = Date.now();
                 mintCompletionId(handle);
-                this.pokeBgQuiescence(handle.owner);
+                this.notifyTerminalOnce(handle, () => explicitStopBashTerminalNote(handle, true));
                 return {
                     content: `Terminated ${handle.id} (the process was already gone).`,
                     details: {
@@ -1151,7 +1194,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
         handle.status = "killed";
         handle.updatedAt = Date.now();
         mintCompletionId(handle);
-        this.pokeBgQuiescence(handle.owner);
+        this.notifyTerminalOnce(handle, () => explicitStopBashTerminalNote(handle, false));
         return {
             content: `Terminated ${handle.id}.`,
             details: {
@@ -1193,9 +1236,10 @@ export function createTaskOutputTool(opts) {
             let effectiveTimeoutMs = requestedMs;
             let waitClampNote = "";
             const wall = opts.deadlineMs?.();
+            const requestedWaitMs = Math.max(1, Math.floor(requestedMs ?? BLOCK_DEFAULT_TIMEOUT_MS));
             if (args.block !== false && wall !== undefined) {
                 const remainMs = wall - Date.now() - BLOCK_WAIT_WRITEOUT_RESERVE_MS;
-                const wantMs = Math.min(BLOCK_MAX_TIMEOUT_MS, Math.max(1, Math.floor(requestedMs ?? BLOCK_DEFAULT_TIMEOUT_MS)));
+                const wantMs = Math.min(BLOCK_MAX_TIMEOUT_MS, requestedWaitMs);
                 if (remainMs <= 0) {
                     effectiveTimeoutMs = 1;
                     waitClampNote =
@@ -1203,7 +1247,7 @@ export function createTaskOutputTool(opts) {
                 }
                 else if (remainMs < wantMs) {
                     effectiveTimeoutMs = remainMs;
-                    waitClampNote = `\n\nNOTE: wait clamped to ${Math.round(remainMs / 1000)}s (requested ${Math.round(wantMs / 1000)}s) — the task's wall-clock deadline is near. If the task is still running after this wait, do NOT re-wait: proceed with other work or write out your results now.`;
+                    waitClampNote = `\n\nNOTE: wait clamped to ${Math.round(remainMs / 1000)}s (requested ${Math.round(requestedWaitMs / 1000)}s) — the task's wall-clock deadline is near. If the task is still running after this wait, do NOT re-wait: proceed with other work or write out your results now.`;
                 }
             }
             const r = await opts.registry.pollTask(id, { owner: ctx.taskId ?? opts.owner, scope: ctx.principal ?? opts.scope, ...((ctx.sessionId ?? opts.sessionId) !== undefined ? { sessionId: ctx.sessionId ?? opts.sessionId } : {}) }, {

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

@@ -45,6 +45,7 @@ export declare class ScopedToolResultStore implements ToolResultStore {
 }
 export declare function isVolatileOffloadStore(store: ToolResultStore): boolean;
 export declare const OFFLOAD_TOOL_NAME = "ReadToolResult";
+export declare function offloadPagebackHint(ref: string, form: "preview" | "cleared", reachableTools?: ReadonlySet<string>): string;
 export declare const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
 export declare const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20000;
 export declare function firstPartyOffloadPolicy(toolName: string): {
@@ -54,6 +55,6 @@ export declare function firstPartyOffloadPolicy(toolName: string): {
 export declare function buildPreview(full: string, ref: string, sizes?: {
     head: number;
     tail: number;
-}): string;
-export declare function withToolResultOffload(tool: AgentTool, store: ToolResultStore, thresholdChars: number, sessionId: string): AgentTool;
+}, reachableTools?: ReadonlySet<string>): string;
+export declare function withToolResultOffload(tool: AgentTool, store: ToolResultStore, thresholdChars: number, sessionId: string, reachableTools?: () => ReadonlySet<string> | undefined): AgentTool;
 export declare function createReadToolResultTool(store: ToolResultStore): AgentTool;