@sema-agent/core 7.24.3 → 7.25.0

package/dist/core/store-contracts/peer-directory-contract.js

@@ -0,0 +1,82 @@
+import { strict as assert } from "node:assert";
+import { resolvePeerSessions } from "../../agents/peer-directory.js";
+import { beginContract } from "./contract-harness.js";
+export const PEER_DIRECTORY_CONTRACT_SCOPE = "peer-kit-A";
+function row(name, sessionId, over = {}) {
+    return { schemaVersion: 1, sessionId, scope: PEER_DIRECTORY_CONTRACT_SCOPE, name, startedAt: 1_000, updatedAt: 2_000, liveness: "live", ...over };
+}
+async function withDirs(mk, fn) {
+    const live = [];
+    const make = () => {
+        const d = mk();
+        live.push(d);
+        return d;
+    };
+    try {
+        await fn(make);
+    }
+    finally {
+        for (const d of live.splice(0))
+            d.close?.();
+    }
+}
+export async function peerDirectoryContract(mk, hooks) {
+    const { run: runRaw, settle } = beginContract(hooks.runAssertion);
+    const run = (name, fn) => runRaw(name, () => withDirs(mk, fn));
+    const S = PEER_DIRECTORY_CONTRACT_SCOPE;
+    run("scope wall: a listing is the accessor's scope only", async (make) => {
+        const d = make();
+        await hooks.write(d, row("alpha", "sess-a"));
+        await hooks.write(d, row("beta", "sess-b", { scope: "peer-kit-B" }));
+        const inA = await d.listPeerSessions({ scope: S });
+        assert.deepEqual(inA.map((r) => r.sessionId), ["sess-a"], "scope A must list exactly its own row");
+        const inB = await d.listPeerSessions({ scope: "peer-kit-B" });
+        assert.deepEqual(inB.map((r) => r.sessionId), ["sess-b"]);
+        const inC = await d.listPeerSessions({ scope: "peer-kit-C" });
+        assert.equal(inC.length, 0, "an unrelated scope sees nothing");
+    });
+    run("the full set is listed (live + dead + deleted) and every listed row is a copy", async (make) => {
+        const d = make();
+        await hooks.write(d, row("alpha", "sess-a"));
+        await hooks.write(d, row("beta", "sess-b", { liveness: "dead", diedAt: 3_000 }));
+        await hooks.write(d, row("gamma", "sess-c", { liveness: "deleted", diedAt: 3_000 }));
+        const listed = await d.listPeerSessions({ scope: S });
+        assert.deepEqual([...listed.map((r) => r.sessionId)].sort(), ["sess-a", "sess-b", "sess-c"], "dead and deleted rows are MARKED, never dropped from a listing");
+        assert.deepEqual(Object.fromEntries(listed.map((r) => [r.sessionId, r.liveness])), { "sess-a": "live", "sess-b": "dead", "sess-c": "deleted" });
+        const first = listed.find((r) => r.sessionId === "sess-a");
+        first.name = "scribbled";
+        const again = await d.listPeerSessions({ scope: S });
+        assert.equal(again.find((r) => r.sessionId === "sess-a").name, "alpha", "a listed row is a copy");
+    });
+    run("the engine's resolver over the listing: live by name, dead still found, deleted refuses", async (make) => {
+        const d = make();
+        await hooks.write(d, row("alpha", "sess-a"));
+        await hooks.write(d, row("beta", "sess-b", { liveness: "dead", diedAt: 3_000 }));
+        await hooks.write(d, row("gamma", "sess-c", { liveness: "deleted", diedAt: 3_000 }));
+        const rows = await d.listPeerSessions({ scope: S });
+        const alpha = resolvePeerSessions(rows, "alpha");
+        assert.equal(alpha.status, "found");
+        const beta = resolvePeerSessions(rows, "beta");
+        assert.equal(beta.status, "found", "a dead row is the name truth offline delivery resolves through");
+        const gamma = resolvePeerSessions(rows, "gamma");
+        assert.equal(gamma.status, "deleted", "a tombstone resolves only to refuse");
+        assert.equal(resolvePeerSessions(rows, "session.sess-b").status, "found", "an address resolves to a KNOWN row");
+        assert.equal(resolvePeerSessions(rows, "session.sess-zzz").status, "not_found", "an address nobody registered is not an append target");
+    });
+    run("restorePeerSession (where implemented) is CAS-on-absent: restores an absent row, never overwrites a present one", async (make) => {
+        const d = make();
+        if (d.restorePeerSession === undefined)
+            return;
+        const restored = await d.restorePeerSession(row("alpha", "sess-a", { liveness: "dead", diedAt: 3_000 }));
+        assert.equal(restored, true, "an absent row is restored");
+        assert.deepEqual((await d.listPeerSessions({ scope: S })).map((r) => r.sessionId), ["sess-a"]);
+        await hooks.write(d, row("alpha", "sess-a", { updatedAt: 9_000 }));
+        const again = await d.restorePeerSession(row("alpha-stale", "sess-a", { liveness: "dead", diedAt: 3_000 }));
+        assert.equal(again, false, "a present row wins over a restore");
+        const current = (await d.listPeerSessions({ scope: S })).find((r) => r.sessionId === "sess-a");
+        assert.equal(current.name, "alpha");
+        assert.equal(current.liveness, "live");
+        assert.equal(current.updatedAt, 9_000, "the existing row is byte-unchanged by a losing restore");
+    });
+    await settle();
+}

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

