@sema-agent/core 5.47.0 → 5.48.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 5.48.0 — 2026-08-20
+
+### Added
+- design/319 tickets B+C+D — the reminder-impersonation defense completes (A shipped 5.46.0):
+  - **Detect-and-disclose trailer** (four outlets: plain-text Read, notebook projection,
+    extracted PDF text, MCP success results): external bytes containing reminder-shaped text
+    gain a trailing disclosure block. Two wordings: bare form (reminder-shaped, markless —
+    throttled 60s per file / per server:tool) and marked form (carries the CURRENT session mark,
+    definitionally zero legitimate probability — never throttled). Scan point = the final
+    model-facing projection at each outlet.
+  - **Narrow defuse** (MCP success + web only): a block carrying the exact current mark is
+    defused (mark bytes broken) with a disclosure line. Read-family outlets stay byte-verbatim
+    (editing-loop preservation; disclosure-only there).
+  - Observability: `TaskResult.stats.mechanisms.reminderDisclosures`
+    (`Record<"outlet.form", number>`). Gate: `npm run gate:reminder-literal` (AST; mint-home
+    exclusivity). Public doc: `docs/REMINDER-PROVENANCE.md` (mechanism, explicit limits,
+    standards-evolution swap point).
+- design/323 — subagent transcript persistence on the EXISTING SessionStore ("no new store"),
+  root-fixing revival across process restarts:
+  - **Placement contract** (all additive/optional): `SessionStore.placements` declaration,
+    placement-bearing acquire, `listPlaced`, six obligations (host-list exclusion, claim
+    refusal `placement_refused`, tuple immutability, mirror-direction identity check,
+    placed release = real row deletion with failures surfaced, partition enumeration).
+    `FileStorageBackend` gains `backgroundAgentStore`/`mailboxStore`/`rosterStore` (aggregation
+    parity with session/checkpoint/tool-result; half-wired silent-degradation shape closed) and
+    declares durable subagent placements.
+  - **Revival**: a completed background subagent now answers `SendMessage` across a process
+    restart (disk-replayed transcript; `status:"revived"`, cycle sequence continuous). The
+    anonymous-agent gate is retired (anonymous rows revive too). User-stopped agents stay
+    blocked on the model lane; `createAgentContinuationVerb` (module-private symbol,
+    `userInitiated`) is the operator door. `resolveSubagentTranscriptTier` (none/rows/full)
+    projects as `WiringManifest.fleet.subagentTranscripts`.
+  - **Caps + reaping**: `RunnerDeps.delegationEntryCaps` (defaults 20 concurrent / 200 retained;
+    bad values refuse via `config.delegation_entry_caps`; rejections
+    `delegation.concurrency_cap`/`delegation.session_cap`); the durable-agent reap gains a
+    placed-partition leg (`orphanPlacedReleased`) with same- and cross-process live-agent
+    protection; `delegation.transcript_integrity` notice. New exports: placement types,
+    tier/caps resolvers, continuation verb, five constants (+14, all additive).
+
+### Fixed
+- The shipped third-party memory-backend reference template refuses cross-scope re-adds and
+  judges whitewash on the PRE-BATCH committed snapshot (delete-then-readd in one batch can no
+  longer blank an origin; `guard:"absent"` same-rev idempotent arm kept; presence-judged strip
+  refusal). A resident pin now runs the template through the full conformance suite on every
+  suite execution.
+
+### Notes
+- Read/MCP results that contain reminder-shaped data grow a trailing block (additive, ~40
+  tokens); MCP/web segments carrying the exact current session mark are byte-defused (narrowing;
+  legitimate-content probability zero, disclosed inline). Everything else in the 319/323 batch
+  is additive; no BREAKING changes.
+
 ## 5.47.0 — 2026-08-20
 
 ### Added

package/dist/agents/agent-transcript-tool.d.ts

@@ -28,6 +28,10 @@ export interface AgentTranscriptToolOptions {
      * design/157 A7 — behind). Absent ⇒ unchanged behavior: the `opts` axes alone supply the identity.
      */
     enrichCtx?: import("../core/tools.js").ToolCtxEnricher;
