@sema-agent/core 5.47.0 → 5.49.0

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # Changelog
 
+## 5.49.0 — 2026-08-20
+
+### Added
+- **`Runner.swapModels({models, tiers?})`** — the model-catalog hot-generation seat: switching
+  models is now a zero-restart operation. Atomic (the candidate is tier-expanded and validated
+  first; a failed swap leaves the current generation byte-identical); in-flight tasks finish on
+  their prepare-resolved models (natural snapshot — documented divergence window = exactly the
+  in-flight lifetime); `tiers` omitted keeps current bindings re-applied over the new models.
+  Announced via `config.models_swapped` (key counts only). Consumers: a deployment that deferred
+  model-catalog changes to a process restart can retire that arm.
+- design/337 (escalation/advisor mode) — the strategy repository becomes real cross-session
+  infrastructure:
+  - **`FileStrategyStore`** (persistence twin; per-strategy files under hashed scope dirs, atomic
+    writes, corrupt-entry quarantine, read-side hardening incl. symlink refusal and byte-bounded
+    reads) aggregated as `FileStorageBackend.strategyStore`.
+  - **CJK retrieval fixed**: term extraction shares the memory tokenizer (alnum runs + CJK
+    bigrams/unigrams) — a pure-CJK strategy was stored but never retrievable; old hits preserved
+    via a legacy acceptance arm.
+  - `TeacherRunResult.strategiesInjected` (id-level injection audit); store faults contained
+    (an optimization's failure no longer kills the run; disclosed via
+    `TeacherConfig.onStrategyStoreIncident`); injected strategies ride inside the untrusted
+    fence; write-side validation doors (`strategy.entry_invalid`); `seedStrategies` two-phase
+    batch install. Export surface +7, additive.
+- Conformance clause 31: an AMBIGUOUS origin representation (disagreeing carriers) is refused on
+  add and update by every backend; agreeing multi-carrier shapes stay legal (the refusal keys on
+  disagreement — serialization closure). The bundled File backend already refused; the clause is
+  the machine face proving all backends answer alike, and it caught the reference template
+  lacking the refusal the moment it landed (template fixed in the same commit).
+
+### Fixed
+- A 13-finding memory-engine hardening batch (post-release scan of the 5.47 window; all
+  externally disclosed):
+  - **Dual-root deployments regain the hold-notice family**: `mergeHarvestReports` now merges
+    `HarvestReport.containment` (booleans OR, lists concatenated) — under a two-plane scope
+    contract the entire `memory.hold_*` family and the index-rollback announce arm were
+    structurally unreachable.
+  - Hold lifecycle: a refused instruction intake finalizes its row (no resurrection by
+    reconciliation); a failed expired-hold release announces once and consumes its verdict
+    (generation-keyed — no infinite re-fire); disposal reporting rides the one signal path.
+  - Origin clearance: a foreign deletion is no longer read as "our tombstone committed"
+    (`tombstonedAt` sidecar; bare absence refuses with custody retained); a concurrent on-disk
+    edit is not overwritten by the clearance re-record (divergence guard, byte-equality
+    exemption for pristine projections); a challenged entry cannot be washed through the resume
+    path.
+  - Read side: the recall-taint judge accepts the Read tool's `path` argument spelling; the
+    marked-projection index drop judges path tokens per occurrence (an innocent clean entry
+    whose name merely contains a marked path no longer over-drops); a read-only plane under
+    carry injects the treated index text; index-drop rewrites are announced when they land.
+  - The opaque handle/search rows no longer carry a model-authored entry id verbatim (digest
+    re-mint on marked commits; the passive-face zero-model-text contract now holds).
+  - `memory_search`'s header states band order truthfully on mixed-band pages (single-band and
+    off pages byte-identical).
+- The transcript-integrity notice keys its once-latch by (scope, handle) and carries `scope` in
+  the detail — multi-tenant attribution without reverse lookup.
+
+### Notes
+- Behavior narrowings (all refusals in existing coded families, disclosed): clearEntryOrigin
+  gains three refusals (divergence / bare-absence / challenged-resume); marked adds do not adopt
+  model-supplied ids; a failed expired-hold release stops re-firing after one loud announcement;
+  refused intakes finalize. Two optional sidecar row members (`OriginClearanceRow.tombstonedAt`,
+  `HoldRow.resolvedAt`) — strict coercers accept old rows. No BREAKING changes; no export
+  removals.
+
+## 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, scope: string | undefined) => 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, access.scope, 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 (scope, 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, scope: string | undefined) => 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, scope, 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, scope, 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/agents/teacher.d.ts

@@ -1,5 +1,5 @@
 import type { Runner } from "../core/runner/runtask.js";
-import type { StrategyStore } from "../core/strategy-store.js";
+import { type StrategyOrigin, type StrategyStore, type StrategyStoreIncident } from "../core/strategy-store.js";
 import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
 /**
  * Teacher mode (escalation cascade): a cheap "student" does the work; a strong "teacher" is consulted
@@ -85,6 +85,17 @@ export interface TeacherConfig {
     minConfidenceToStore?: number;
     /** Inject retrieved strategies into the objective. Default true when a store+scope are set. */
     injectStrategies?: boolean;
+    /**
+     * Disclosure sink for a strategy-store failure this loop CONTAINED (store-fault containment): a
+     * `find` that failed injects nothing, a `save` that failed stores nothing — neither ever fails the
+     * task (the repository is an optimization; an optimization's fault must not kill the work it was
+     * optimizing) — but each is disclosed here so a broken store is discoverable. The one exception
+     * stays loud: an error carrying a `config.`-prefixed code (an illegal `retrieveK` etc.) is a
+     * PROGRAMMER error and rethrows — containing it would silence the validation door entirely.
+     * Callback faults are themselves contained (safe-notify posture); absent ⇒ `console.warn`, once
+     * per op kind.
+     */
+    onStrategyStoreIncident?: (i: StrategyStoreIncident) => void;
 }
 export type EscalationTrigger = "stuck" | "blocked" | "failed" | "verify-fail";
 export interface TeacherAdvice {
@@ -105,6 +116,19 @@ export interface EscalationRecord {
 export interface TeacherRunResult extends TaskResult {
     /** Escalations that occurred during this run (empty if the student succeeded alone). */
     escalations: EscalationRecord[];
+    /**
+     * Audit trail of the strategies retrieved into the student's objective for THIS run — id-level (the
+     * text is not copied; the id is the join key into the store), with each entry's stored timestamp and
+     * provenance stamp. Lets a host connect "what was injected" to "how the run ended" offline, which is
+     * the only way retrieval-induced degradation is ever measurable. PRESENT iff ≥1 strategy was
+     * injected; ABSENT means no store was configured, injection was disabled, retrieval matched nothing,
+     * or the find failed (a failure additionally raises `onStrategyStoreIncident`).
+     */
+    strategiesInjected?: Array<{
+        id: string;
+        ts: string;
+        origin?: StrategyOrigin;
+    }>;
     /** Usage spent on the teacher (advisor), separate from the student's `stats` (which includes the
      *  cheap helper monitor/verifier calls). `tasks` = teacher runs (escalation asks + any takeover).
      *  `humanReview` = the HITL-gate burden of the teacher's runs (notably a takeover that hit an approval