@@ -883,6 +883,12 @@ export type TaskEvent = ({
      *  nor an agent-type — the child then keeps its taskId (NOT the raw objective, which could leak a delegated
      *  secret to a progress-scoped consumer — dual-review Q2). Sanitized (control-char-stripped, length-capped). */
     name?: string;
+    /** The EXPLICIT `Agent({name})` spawn identity of the sub-run, when the spawn carried one — the
+     *  teammate KEY, as opposed to {@link name} (the display label): the same string the fleet row's
+     *  spawn frame (`BackgroundChildEvent.spawnName`), the roster row and the child's uplink `from`
+     *  carry, so a consumer binds "@name → row" by string equality. Validated at spawn
+     *  (`^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`). ABSENT = an unnamed delegation, never a missing value. */
+    spawnName?: string;
     /**
      * The model this sub-run was PREPARED with — the resolved id, read off the leg's prepared model
      * at the mint, so it is the same value `TaskResult.model` and the `task.start` trace frame carry.

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

@@ -1,7 +1,25 @@
+import type { MailboxAppendMessage, MailboxStore } from "./mailbox-store.js";
 /** design/135 G2: `"event"` is the ONE non-terminal member — a Monitor batch notification (new stdout
  *  lines from a still-running watch). Everything else is a terminal completion notification. */
 export type TaskNotificationStatus = "completed" | "failed" | "killed" | "cancelled" | "event";
 export type SystemInjectionPriority = "now" | "next" | "later";
+/**
+ * The outcome an injection entry settles with — what the session did with the frame:
+ *  · `queued` — a live lane took it (it rides that run's next turn boundary; accepted, not yet consumed);
+ *  · `parked` — no live lane; pended IN PROCESS on {@link PendingSessionNotifications} for the
+ *    session's next run in this process (a process restart loses it);
+ *  · `parked_durably` — no live lane; appended to the session's DURABLE box
+ *    ({@link PendingSessionNotifications.bindSessionBox}) — the next run drains it, in any process;
+ *  · `dropped_duplicate` — the session already delivered this exact frame.
+ * The park backend is the seat's choice ({@link routeOrParkNotification}), never the producer's.
+ */
+export type NotificationInjectionOutcome = "queued" | "parked" | "parked_durably" | "dropped_duplicate";
+export declare const NOTIFICATION_INJECTION_OUTCOMES: readonly ["queued", "parked", "parked_durably", "dropped_duplicate"];
+/** Is `value` one of the injector's outcome words? A host-wired uplink may answer anything (a bare
+ *  `void`, an array's `push` count) — such an answer reads as "outcome not reported", never as a word. */
+export declare function isNotificationInjectionOutcome(value: unknown): value is NotificationInjectionOutcome;
+/** The disposition a park/route decision reports back — the injection outcome minus the dedup fold. */
+export type NotificationDisposition = Exclude<NotificationInjectionOutcome, "dropped_duplicate">;
 /** The closed value set of {@link SystemInjectionPriority}, as data — the wire-facing entries validate
  *  against THIS rather than against three inline string literals, so widening the type widens the guard.
  *  (Names taken verbatim from CC 2.1.223's `UYo` @ `CC:644918`; see the semantics note on
@@ -135,6 +153,12 @@ export interface TaskNotificationPayload {
      *  outside caller can neither mint a chain nor wear the peer class. */
     peer?: {
         hopChain: string[];
+        /** The SENDING run's session id, when the producer knows it — the reply/receipt address a durable
+         *  park of this frame records (`MailboxPeerMeta.fromSession`). Engine-read; never rendered. */
+        fromSession?: string;
+        /** The sender's admission key (the same token the send-point gate charged), so a durable park
+         *  re-judges the frame under the same sender at the drain. Engine-read; never rendered. */
+        senderKey?: string;
     };
     /**
      * design/385 §1.4 d1 — the delegated-child → parent UPLINK carrier (`SendMessage("main")`). Its
@@ -264,7 +288,7 @@ export interface SystemInjection<TPayload = unknown> {
      *  listener: "queued" once the boundary steer accepted, "parked" when the idle tail-race (or the
      *  engine-note backlog cap) rejected and the payload was pended per session. Absent =
      *  fire-and-forget producer (no receipt to honor). */
-    onDisposition?: (d: "queued" | "parked") => void;
+    onDisposition?: (d: NotificationDisposition) => void;
 }
 /** design/373 (adversarial r3, recorded rule): the key deliberately EXCLUDES the injection tier.
  *  The key names an EVENT's identity; `priority` is delivery metadata about one submission of it.
@@ -356,6 +380,27 @@ export declare function renderTaskNotificationXml(n: TaskNotificationPayload): s
 export declare const MAX_PENDING_EVENTS_PER_TASK = 50;
 export declare const MAX_PENDING_EVENTS_PER_SESSION = 200;
 export declare const MAX_PENDING_SESSIONS = 100;
+/** Session-box bindings are three references and a handle; bounded far above the parked-session cap so
+ *  a long-lived leader's binding is not evicted by parked traffic (eviction = the park backend degrades
+ *  to in-process, which the receipt then says). */
+export declare const MAX_SESSION_BOX_BINDINGS = 4096;
+/**
+ * A session's DURABLE box, bound to the park seat by the leg that mounts its session-box drain — one
+ * mint (the drain mount judgment), two readers (the drain and {@link routeOrParkNotification}), so
+ * "a frame parked here is drained there" holds by construction. Absent for a session whose legs mount
+ * no drain (a delegated child, an ungrammatical id, no cross-process-safe mailbox).
+ */
+export interface SessionBoxBinding {
+    mailbox: MailboxStore;
+    /** The registry/mailbox scope the session's legs mount in (the drain reads the same scope). */
+    scope: string;
+    /** The box handle (`session.<id>`), minted after the address grammar passed. */
+    handle: string;
+    /** The session id the box belongs to — the `fromRoot` a durably parked child frame records. */
+    sessionId: string;
+    /** Where an append fault is disclosed (the frame then takes the in-process park — never lost). */
+    onError?: (e: unknown) => void;
+}
 /**
  * RB-375 A2 (ruled 2026-08-03) — is this frame the TERMINAL of a delegated background agent?
  *
@@ -423,7 +468,7 @@ export interface DrainedPendingNotifications {
  *  · `"unavailable"` — the lane can no longer take anything; the caller tries the next lane, and
  *    finally the parked store.
  */
-export type LiveNotificationLane = (payload: TaskNotificationPayload, priority: SystemInjectionPriority, onDisposition?: (d: "queued" | "parked") => void) => "taken" | "pending" | "duplicate" | "unavailable";
+export type LiveNotificationLane = (payload: TaskNotificationPayload, priority: SystemInjectionPriority, onDisposition?: (d: NotificationDisposition) => void) => "taken" | "pending" | "duplicate" | "unavailable";
 /** One run's seat: its two entry points, plus the two bookkeeping verbs its owner drives. */
 export interface LiveNotificationLaneSeat {
     /**
@@ -500,7 +545,7 @@ export declare class SessionLiveNotificationLanes {
      * special-cased: a lane that just refused this frame reports `"unavailable"` for it from then on.
      */
     deliver(sessionId: string, payload: TaskNotificationPayload, priority: SystemInjectionPriority, opts?: {
-        onDisposition?: (d: "queued" | "parked") => void;
+        onDisposition?: (d: NotificationDisposition) => void;
     }): "taken" | "pending" | "duplicate" | "unavailable";
     /** Sessions holding at least one live lane (observability + the tests' rollback detector). */
     get size(): number;
@@ -528,6 +573,16 @@ export declare class PendingSessionNotifications {
     /** Whole-session losses whose tombstone was itself evicted — the count survives, the attribution
      *  does not. Surfaced on the next session-level disclosure so it is never simply forgotten. */
     private unattributedDrops;
+    /** The durable park backend per session ({@link SessionBoxBinding}); insertion-ordered, bounded. */
+    private readonly sessionBoxes;
+    /**
+     * Bind (or, with `undefined`, unbind) the session's durable box. Written at EVERY drain mount of a
+     * session's leg, so the binding tracks the deployment's current seats (a mailbox swapped out
+     * unbinds at the next mount). A re-bind refreshes the entry's LRU position.
+     */
+    bindSessionBox(sessionId: string, box: SessionBoxBinding | undefined): void;
+    /** The session's durable box, when a leg of it mounted the drain in this process. */
+    sessionBoxFor(sessionId: string): SessionBoxBinding | undefined;
     pend(sessionId: string, n: TaskNotificationPayload, priority?: SystemInjectionPriority): void;
     /** Remove and return the session's pendings (one-shot — the next run consumes them exactly once).
      *  design/373 §3.5: the batch comes out PRIORITY-MAJOR (stable sort — pend order within a class;
@@ -548,6 +603,13 @@ export declare class PendingSessionNotifications {
      * next drain. Callers ask BEFORE routing and BEFORE parking.
      */
     holdsKey(sessionId: string, dedupKey: string): boolean;
+    /** Keys the session's DURABLE box took ({@link routeOrParkNotification}'s durable arm) — the third holder
+     *  {@link holdsKey} consults, so a retry of a frame the box already holds folds exactly as one the
+     *  in-process store holds. Bounded like {@link routed}; a key is released when the append faulted and
+     *  the frame took the in-process park instead (that store then owns it). */
+    private readonly durable;
+    noteDurablePark(sessionId: string, dedupKey: string): void;
+    forgetDurablePark(sessionId: string, dedupKey: string): void;
     /** Record that this session has DELIVERED this frame — see {@link routed}. Written at ONE place, the
      *  harness's consumption sink (the step where a queued frame enters the model's input), so the record
      *  can never run ahead of the delivery it claims. */
@@ -565,7 +627,20 @@ export declare class PendingSessionNotifications {
  *    ({@link LiveNotificationLaneSeat.markDelivered});
  *  · nothing can take it ⇒ park, carrying the tier, for the session's next run.
  */
-export declare function routeOrParkNotification(store: PendingSessionNotifications, sessionId: string, payload: TaskNotificationPayload, priority: SystemInjectionPriority, onDisposition?: (d: "queued" | "parked") => void): void;
+export declare function routeOrParkNotification(store: PendingSessionNotifications, sessionId: string, payload: TaskNotificationPayload, priority: SystemInjectionPriority, onDisposition?: (d: NotificationDisposition) => void): void;
+/**
+ * The durable form of a parked peer-words frame: the SAME `peer_message` record the cross-session lane
+ * appends (the recipient's drain renders it through the one envelope and judges it through the one
+ * admission gate), with `fromRoot` = the box owner's own session — a frame reaches this seat only
+ * through the injector its owner handed to a child of its tree, so the same-tree fact is the seat's to
+ * state, not the producer's to claim.
+ */
+export declare function sessionBoxRecordOf(payload: TaskNotificationPayload & {
+    agentMessage: {
+        from: string;
+        body: string;
+    };
+}, box: Pick<SessionBoxBinding, "sessionId">): MailboxAppendMessage;
 /**
  * Delivery-side overflow disclosure: fold the per-task drop counts into the drained payloads. Two
  * carrier shapes, chosen per survivor:

package/dist/core/task-notification.js

@@ -1,6 +1,10 @@
 import { escapeEnvelopeTag, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { PEER_MESSAGE_NOTICE } from "../agents/peer-admission.js";
 import { buildCrossSessionEnvelope, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
+export const NOTIFICATION_INJECTION_OUTCOMES = ["queued", "parked", "parked_durably", "dropped_duplicate"];
+export function isNotificationInjectionOutcome(value) {
+    return typeof value === "string" && NOTIFICATION_INJECTION_OUTCOMES.includes(value);
+}
 export const SYSTEM_INJECTION_PRIORITIES = ["now", "next", "later"];
 export function isSystemInjectionPriority(value) {
     return typeof value === "string" && SYSTEM_INJECTION_PRIORITIES.includes(value);
@@ -107,6 +111,7 @@ const MAX_DEDUP_KEYS = 2_000;
 export const MAX_PENDING_EVENTS_PER_TASK = 50;
 export const MAX_PENDING_EVENTS_PER_SESSION = 200;
 export const MAX_PENDING_SESSIONS = 100;
+export const MAX_SESSION_BOX_BINDINGS = 4096;
 const MAX_TOMBSTONES = 5_000;
 const TERMINAL_STATUSES = new Set(["completed", "failed", "killed", "cancelled"]);
 export function isDelegatedAgentTerminal(n) {
@@ -186,6 +191,22 @@ export class PendingSessionNotifications {
     droppedSessions = 0;
     evictedSessions = new Map();
     unattributedDrops = 0;
+    sessionBoxes = new Map();
+    bindSessionBox(sessionId, box) {
+        this.sessionBoxes.delete(sessionId);
+        if (box === undefined)
+            return;
+        this.sessionBoxes.set(sessionId, box);
+        while (this.sessionBoxes.size > MAX_SESSION_BOX_BINDINGS) {
+            const oldest = this.sessionBoxes.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.sessionBoxes.delete(oldest);
+        }
+    }
+    sessionBoxFor(sessionId) {
+        return this.sessionBoxes.get(sessionId);
+    }
     pend(sessionId, n, priority) {
         let s = this.sessions.get(sessionId);
         if (s === undefined) {
@@ -251,7 +272,36 @@ export class PendingSessionNotifications {
     }
     routed = new Map();
     holdsKey(sessionId, dedupKey) {
-        return this.sessions.get(sessionId)?.keys.has(dedupKey) === true || this.routed.get(sessionId)?.has(dedupKey) === true;
+        return this.sessions.get(sessionId)?.keys.has(dedupKey) === true || this.routed.get(sessionId)?.has(dedupKey) === true || this.durable.get(sessionId)?.has(dedupKey) === true;
+    }
+    durable = new Map();
+    noteDurablePark(sessionId, dedupKey) {
+        let mine = this.durable.get(sessionId);
+        if (mine === undefined) {
+            if (this.durable.size >= MAX_PENDING_SESSIONS) {
+                const oldest = this.durable.keys().next().value;
+                if (oldest !== undefined)
+                    this.durable.delete(oldest);
+            }
+            mine = new Set();
+            this.durable.set(sessionId, mine);
+        }
+        mine.add(dedupKey);
+        if (mine.size > MAX_PENDING_EVENTS_PER_SESSION) {
+            for (const k of mine) {
+                mine.delete(k);
+                if (mine.size <= MAX_PENDING_EVENTS_PER_SESSION)
+                    break;
+            }
+        }
+    }
+    forgetDurablePark(sessionId, dedupKey) {
+        const mine = this.durable.get(sessionId);
+        if (mine === undefined)
+            return;
+        mine.delete(dedupKey);
+        if (mine.size === 0)
+            this.durable.delete(sessionId);
     }
     markDelivered(sessionId, dedupKey) {
         let mine = this.routed.get(sessionId);
@@ -285,6 +335,30 @@ export function routeOrParkNotification(store, sessionId, payload, priority, onD
     }
     const routed = store.liveLanes.deliver(sessionId, payload, priority, { ...(onDisposition !== undefined ? { onDisposition } : {}) });
     if (routed === "unavailable") {
+        const box = store.sessionBoxFor(sessionId);
+        const carrier = payload.agentMessage;
+        if (box !== undefined && carrier !== undefined) {
+            store.noteDurablePark(sessionId, dedupKey);
+            const record = sessionBoxRecordOf({ ...payload, agentMessage: carrier }, box);
+            let appended;
+            try {
+                appended = Promise.resolve(box.mailbox.append(box.scope, box.handle, record));
+            }
+            catch (e) {
+                appended = Promise.reject(e);
+            }
+            appended.then(() => onDisposition?.("parked_durably"), (e) => {
+                store.forgetDurablePark(sessionId, dedupKey);
+                try {
+                    box.onError?.(e);
+                }
+                catch {
+                }
+                store.pend(sessionId, payload, priority);
+                onDisposition?.("parked");
+            });
+            return;
+        }
         store.pend(sessionId, payload, priority);
         onDisposition?.("parked");
     }
@@ -292,6 +366,21 @@ export function routeOrParkNotification(store, sessionId, payload, priority, onD
         onDisposition?.("queued");
     }
 }
+export function sessionBoxRecordOf(payload, box) {
+    const peer = payload.peer;
+    return {
+        from: payload.agentMessage.from,
+        content: payload.agentMessage.body,
+        sentAt: Date.now(),
+        hopChain: peer !== undefined ? [...peer.hopChain] : [],
+        peerMeta: {
+            ...(peer?.fromSession !== undefined ? { fromSession: peer.fromSession } : {}),
+            ...(peer?.senderKey !== undefined ? { senderKey: peer.senderKey } : {}),
+            fromRoot: box.sessionId,
+            kind: "peer_message",
+        },
+    };
+}
 function evictOldest(s, match) {
     let idx = s.items.findIndex((i) => match(i) && !TERMINAL_STATUSES.has(i.status));
     if (idx === -1)

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

@@ -419,7 +419,6 @@ export function registerBackgroundAgentLane(core, input) {
                 ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
                 ...(input.description !== undefined ? { description: input.description } : {}),
                 ...(input.model !== undefined ? { model: input.model } : {}),
-                ...(input.teamName !== undefined ? { teamName: input.teamName } : {}),
                 writerId: core.writerId,
                 writerEpoch: 1,
                 spawnedAt: now,
@@ -1236,7 +1235,7 @@ export async function deliverToRunningAgentLane(core, id, access, notification,
             let result;
             try {
                 const d = await handle.notify?.(notification, opts);
-                if (d === "parked") {
+                if (d === "parked" || d === "parked_durably") {
                     result = handle.retainedContinuation === true ? { ok: true, disposition: "parked" } : { ok: false, reason: "not_running" };
                 }
                 else {

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_CHARS, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, clipMonitorLine, terminalTaskSummary, accountDroppedBytes, renderSpoolBody, 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, renderSpoolBody, SPOOL_REPLAY, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.js";
 import { buildToolResultRef, OFFLOAD_TOOL_NAME, toolResultProvenanceOf } from "./tool-result-store.js";
 import { thrownText } from "./thrown-value.js";
 export function registerMonitorLane(core, input) {
@@ -339,6 +339,7 @@ export async function pollMonitorLane(handle, filter, deadline, signal) {
             details: {
                 status: running ? "running" : handle.status,
                 exitCode: spool.exitCode,
+                replay: SPOOL_REPLAY,
                 ...(spool.droppedBytes !== undefined ? { bytesDroppedBeforeCursor: spool.droppedBytes } : {}),
                 ...(spool.timedOut === true ? { timedOut: true, ...(spool.timeoutSec !== undefined ? { timeoutSec: spool.timeoutSec } : {}) } : {}),
             },

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

@@ -5,6 +5,7 @@ import type { BackgroundAgentRecord, BackgroundAgentStore } from "./background-a
 import type { WorkflowHandle, WorkflowRun } from "../orchestration/workflow.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
 import type { ToolResultStore } from "./tool-result-store.js";
+import type { AssertAllKeysHandled } from "./ask-origin.js";
 export type SemaTaskType = "background_bash" | "workflow" | "background_agent" | "monitor";
 /** design/134 §3.3 (R3): WHO initiated a kill — recorded at the initiation site (first-marker-wins),
  *  because the settle-side then/catch context has already lost it. OPEN ENUM on the wire, now in the
@@ -254,7 +255,7 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
      *  ends park per session inside the injector itself (the lane-teardown branch). */
     notify?: (notification: import("./task-notification.js").TaskNotificationPayload, opts?: {
         priority?: import("./task-notification.js").SystemInjectionPriority;
-    }) => "queued" | "parked" | "dropped_duplicate" | Promise<"queued" | "parked" | "dropped_duplicate">;
+    }) => import("./task-notification.js").NotificationInjectionOutcome | Promise<import("./task-notification.js").NotificationInjectionOutcome>;
     /** design/147 S2a — messages that arrived in the STARTUP window (row already
      *  running, lane not yet bound). Bounded; flushed in order by attachAgentNotify. Discarded at
      *  terminal settle: a run that failed during prepare never had a lane to park through, and the
@@ -658,6 +659,54 @@ export declare function spoolDropNote(acct: {
     droppedBytes?: number;
     dropUnknown?: true;
 }): string;
+/**
+ * HOW a poll's output body may be read AGAIN — the machine word beside `details`, previously legible
+ * only from the stdout heading's prose.
+ *
+ * `full` = the whole output of the task, re-rendered from the registry's own spool on every poll: a
+ * later poll answers the same bytes plus whatever arrived, so a consumer REPLACES what it holds.
+ * `cursor` = only what is NEW since the previous read: the env cursor was consumed and those bytes
+ * cannot be served twice, so a consumer APPENDS.
+ *
+ * The distinction was machine-invisible and the one key nearby reads the two faces OPPOSITELY:
+ * `bytesDroppedBeforeCursor` rides the spool faces only when something was actually dropped, and the
+ * increment face unconditionally (value possibly 0). A consumer discriminating on that key's PRESENCE
+ * therefore reads a spool that happened to drop bytes as an increment — and appends a body that was a
+ * full re-render, printing the same text twice.
+ */
+export declare const TASK_OUTPUT_REPLAY_KINDS: readonly ["full", "cursor"];
+export type TaskOutputReplay = (typeof TASK_OUTPUT_REPLAY_KINDS)[number];
+/**
+ * The ONE table the word and the prose both come out of. Each face's stdout/stderr headings live here
+ * rather than at the three legs that render them, so the banner a person reads and the key a program
+ * reads cannot drift — the failure mode this whole field exists to end (the two spool renderers were
+ * hand-copied twins before {@link renderSpoolBody}, and their drift was three disclosure bugs).
+ *
+ * `stdoutWhenGapped` is the heading a face falls back to once a gap has been disclosed. `undefined` is
+ * a ROW, not an omission: an increment window claims nothing about completeness to begin with ("new
+ * stdout" is true whether or not bytes were lost before it), so it has no claim to downgrade — while a
+ * spool advertising itself as "full" with a disclosed gap would be saying something false.
+ */
+export declare const REPLAY_FACE: {
+    readonly full: {
+        readonly stdout: "stdout (full, re-readable)";
+        readonly stdoutWhenGapped: "stdout (re-readable spool — INCOMPLETE, see note above)";
+        readonly stderr: "stderr";
+    };
+    readonly cursor: {
+        readonly stdout: "new stdout";
+        readonly stdoutWhenGapped: undefined;
+        readonly stderr: "new stderr";
+    };
+};
+export type ReplayHeadingTableCoversEveryReplay = AssertAllKeysHandled<Exclude<TaskOutputReplay, keyof typeof REPLAY_FACE>>;
+/** The re-readable spool face: the monitor lane and the bash spool lane, both rendered by
+ *  {@link renderSpoolBody}. Named once so the three legs that report it cannot each spell it. */
+export declare const SPOOL_REPLAY = "full";
+/** The consume-once increment face: the bash blocked wait, which accumulates env-cursor increments. */
+export declare const INCREMENT_REPLAY = "cursor";
+/** The stdout heading of a face, downgraded when a gap has been disclosed (see {@link REPLAY_FACE}). */
+export declare function stdoutHeadingOf(replay: TaskOutputReplay, gapDisclosed: boolean): string;
 /** The re-readable spool fields {@link renderSpoolBody} reads — the intersection of the bash handle's
  *  optional `spool` and the monitor handle's mandatory one (both carry supersets: `mirrorFailed` is
  *  bash-only, `drainFailed`/`dropNotified` monitor-only). Declared as a named shape, not inlined, so
@@ -878,15 +927,14 @@ export interface RegisterBackgroundAgentInput extends TaskAccess {
      *  internals chain; equals parentSessionId at depth 1). Persisted on the handle, the durable row
      *  and the roster so recovery faces enumerate the whole tree under the root without alias walks. */
     rootSessionId?: string;
-    /** design/151 S3b — revival lookup keys (CC meta-sidecar shape): the model RECORD KEY and the team
-     *  name, persisted on the durable row so a tier-3 revival rebuilds the spec the way a fresh
-     *  named-teammate spawn would. Lookup keys only, never a serialized spec. `model` is NOT the
+    /** design/151 S3b — the revival lookup key (CC meta-sidecar shape): the model RECORD KEY,
+     *  persisted on the durable row so a tier-3 revival rebuilds the spec the way a fresh
+     *  named-teammate spawn would. A lookup key only, never a serialized spec. `model` is NOT the
      *  resolved model id: a spawn that named a model in WORDS records the caller's spelling verbatim
      *  (catalog key / tier word / CC alias) so the revival can re-resolve it against the catalog in
      *  force at WAKE time; only a spawn that carried a Model OBJECT records that object's id. Same
      *  value and same rule as the roster row's `model` column. */
     model?: string;
-    teamName?: string;
     toolUseId?: string;
     abort: AbortController;
     now?: number;

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

@@ -101,14 +101,25 @@ export function spoolDropNote(acct) {
         return "[!] an unknown amount of earlier output was permanently dropped before this window (buffer evicted)\n";
     return "";
 }
+export const TASK_OUTPUT_REPLAY_KINDS = ["full", "cursor"];
+export const REPLAY_FACE = {
+    full: { stdout: "stdout (full, re-readable)", stdoutWhenGapped: "stdout (re-readable spool — INCOMPLETE, see note above)", stderr: "stderr" },
+    cursor: { stdout: "new stdout", stdoutWhenGapped: undefined, stderr: "new stderr" },
+};
+export const SPOOL_REPLAY = "full";
+export const INCREMENT_REPLAY = "cursor";
+export function stdoutHeadingOf(replay, gapDisclosed) {
+    const face = REPLAY_FACE[replay];
+    return gapDisclosed ? (face.stdoutWhenGapped ?? face.stdout) : face.stdout;
+}
 export function renderSpoolBody(spool, opts) {
     const timedOutClause = spool.timedOut === true ? ` (timed out after ${spool.timeoutSec !== undefined ? `${spool.timeoutSec}s` : "its background time budget"})` : "";
     const displayStatus = (spool.exitCode !== undefined ? `exited(code ${spool.exitCode})` : opts.running ? "running" : opts.handleStatus) + timedOutClause;
     const rolledNote = spool.rolledChars > 0 ? `[!] ${spool.rolledChars} earlier char(s) dropped from the spool (memory bound)${opts.rolledExtraClause}\n` : "";
     const droppedNote = spoolDropNote(spool);
-    const stdoutHeading = droppedNote !== "" || opts.drainNote !== "" ? "stdout (re-readable spool — INCOMPLETE, see note above)" : "stdout (full, re-readable)";
+    const stdoutHeading = stdoutHeadingOf(SPOOL_REPLAY, droppedNote !== "" || opts.drainNote !== "");
     return (`status: ${displayStatus}\n${rolledNote}${droppedNote}${opts.drainNote}--- ${stdoutHeading} ---\n${opts.shape(spool.stdout) || "(none)"}\n` +
-        `--- stderr ---\n${opts.shape(spool.stderr) || "(none)"}`);
+        `--- ${REPLAY_FACE[SPOOL_REPLAY].stderr} ---\n${opts.shape(spool.stderr) || "(none)"}`);
 }
 export function droppedGapNote(spool) {
     if ((spool.droppedBytes ?? 0) > 0)

package/dist/core/task-registry.js

@@ -8,7 +8,7 @@ import { createSafeNotifier } from "./safe-notify.js";
 import { stripCwdSentinel } from "../tools/fs/fs-shared.js";
 import { registerMonitorLane, pollMonitorLane, stopMonitorLane } from "./task-registry-monitor.js";
 import { registerWorkflowLane, pollWorkflowLane, stopWorkflowLane } from "./task-registry-workflow.js";
-import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, renderSpoolBody, spoolDropNote, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
+import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, renderSpoolBody, stdoutHeadingOf, REPLAY_FACE, SPOOL_REPLAY, INCREMENT_REPLAY, spoolDropNote, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
 export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
 import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
 import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
@@ -1075,6 +1075,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                     details: {
                         status: running ? "running" : handle.status,
                         exitCode: spool.exitCode,
+                        replay: SPOOL_REPLAY,
                         ...(spool.droppedBytes !== undefined ? { bytesDroppedBeforeCursor: spool.droppedBytes } : {}),
                         ...(spool.timedOut === true ? { timedOut: true, ...(spool.timeoutSec !== undefined ? { timeoutSec: spool.timeoutSec } : {}) } : {}),
                     },
@@ -1099,12 +1100,13 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                 if (r.error.code === "not_found")
                     return noTask(requestedId, runningAgentFooterLane(this.core, access));
                 const retrieval_status = r.error.code === "timeout" ? "timeout" : "not_ready";
-                const salvaged = stdout.length > 0 || stderr.length > 0
+                const carriedOutput = stdout.length > 0 || stderr.length > 0;
+                const salvaged = carriedOutput
                     ? `\n--- output accumulated before the error ---\n${clipTaskOutput(stdout, handle.outputFile)}${stderr ? `\n--- stderr ---\n${clipTaskOutput(stderr, handle.outputFile)}` : ""}`
                     : "";
                 return {
                     content: `Error (TaskOutput): ${r.error.message}${salvaged}`,
-                    details: { task_id: handle.id, type: "background_bash", status: handle.status, retrieval_status, error: r.error.code },
+                    details: { task_id: handle.id, type: "background_bash", status: handle.status, retrieval_status, ...(carriedOutput ? { details: { replay: INCREMENT_REPLAY } } : {}), error: r.error.code },
                     isError: true,
                 };
             }
@@ -1125,8 +1127,8 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                 const displayStatus = (r.value.status === "exited" ? `exited(code ${r.value.exitCode})` : r.value.status) + timedOutClause;
                 const droppedNote = spoolDropNote(dropAcct) +
                     (rolledChars > 0 ? `[!] ${rolledChars} accumulated char(s) dropped from the middle during the blocked wait (memory bound)\n` : "");
-                const body = `status: ${displayStatus}\n${droppedNote}--- new stdout ---\n${shape(stdout) || "(none)"}\n` +
-                    `--- new stderr ---\n${shape(stderr) || "(none)"}`;
+                const body = `status: ${displayStatus}\n${droppedNote}--- ${stdoutHeadingOf(INCREMENT_REPLAY, droppedNote !== "")} ---\n${shape(stdout) || "(none)"}\n` +
+                    `--- ${REPLAY_FACE[INCREMENT_REPLAY].stderr} ---\n${shape(stderr) || "(none)"}`;
                 return {
                     content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
                     details: {
@@ -1139,6 +1141,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                         details: {
                             status: r.value.status,
                             exitCode: r.value.exitCode,
+                            replay: INCREMENT_REPLAY,
                             bytesDroppedBeforeCursor: dropAcct.droppedBytes ?? 0,
                             ...(r.value.timedOut === true ? { timedOut: true, ...(r.value.timeoutSec !== undefined ? { timeoutSec: r.value.timeoutSec } : {}) } : {}),
                         },

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

@@ -783,9 +783,12 @@ export interface TaskSpec {
     /**
      * design/199 件B — TASK-layer ADDITIONS to the built-in sensitive-path READ deny set
      * ({@link import("../tools/fs/read-deny.js").READ_FACE_DEFAULT_DENY_ENTRIES}). Judged by the
-     * structured read faces (Read/Grep/Glob/RepoMap, their traversals, the classify shell gate's
-     * auto-allow probe, the compaction attachment reader and the `bash_readonly` shell mounted by
-     * {@link handsReadOnly} — one deny judge for every read face) in BOTH containment modes. Add-only at
+     * structured read faces (Read/Grep/Glob/RepoMap, their traversals, the compaction attachment reader) and
+     * by the shell READ STATION under every doctrine — the full shell (`Bash`, `Monitor`, whatever
+     * {@link shellGate} says) and the `bash_readonly` shell mounted by {@link handsReadOnly} alike: a
+     * deny-listed shell read is REFUSED at the gate (`deniedBy: "read_boundary"`), never asked, with the same
+     * sentence the structured faces refuse with — one deny judge for every read face — in BOTH containment
+     * modes. Add-only at
      * the task layer: entries here UNION with the active built-ins and the deployment's
      * {@link RunnerDeps.readDenyPatterns}; `[]` ≡ absent (union identity); NOTHING at the task layer
      * can remove a built-in — the one removal channel is the DEPLOYMENT's built-in configuration
@@ -873,8 +876,12 @@ export interface TaskSpec {
      *  - `"always"`: every `bash` command tightens to an `irreversible_ask` durable suspend (fail-closed; the
      *    correct default for an unattended/supervisor deployment with no classifier).
      *  - `"classify"`: mark `bash` `irreversibility:"maybe"` with {@link import("../tools/fs/index.js").bashReversibilityProbe}
-     *    — a provably-benign single allowlisted read-only command (no operators) auto-allows; everything else
-     *    (writes, egress, pipes, unknown commands) tightens to ask. An egress command (e.g. `curl`) suspends under
+     *    — the SHAPE classifier alone: a provably-benign single allowlisted read-only command (no operators)
+     *    auto-allows; everything else (writes, egress, pipes, unknown commands) tightens to ask. WHERE a command
+     *    reads is not this doctrine's question under any value: the gate's shell read station judges every
+     *    shell call's read candidates against the deny set and the containment roots (a deny-listed read is
+     *    refused, an out-of-root read is a mandated ask) whether `shellGate` is `"off"`, `"classify"` or
+     *    `"always"`. An egress command (e.g. `curl`) suspends under
      *    the IRREVERSIBLE axis (the shell mark is irreversibility, not egress) — the kind is non-budgetable either
      *    way, so the budget resolver still never auto-approves it; the axis label is informational.
      *    NOT unconditional: a POSITIVE per-tool mark on the shell tool keeps its seat — an explicit

package/dist/core/tool-catalog-entries.js

@@ -154,6 +154,7 @@ export const ENGINE_CARDS = Object.freeze({
     a2a: "src/core/a2a.ts",
     path_not_in_root: "src/tools/fs/safety.ts",
     read_path_denied: "src/tools/fs/safety.ts",
+    readonly_out_of_root: "src/tools/fs/shell-read-check.ts",
 });
 const byId = new Map();
 for (const e of TOOL_CATALOG_ENTRIES) {