+    /** Subagent transcript persistence — the declared-durability integrity-gap disclosure sink (see
+     *  the SendMessage twin): a durable row with a bound sessionId whose session store attests
+     *  not_found. Announced once per (handle, process); absent ⇒ the honest per-call degrade alone. */
+    onTranscriptIntegrityGap?: (handle: string) => void;
 }
 /**
  * Residual observability (lane C) — build the MODEL-VISIBLE **AgentTranscript** tool: read the last N tool steps of a

package/dist/agents/agent-transcript-tool.js

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { defineTool } from "../core/tools.js";
-import { canAccessAgentRecord } from "../core/background-agent-store.js";
+import { announceTranscriptIntegrityGapOnce, canAccessAgentRecord } from "../core/background-agent-store.js";
+import { DURABLE_AGENT_HANDLE_RE } from "../core/task-registry.js";
 import { inlineUntrusted } from "../core/untrusted-text.js";
 import { stepsFromMessages } from "./subagent-steps.js";
 import { REPORT_FIELD_MAX } from "./subagent.js";
@@ -61,7 +62,10 @@ export function createAgentTranscriptTool(opts) {
                         details: { type: "agent-transcript", id, steps },
                     };
                 }
-                catch {
+                catch (e) {
+                    if (e?.code === "not_found") {
+                        announceTranscriptIntegrityGapOnce(id, opts.onTranscriptIntegrityGap);
+                    }
                     return undefined;
                 }
             };
@@ -77,7 +81,10 @@ export function createAgentTranscriptTool(opts) {
                 const durable = await readDurableSteps();
                 if (durable)
                     return durable;
-                return { content: `No transcript: no background agent task "${id}" (unknown id, not yours, or expired).`, details: { error: "not_found", id }, isError: true };
+                if (DURABLE_AGENT_HANDLE_RE.test(id)) {
+                    return { content: `No transcript found for agent ${id}.`, details: { error: "not_found", id }, isError: true };
+                }
+                return { content: `No transcript: no background agent task "${id}" (unknown id, or not yours).`, details: { error: "not_found", id }, isError: true };
             }
             const runLedger = ctx.subagentRetain ?? undefined;
             const atLedgerSessionId = ctx.sessionId ?? opts.sessionId;

package/dist/agents/send-message-tool.d.ts

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import type { Runner } from "../core/runner/runtask.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
 import { type ToolCtxEnricher } from "../core/tools.js";
+import { type TaskAccess } from "../core/task-registry.js";
 import { SubagentRetainLedger } from "./retain-ledger.js";
 import { type SubagentSteerHandle } from "./subagent.js";
 import { type PeerAdmissionConfig, type PeerInboundChainRef, type PeerSelfRef } from "./peer-admission.js";
@@ -125,6 +126,14 @@ export interface SendMessageToolOptions {
      *  A direct mount that wires `uplink` without this leaves L1 ungated (recorded honest boundary:
      *  the library does not fabricate an identity on the host's behalf). */
     uplinkRecipient?: PeerSelfRef;
+    /**
+     * Subagent transcript persistence — the "declared durability contradicted by reality" disclosure
+     * sink: called (at most once per handle per process, {@link announceTranscriptIntegrityGapOnce})
+     * when a durable row with a bound sessionId meets a session store that attests `not_found`. The
+     * first-party mount wires an EngineNotice (`delegation.transcript_integrity`); absent ⇒ the
+     * per-call honest refusal is the only loudness (unchanged behavior).
+     */
+    onTranscriptIntegrityGap?: (handle: string) => void;
 }
 /** RB-382 — max chars of the `summary` arg (the short recap label, distinct from `message`'s much
  *  larger {@link UPLINK_RESULT_MAX}) before ITS OWN truncation. Exported for direct unit-testing only
@@ -152,8 +161,41 @@ export declare function clipSendMessageSummary(raw: string): string;
  * second revive). The auto-mode peer-referral tighten keys on the WIRE NAME and applies to a direct
  * mount all the same.
  */
-export declare function createSendMessageTool(opts: SendMessageToolOptions): import("../core/types.js").AgentTool<Type.TObject<{
+export declare function createSendMessageTool(opts: SendMessageToolOptions): import("../internal/harness.js").AgentTool<Type.TObject<{
     to: Type.TString;
     message: Type.TString;
     summary: Type.TOptional<Type.TString>;
 }>, unknown>;
+/** The receipt {@link createAgentContinuationVerb} resolves with — the SendMessage tool's own
+ *  receipt family, flattened to one text (same content, same `details.error` code vocabulary). */
+export interface AgentContinuationReceipt {
+    content: string;
+    details?: unknown;
+    isError?: boolean;
+}
+/**
+ * Subagent transcript persistence — the OPERATOR continuation verb: the SendMessage delivery ladder
+ * as a reusable, non-model face for a deployment's own continuation endpoint. SINGLE-SOURCE by
+ * construction: the verb routes THROUGH `createSendMessageTool`'s product (status arms, admission
+ * gates, preflight order, claim CAS + rollback, parked/running refusals and the whole refusal-code
+ * family are the tool's own, byte-shared — never a twin implementation). The one fork is the
+ * `userInitiated` mode bit ({@link OPERATOR_CONTINUATION_CTX}): `true` waives BOTH user-stop gates —
+ * the durable row's `stoppedBy === "user"` arm and the live registry's stop-attribution arm — so an
+ * explicit human "continue it" overrides an earlier human "stop it" (the winning claim's
+ * clear-terminal-payload erases the durable mark; the model-facing tool NEVER softens).
+ *
+ * Authorization is three-layered and this verb owns only the first: ① the same
+ * `canAccessAgentRecord` row predicate the tool runs (an out-of-scope handle reads not_found —
+ * non-leaking); ② "this really is an explicit human instruction" is the DEPLOYMENT's obligation —
+ * the same trust seat that stamps `stopSource:"user"` on the stop side (a server exposes this only
+ * through a verified interactive-user principal endpoint, never to unattended machine clients); ③ the model
+ * tool face has no such parameter (the bit travels on a module-private symbol — zero forgeable
+ * surface from arguments).
+ *
+ * Store-conditional like every continuation face: with no durable stores wired the live-gate waiver
+ * still works for same-process handles, and the durable leg refuses honestly.
+ */
+export declare function createAgentContinuationVerb(opts: SendMessageToolOptions): (handle: string, content: string, access: TaskAccess, o?: {
+    userInitiated?: true;
+    summary?: string;
+}) => Promise<AgentContinuationReceipt>;

package/dist/agents/send-message-tool.js

@@ -1,7 +1,8 @@
 import { Type } from "typebox";
 import { defineTool } from "../core/tools.js";
 import { normalizeAgentName, DURABLE_AGENT_HANDLE_RE, DURABLE_AGENT_HEARTBEAT_MS } from "../core/task-registry.js";
-import { canAccessAgentRecord, clearRevivedRowTerminalPayload } from "../core/background-agent-store.js";
+import { announceTranscriptIntegrityGapOnce, canAccessAgentRecord, clearRevivedRowTerminalPayload } from "../core/background-agent-store.js";
+import { uuidv7 } from "../internal/harness.js";
 import { MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../core/mailbox-store.js";
 import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger } from "./retain-ledger.js";
@@ -41,6 +42,7 @@ function withTargetLane(key, fn) {
 function targetLaneKey(scope, targetId) {
     return JSON.stringify([scope ?? "", targetId]);
 }
+const OPERATOR_CONTINUATION_CTX = Symbol("sema.operator_continuation");
 export function createSendMessageTool(opts) {
     const tier3Capable = opts.agentStore !== undefined && opts.mailbox !== undefined && opts.reviveSpawn !== undefined;
     return defineTool({
@@ -56,9 +58,9 @@ export function createSendMessageTool(opts) {
             `address an older one. You will be notified automatically when it completes — prefer ending your turn; do not ` +
             `poll. ` +
             (tier3Capable
-                ? `Continuing a finished agent works for NAMED agents (revived from their durable record, even across restarts) and for runs that retain sub-agent sessions; when neither covers it you get an honest error and should launch a new agent with the needed context instead.`
+                ? `Continuing a finished agent works for agents with a durable record — by name or task_id, even across restarts — and for runs that retain sub-agent sessions; when neither covers it you get an honest error and should launch a new agent with the needed context instead.`
                 : `Continuing a finished agent requires the run to retain sub-agent sessions; when the session was not ` +
-                    `retained (or has expired) you get an honest error and should launch a new agent with the needed context instead.`),
+                    `retained (or is no longer held) you get an honest error and should launch a new agent with the needed context instead.`),
         parameters: Type.Object({
             to: Type.String({ description: 'Recipient: the agent\'s name, or its task_id (a…) returned by the Agent tool with run_in_background. "main" is reserved for the spawning conversation.' }),
             message: Type.String({ description: "The follow-up request. The agent continues from its full prior context." }),
@@ -66,6 +68,7 @@ export function createSendMessageTool(opts) {
         }),
         execute: async (args, ctx) => {
             const a = args;
+            const operatorUserInitiated = ctx[OPERATOR_CONTINUATION_CTX] === true;
             const to = String(a.to ?? "").trim();
             const message = String(a.message ?? "").trim();
             if (!to)
@@ -201,10 +204,10 @@ export function createSendMessageTool(opts) {
                     if (!canAccessAgentRecord(row, parentAccess))
                         return undefined;
                 }
-                if (row.name === undefined || row.agentType === "fork")
+                if (row.agentType === "fork")
                     return undefined;
                 const whoT3 = handle === to ? `agent ${handle}` : `agent "${to}" (${handle})`;
-                if (row.status === "killed" && row.stoppedBy === "user") {
+                if (row.status === "killed" && row.stoppedBy === "user" && !operatorUserInitiated) {
                     return {
                         content: `Message not sent: ${whoT3} was stopped by the user and was not resumed. Treat its work as cancelled; only start a new agent for it if the user explicitly asks.`,
                         details: { error: "killed", to, stoppedBy: row.stoppedBy },
@@ -289,7 +292,8 @@ export function createSendMessageTool(opts) {
                         catch (e) {
                             await rollbackDrain();
                             if (e?.code === "not_found") {
-                                return queueFullReceipt(`Its transcript session no longer exists (evicted or reaped), so a revival cannot drain the backlog.`);
+                                announceTranscriptIntegrityGapOnce(handle, opts.onTranscriptIntegrityGap);
+                                return queueFullReceipt(`No transcript found for agent ${handle}, so a revival cannot drain the backlog.`);
                             }
                             return queueFullReceipt(`Its transcript store did not answer (${e instanceof Error ? e.message : String(e)}) — this send did not start a backlog drain; a later resend will try again.`);
                         }
@@ -387,8 +391,9 @@ export function createSendMessageTool(opts) {
                     catch (e) {
                         await rollback();
                         if (e?.code === "not_found") {
+                            announceTranscriptIntegrityGapOnce(handle, opts.onTranscriptIntegrityGap);
                             return {
-                                content: `Message not sent: ${whoT3}'s transcript session no longer exists (evicted or reaped) — it cannot be revived. Launch a new agent with the needed context instead.`,
+                                content: `Message not sent: no transcript found for agent ${handle} — it cannot be revived. Launch a new agent with the needed context instead.`,
                                 details: { error: "resume.session_not_found", to },
                                 isError: true,
                             };
@@ -533,8 +538,15 @@ export function createSendMessageTool(opts) {
                     const labels = parentAccess !== undefined
                         ? [...ownLabels, ...opts.registry.runningBackgroundAgentLabels(parentAccess).filter((l) => !ownLabels.includes(l))]
                         : ownLabels;
+                    if (DURABLE_AGENT_HANDLE_RE.test(to)) {
+                        return {
+                            content: `Message not sent: no transcript found for agent ${to} — launch a new agent with the needed context instead.`,
+                            details: { error: "not_found", to },
+                            isError: true,
+                        };
+                    }
                     return {
-                        content: `Message not sent: no agent matches "${to}" (unknown id or name, not yours, or expired).` +
+                        content: `Message not sent: no agent matches "${to}" (unknown id or name, or not yours).` +
                             (suggestion !== undefined ? ` Did you mean: ${suggestion}?` : "") +
                             (labels.length > 0 ? ` Running background agents: ${labels.join(", ")}.` : "") +
                             ` Note: a completed foreground agent is not resumable (its transcript is not retained) — spawn with run_in_background to keep an agent addressable, or launch a new agent.`,
@@ -617,7 +629,7 @@ export function createSendMessageTool(opts) {
             }
             if (row.status === "killed") {
                 const by = opts.registry.getStopAttribution(targetId);
-                if (by === "user") {
+                if (by === "user" && !operatorUserInitiated) {
                     return {
                         content: `Message not sent: ${who} was stopped by the user and was not resumed. Treat its work as cancelled; only start a new agent for it if the user explicitly asks.`,
                         details: { error: "killed", to, stoppedBy: by },
@@ -712,9 +724,10 @@ export function createSendMessageTool(opts) {
                     const text = code === "resume.retain_off"
                         ? `${who}'s session was not retained (retainSubagentSessions is off) — relaunch a new agent instead.`
                         : code === "resume.evicted"
-                            ? `${who}'s retained session was evicted (retain TTL / capacity / parent run ended) — relaunch a new agent instead.`
+                            ?
+                                `${who} is no longer held in this run's fast lane (retain window or capacity passed, or the parent run ended) — relaunch a new agent with the needed context instead.`
                             : code === "resume.session_not_found"
-                                ? `${who}'s session no longer exists — relaunch a new agent instead.`
+                                ? `no transcript found for ${who} — relaunch a new agent with the needed context instead.`
                                 : code === "resume.cap"
                                     ? `${who} reached its resume cap (${SUBAGENT_RESUME_CAP} follow-ups per agent) — relaunch a new agent instead.`
                                     : code === "steering.still_running"
@@ -732,3 +745,29 @@ export function createSendMessageTool(opts) {
         },
     }, opts.enrichCtx !== undefined ? { enrichCtx: opts.enrichCtx } : {});
 }
+export function createAgentContinuationVerb(opts) {
+    return async (handle, content, access, o) => {
+        const tool = createSendMessageTool({
+            ...opts,
+            enrichCtx: (base) => {
+                const enriched = {
+                    ...base,
+                    ...(access.owner !== undefined ? { taskId: access.owner } : {}),
+                    ...(access.scope !== undefined ? { principal: access.scope } : {}),
+                    ...(access.sessionId !== undefined ? { sessionId: access.sessionId } : {}),
+                };
+                if (o?.userInitiated === true)
+                    enriched[OPERATOR_CONTINUATION_CTX] = true;
+                return enriched;
+            },
+        });
+        const summaryRaw = (o?.summary ?? content).replace(/\s+/g, " ").trim().slice(0, 200);
+        const summary = summaryRaw === "" ? "operator follow-up" : summaryRaw;
+        const out = await tool.execute(`op-${uuidv7()}`, { to: handle, message: content, summary });
+        const text = out.content
+            .filter((c) => c.type === "text")
+            .map((c) => c.text)
+            .join("\n");
+        return { content: text, ...(out.details !== undefined ? { details: out.details } : {}), ...(out.isError === true ? { isError: true } : {}) };
+    };
+}

package/dist/agents/subagent.d.ts

@@ -466,6 +466,24 @@ export declare function createSubagentResume(deps: {
      *  isolation scope (first failure per site; later ones counted only). */
     onNotifyError?: (failure: import("../core/safe-notify.js").SafeNotifyFailure) => void;
 }): (content: string) => Promise<string>;
+/** Subagent transcript persistence — the RESOLVED delegation entry-caps pair (both members present;
+ *  see {@link resolveDelegationEntryCaps}). */
+export interface ResolvedDelegationEntryCaps {
+    maxConcurrent: number;
+    maxCumulativePerSession: number;
+}
+/**
+ * Subagent transcript persistence — resolve + LOUDLY validate `RunnerDeps.delegationEntryCaps`
+ * (#123 bad-value law: a garbage knob refuses with a coded error, it is never silently folded to
+ * the defaults). Refusal shapes: a member that is not a positive integer (NaN, 0, negative,
+ * fractional, non-number), and a RESOLVED pair where `maxConcurrent > maxCumulativePerSession`
+ * (you cannot run more agents at once than the tree may ever create — a contradiction, not a
+ * preference). Absent members take the exported CC-parity defaults.
+ */
+export declare function resolveDelegationEntryCaps(caps: {
+    maxConcurrent?: number;
+    maxCumulativePerSession?: number;
+} | undefined): ResolvedDelegationEntryCaps;
 /**
  * Options for {@link createSubagentTool}.
  *

package/dist/agents/subagent.js

@@ -24,7 +24,7 @@ import { BG_AGENT_REAP_STOP_ERROR } from "../core/task-registry.js";
 import { readDurableOrgAdmission } from "../core/memory-admission.js";
 import { extractErrorCode } from "../brain/errors.js";
 import { governanceRetryClass } from "../core/governance-codes.js";
-import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX, RUNNING_AGENT_OBSERVE_EVERY_BEATS } from "../config/defaults.js";
+import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX, RUNNING_AGENT_OBSERVE_EVERY_BEATS, DELEGATION_MAX_CONCURRENT_DEFAULT, DELEGATION_MAX_PER_SESSION_DEFAULT } from "../config/defaults.js";
 function rollupDelegatedCost(stats, nested) {
     if (stats.costMicroUsd === undefined)
         return undefined;
@@ -875,6 +875,43 @@ function parkCompletionNotify(deps) {
     };
     entry.deferredNotify = { ...(payload.seq !== undefined ? { seq: payload.seq } : {}), cancel, flush: () => deliver(false) };
 }
+export function resolveDelegationEntryCaps(caps) {
+    const bad = (member, value) => {
+        const e = new Error(`RunnerDeps.delegationEntryCaps.${member} holds ${typeof value === "number" ? String(value) : value === null ? "null" : typeof value} — must be a positive integer (or absent for the default). A bad cap refuses loudly; it is never silently folded to the default.`);
+        e.code = "config.delegation_entry_caps";
+        throw e;
+    };
+    const member = (name, fallback) => {
+        const v = caps?.[name];
+        if (v === undefined)
+            return fallback;
+        if (typeof v !== "number" || !Number.isInteger(v) || v <= 0)
+            bad(name, v);
+        return v;
+    };
+    const maxConcurrent = member("maxConcurrent", DELEGATION_MAX_CONCURRENT_DEFAULT);
+    const maxCumulativePerSession = member("maxCumulativePerSession", DELEGATION_MAX_PER_SESSION_DEFAULT);
+    if (maxConcurrent > maxCumulativePerSession) {
+        const e = new Error(`RunnerDeps.delegationEntryCaps resolves to maxConcurrent ${maxConcurrent} > maxCumulativePerSession ${maxCumulativePerSession} — a tree cannot run more agents at once than it may ever create. Fix the pair; a contradictory configuration refuses loudly.`);
+        e.code = "config.delegation_entry_caps";
+        throw e;
+    }
+    return { maxConcurrent, maxCumulativePerSession };
+}
+const delegationEntryLedgers = new WeakMap();
+function delegationEntryLedger(registry, key) {
+    let byKey = delegationEntryLedgers.get(registry);
+    if (byKey === undefined) {
+        byKey = new Map();
+        delegationEntryLedgers.set(registry, byKey);
+    }
+    let set = byKey.get(key);
+    if (set === undefined) {
+        set = new Set();
+        byKey.set(key, set);
+    }
+    return set;
+}
 export function normalizeSubagentType(value) {
     return value.normalize("NFKC").toLowerCase().replace(/[\p{White_Space}\p{Pd}_]+/gu, "");
 }
@@ -2432,6 +2469,53 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const shortDesc = reviveRow?.description ?? String(a.description ?? "sub-agent").slice(0, 200);
                 const bgOwner = reviveRow !== undefined ? reviveRow.owner : sessionScopedBg ? ctx.sessionId : ctx.taskId ?? bg.owner;
                 const bgScope = treeScope;
+                const capScope = bgScope;
+                const capRoot = reviveRow !== undefined
+                    ? (reviveRow.rootSessionId ?? reviveRow.parentSessionId ?? (reviveRow.sessionScoped ? reviveRow.owner : undefined))
+                    : (ctx.rootSessionId ?? ctx.sessionId);
+                const entryCaps = ctx.delegationEntryCaps ?? { maxConcurrent: DELEGATION_MAX_CONCURRENT_DEFAULT, maxCumulativePerSession: DELEGATION_MAX_PER_SESSION_DEFAULT };
+                const capLedgerKey = capScope !== undefined && capRoot !== undefined ? JSON.stringify([capScope, capRoot]) : undefined;
+                if (capScope !== undefined && capRoot !== undefined) {
+                    let storedHandles = [];
+                    let storedEnumerationOk = false;
+                    if (bg.agentStore !== undefined && reviveRow === undefined) {
+                        try {
+                            storedHandles = (await bg.agentStore.listBySession(capScope, capRoot)).map((r) => r.handle);
+                            storedEnumerationOk = true;
+                        }
+                        catch {
+                            storedHandles = [];
+                        }
+                    }
+                    const capRefusal = async (code, text) => {
+                        dropHostAbortListener();
+                        await cancelObserver();
+                        const wt = await finishWorktree();
+                        return { isError: true, content: `Sub-agent not started in background: ${text}${wt ? `\n${wt}` : ""}`, details: { error: code } };
+                    };
+                    const activeFace = bg.registry.activeDelegationHandles;
+                    const active = typeof activeFace === "function" ? activeFace.call(bg.registry, capScope, capRoot) : [];
+                    if (typeof activeFace === "function" && active.length >= entryCaps.maxConcurrent) {
+                        return await capRefusal("delegation.concurrency_cap", `this session tree already has ${active.length} background agents running — the concurrency cap (${entryCaps.maxConcurrent}; RunnerDeps.delegationEntryCaps.maxConcurrent) refuses another. Wait for one to complete (you will be notified) or stop one, then relaunch.`);
+                    }
+                    if (reviveRow === undefined) {
+                        const ledger = delegationEntryLedger(bg.registry, capLedgerKey);
+                        let cumulative;
+                        if (bg.agentStore !== undefined && storedEnumerationOk) {
+                            const keep = new Set([...storedHandles, ...active]);
+                            for (const h of [...ledger])
+                                if (!keep.has(h))
+                                    ledger.delete(h);
+                            cumulative = new Set([...storedHandles, ...ledger]).size;
+                        }
+                        else {
+                            cumulative = ledger.size;
+                        }
+                        if (cumulative >= entryCaps.maxCumulativePerSession) {
+                            return await capRefusal("delegation.session_cap", `this session tree has already launched ${cumulative} background agents in its retained window — the cumulative cap (${entryCaps.maxCumulativePerSession}; RunnerDeps.delegationEntryCaps.maxCumulativePerSession) refuses more. Continue an existing agent (SendMessage) instead of launching new ones.`);
+                        }
+                    }
+                }
                 const settlementSeat = ctx.delegationSettlement?.();
                 const bgSettleId = settlementSeat !== undefined ? `bg-${uuidv7()}` : undefined;
                 if (settlementSeat !== undefined && bgSettleId !== undefined) {
@@ -2554,6 +2638,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                     return { isError: true, content: `Sub-agent not started in background: ${e instanceof Error ? e.message : String(e)}${wt ? `\n${wt}` : ""}`, details: { error: "register_failed" } };
                 }
+                if (capLedgerKey !== undefined && reviveRow === undefined)
+                    delegationEntryLedger(bg.registry, capLedgerKey).add(taskId);
                 childInternals.peerSelfRef?.addAxis("h", taskId);
                 if (agentName !== undefined) {
                     recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...(reviveRow !== undefined ? ((reviveRow.rootSessionId ?? reviveRow.parentSessionId) !== undefined ? { rootSessionId: reviveRow.rootSessionId ?? reviveRow.parentSessionId } : {}) : (ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: reviveRow?.spawnedAt ?? Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));
@@ -2691,10 +2777,22 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         usage: { toolUses: toolStarts },
                     });
                 }, () => bg.registry.noteBackgroundAgentActivity(taskId));
+                const bgPlacementRoot = reviveRow !== undefined ? (reviveRow.rootSessionId ?? reviveRow.parentSessionId) : (ctx.rootSessionId ?? ctx.sessionId);
+                const bgPlacementParent = reviveRow !== undefined ? reviveRow.parentSessionId : ctx.sessionId;
+                const bgPlacement = bg.agentStore !== undefined && opts.runner.sessions.placements?.subagent !== undefined
+                    ? {
+                        kind: "subagent",
+                        ...(bgScope !== undefined ? { scope: bgScope } : {}),
+                        ...(bgPlacementParent !== undefined ? { parentSessionId: bgPlacementParent } : {}),
+                        ...(bgPlacementRoot !== undefined ? { rootSessionId: bgPlacementRoot } : {}),
+                        handle: taskId,
+                    }
+                    : undefined;
                 const bgInternals = bgSink
                     ? {
                         ...childInternals,
                         ...(bgQuestionStrip !== undefined ? bgQuestionStrip.internalsFlag : {}),
+                        ...(bgPlacement !== undefined ? { sessionPlacement: bgPlacement } : {}),
                         onNotifyInjectorReady: s2NotifyReady,
                         delegationTaskType: "background_agent",
                         ...(bgCycleSeq !== undefined ? { cycleSeq: bgCycleSeq } : {}),
@@ -2730,6 +2828,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     : {
                         ...childInternals,
                         ...(bgQuestionStrip !== undefined ? bgQuestionStrip.internalsFlag : {}),
+                        ...(bgPlacement !== undefined ? { sessionPlacement: bgPlacement } : {}),
                         onNotifyInjectorReady: s2NotifyReady,
                         delegationTaskType: "background_agent",
                         ...(bgCycleSeq !== undefined ? { cycleSeq: bgCycleSeq } : {}),
@@ -2760,7 +2859,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     };
                     try {
                         await opts.runner.sessions.acquire(bgChildSessionId, { requireExisting: true });
-                        await opts.runner.sessions.release(bgChildSessionId);
+                        if (opts.runner.sessions.forget)
+                            await opts.runner.sessions.forget(bgChildSessionId);
                     }
                     catch (e) {
                         const code = e.code;

package/dist/config/defaults.d.ts

@@ -21,6 +21,26 @@
  */
 export declare const RETAIN_DEFAULT_TTL_MS: number;
 export declare const RETAIN_DEFAULT_MAX = 16;
+/** Subagent transcript persistence — the delegation ENTRY caps (CC values: 20 concurrent /
+ *  200 per session tree). The INLET bound family (`RunnerDeps.delegationEntryCaps`), as opposed to
+ *  the retain pair above, which is a pure in-memory fast-lane handle bound (outlet — armed
+ *  deployments lose nothing when it evicts). Concurrent = running/pending a* handles under one
+ *  (scope, rootSessionId) key in THIS process's registry; cumulative = retained-window count under
+ *  the same key (see the enforcement site for the exact retained-window semantics). */
+export declare const DELEGATION_MAX_CONCURRENT_DEFAULT = 20;
+export declare const DELEGATION_MAX_PER_SESSION_DEFAULT = 200;
+/** Subagent transcript persistence — orphan adoption (CC parity: after a restart a deployment
+ *  auto-adopts at most this many stale rows whose transcript mtime is inside the window; older ones
+ *  stay MANUALLY continuable for the whole retention period — never deleted by the window). The
+ *  TRIGGER is deployment-owned (core has no daemon and never revives runs nobody asked for); these
+ *  constants are the shared vocabulary so every deployment adopts by the same numbers. */
+export declare const ORPHAN_ADOPT_WINDOW_MS_DEFAULT: number;
+export declare const ORPHAN_ADOPT_MAX_DEFAULT = 20;
+/** Subagent transcript persistence — the default transcript retention period (CC
+ *  cleanupPeriodDays parity). Core ships NO sweeper (design/151 ruling 2): the blessed path is the
+ *  deployment calling `TaskRegistry.reapDurableAgents` with `maxAgeMs` derived from this (boot +
+ *  every 24h is the reference cadence). */
+export declare const SUBAGENT_TRANSCRIPT_RETENTION_DAYS_DEFAULT = 30;
 /** Default idle TTL (days) before a cached session is evicted (config-catalog `session.idleTtlDays`). */
 export declare const SESSION_DEFAULT_TTL_DAYS = 7;
 /**

package/dist/config/defaults.js

@@ -1,4 +1,9 @@
 export const RETAIN_DEFAULT_TTL_MS = 30 * 60 * 1000;
 export const RETAIN_DEFAULT_MAX = 16;
+export const DELEGATION_MAX_CONCURRENT_DEFAULT = 20;
+export const DELEGATION_MAX_PER_SESSION_DEFAULT = 200;
+export const ORPHAN_ADOPT_WINDOW_MS_DEFAULT = 48 * 60 * 60 * 1000;
+export const ORPHAN_ADOPT_MAX_DEFAULT = 20;
+export const SUBAGENT_TRANSCRIPT_RETENTION_DAYS_DEFAULT = 30;
 export const SESSION_DEFAULT_TTL_DAYS = 7;
 export const RUNNING_AGENT_OBSERVE_EVERY_BEATS = 4;

package/dist/core/background-agent-store.d.ts

@@ -170,6 +170,7 @@ export interface BackgroundAgentRecord {
 export declare const REVIVED_ROW_CLEARED_FIELDS: readonly ["settledAt", "stoppedBy", "completionId", "finalOutput", "finalOutputFull", "error", "errorCode", "errorRetryable", "errorKind", "errorRetryAfterMs", "resultIsPartial", "summary", "recentSteps", "editedFiles", "usage"];
 /** Erase {@link REVIVED_ROW_CLEARED_FIELDS} from a record a revival is about to write back. */
 export declare function clearRevivedRowTerminalPayload(record: BackgroundAgentRecord): void;
+export declare function announceTranscriptIntegrityGapOnce(handle: string, sink: ((handle: string) => void) | undefined): void;
 /** Content-free projection for list reads (design/151 HIGH-1: `summary`/`finalOutput`/`recentSteps`
  *  and friends NEVER ride a list — content is get-by-handle only, behind the full predicate). */
 export interface BackgroundAgentRowSummary {

package/dist/core/background-agent-store.js

@@ -21,6 +21,19 @@ export function clearRevivedRowTerminalPayload(record) {
     for (const field of REVIVED_ROW_CLEARED_FIELDS)
         delete record[field];
 }
+const transcriptIntegrityAnnounced = new Set();
+export function announceTranscriptIntegrityGapOnce(handle, sink) {
+    if (sink === undefined)
+        return;
+    if (transcriptIntegrityAnnounced.has(handle))
+        return;
+    transcriptIntegrityAnnounced.add(handle);
+    try {
+        sink(handle);
+    }
+    catch {
+    }
+}
 export class BackgroundAgentStoreError extends Error {
     code;
     constructor(code, message) {

package/dist/core/mcp.d.ts

@@ -36,6 +36,7 @@ import type { AgentTool } from "../internal/harness-types.js";
 import type { ImageContent, TextContent } from "../internal/llm.js";
 import { type McpImageResizer } from "./image-downsample.js";
 import type { McpServerSpec, OnElicit, ToolEffect } from "./types.js";
+import { type ReminderDisclosureCounts } from "./reminder-disclosure.js";
 /**
  * The safety axes (design/77 §4 irreversibility, design/70 egress) derived from one materialized MCP
  * tool's server-advertised `annotations`. These ride alongside the {@link AgentTool} (which is vendored
@@ -462,7 +463,11 @@ export declare function normalizeMcpToolSchema(schema: unknown): McpSchemaNormal
  * combinator's own structure is legal JSON Schema ⇒ passes validateJsonSchemaShape too).
  */
 export declare function mcpToolSchemaProblem(schema: unknown): string | undefined;
-export declare function materializeMcpTools(specs: McpServerSpec[], principal?: string, onElicit?: OnElicit, imageResizer?: McpImageResizer): Promise<MaterializedMcp>;
+export declare function materializeMcpTools(specs: McpServerSpec[], principal?: string, onElicit?: OnElicit, imageResizer?: McpImageResizer, // design/116 CONFIRM-1 seam: deployment-injected; default = auto-detected sharp
+reminderDisclosure?: {
+    reminderMark?: string;
+    counts?: ReminderDisclosureCounts;
+}): Promise<MaterializedMcp>;
 /**
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.
  * Unlike server hints, the caller may RAISE or LOWER any axis: `effect` sets the repeat-safety class (lower to