@sema-agent/core 5.46.0 → 5.48.0

package/dist/agents/subagent.js

@@ -3,6 +3,8 @@ import { isAbsolute } from "node:path";
 import { withDelegationProvenance } from "../core/tool-policy.js";
 import { isHighSurrogate, isLowSurrogate } from "../core/surrogate-safe-slice.js";
 import { newDelegationProvenanceAggregate, reduceDelegationAttestation } from "../core/memory-engine/delegation-provenance.js";
+import { registerDelegationLaunch, replayExternalSettlementEffects, settleDelegation } from "../core/memory-engine/delegation-settlement.js";
+import { enqueueMemoryAnnouncement } from "../core/memory-engine/layout.js";
 import { resolveModel, resolveModelDisplayLabel } from "../core/roles.js";
 import { OUTPUT_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { TOOL_SEARCH_NAME } from "../core/runner/tool-disclosure.js";
@@ -22,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;
@@ -873,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, "");
 }
@@ -1935,6 +1974,59 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const shortDesc = `fork: ${(typeof a.description === "string" && a.description.trim() ? a.description.trim() : prompt).slice(0, 180)}`;
                     const bgOwner = sessionScopedBg ? ctx.sessionId : ctx.taskId ?? bg.owner;
                     const bgScope = treeScope;
+                    const forkSettlementSeat = ctx.delegationSettlement?.();
+                    const forkSettleId = forkSettlementSeat !== undefined ? `bg-${uuidv7()}` : undefined;
+                    if (forkSettlementSeat !== undefined && forkSettleId !== undefined) {
+                        try {
+                            registerDelegationLaunch(forkSettlementSeat.controlDir, { settleId: forkSettleId, sessionId: forkSettlementSeat.sessionId, now: Date.now, ...(ctx.toolCallId !== undefined ? { toolUseId: ctx.toolCallId } : {}) });
+                        }
+                        catch (e) {
+                            dropHostAbortListener();
+                            const wt = await finishWorktree();
+                            return {
+                                isError: true,
+                                content: `Sub-agent not started in background: the delegation settlement account could not record the launch (${(e instanceof Error ? e.message : String(e)).slice(0, 300)}) — fail-closed; repair the memory control plane or retry.${wt ? `\n${wt}` : ""}`,
+                                details: { error: "settlement_write_ahead_failed" },
+                            };
+                        }
+                    }
+                    const settleForkRow = (status) => {
+                        if (forkSettlementSeat === undefined || forkSettleId === undefined)
+                            return;
+                        const att = status !== undefined ? childAttestation(status) : undefined;
+                        const verdict = att === "external" ? "external" : att === "clean" ? "clean" : "unattestable";
+                        let settled = false;
+                        let lastErr;
+                        for (let attempt = 0; attempt < 3 && !settled; attempt++) {
+                            try {
+                                settleDelegation(forkSettlementSeat.controlDir, { settleId: forkSettleId, status: verdict, now: Date.now });
+                                settled = true;
+                            }
+                            catch (e) {
+                                lastErr = e;
+                            }
+                        }
+                        if (settled && verdict === "external") {
+                            try {
+                                replayExternalSettlementEffects(forkSettlementSeat.controlDir, { carry: true, now: Date.now });
+                            }
+                            catch {
+                            }
+                        }
+                        if (!settled) {
+                            const detail = lastErr instanceof Error ? lastErr.message : String(lastErr);
+                            try {
+                                enqueueMemoryAnnouncement(forkSettlementSeat.controlDir, {
+                                    kind: "gate",
+                                    at: Date.now(),
+                                    items: [`delegation settlement: the terminal observation for a background fork of session ${JSON.stringify(forkSettlementSeat.sessionId)} could NOT be recorded (verdict ${verdict}) — the row stays pending and expires as UNPROVEN at the settlement window (fail-closed floor): ${detail.slice(0, 200)}`],
+                                });
+                            }
+                            catch {
+                                console.warn(`[sema] delegation settlement terminal write failed (fork, verdict ${verdict}, session ${forkSettlementSeat.sessionId}): ${detail}`);
+                            }
+                        }
+                    };
                     let taskId;
                     try {
                         taskId = bg.registry.registerBackgroundAgent({
@@ -1962,6 +2054,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         catch {
                         }
                         const wt = await finishWorktree();
+                        if (forkSettlementSeat !== undefined && forkSettleId !== undefined) {
+                            try {
+                                settleDelegation(forkSettlementSeat.controlDir, { settleId: forkSettleId, status: "void", now: Date.now, note: "registration failed before invoke (not dispatched)" });
+                            }
+                            catch {
+                            }
+                        }
                         return { isError: true, content: `Sub-agent not started in background: ${e instanceof Error ? e.message : String(e)}${wt ? `\n${wt}` : ""}`, details: { error: "register_failed" } };
                     }
                     childInternals.peerSelfRef?.addAxis("h", taskId);
@@ -2106,6 +2205,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     void opts.runner
                         .runTask(bgForkSpec, bgForkInternals)
                         .then(async (child) => {
+                        settleForkRow(child.status);
                         dropHostAbortListener();
                         await finishWorktree();
                         try {
@@ -2202,6 +2302,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }
                     })
                         .catch((e) => {
+                        settleForkRow("failed");
                         dropHostAbortListener();
                         void finishWorktree();
                         const killed = abort.signal.aborted;
@@ -2268,7 +2369,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                     : `Note: it is stopped automatically (killed) if still running when this task ends — do not promise the user results beyond this task.`,
                             ],
                         }),
-                        details: { type: "agent", subagent_type: FORK_SUBAGENT_TYPE, status: "async_launched", isAsync: true, task_id: taskId, description: shortDesc, prompt },
+                        details: { type: "agent", subagent_type: FORK_SUBAGENT_TYPE, status: "async_launched", isAsync: true, task_id: taskId, description: shortDesc, prompt, ...(forkSettleId !== undefined ? { settle_id: forkSettleId } : {}) },
                     };
                 }
                 const bgIgnoredNote = a.run_in_background === true
@@ -2368,6 +2469,107 @@ 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) {
+                    try {
+                        registerDelegationLaunch(settlementSeat.controlDir, { settleId: bgSettleId, sessionId: settlementSeat.sessionId, now: Date.now, ...(ctx.toolCallId !== undefined ? { toolUseId: ctx.toolCallId } : {}) });
+                    }
+                    catch (e) {
+                        dropHostAbortListener();
+                        await cancelObserver();
+                        const wt = await finishWorktree();
+                        return {
+                            isError: true,
+                            content: `Sub-agent not started in background: the delegation settlement account could not record the launch (${(e instanceof Error ? e.message : String(e)).slice(0, 300)}) — fail-closed; repair the memory control plane or retry.${wt ? `\n${wt}` : ""}`,
+                            details: { error: "settlement_write_ahead_failed" },
+                        };
+                    }
+                }
+                const settleDelegationRow = (status) => {
+                    if (settlementSeat === undefined || bgSettleId === undefined)
+                        return;
+                    const att = status !== undefined ? childAttestation(status) : undefined;
+                    const verdict = att === "external" ? "external" : att === "clean" ? "clean" : "unattestable";
+                    let settled = false;
+                    let lastErr;
+                    for (let attempt = 0; attempt < 3 && !settled; attempt++) {
+                        try {
+                            settleDelegation(settlementSeat.controlDir, { settleId: bgSettleId, status: verdict, now: Date.now });
+                            settled = true;
+                        }
+                        catch (e) {
+                            lastErr = e;
+                        }
+                    }
+                    if (settled && verdict === "external") {
+                        try {
+                            replayExternalSettlementEffects(settlementSeat.controlDir, { carry: true, now: Date.now });
+                        }
+                        catch {
+                        }
+                    }
+                    if (!settled) {
+                        const detail = lastErr instanceof Error ? lastErr.message : String(lastErr);
+                        try {
+                            enqueueMemoryAnnouncement(settlementSeat.controlDir, {
+                                kind: "gate",
+                                at: Date.now(),
+                                items: [`delegation settlement: the terminal observation for a background delegation of session ${JSON.stringify(settlementSeat.sessionId)} could NOT be recorded (verdict ${verdict}) — the row stays pending and expires as UNPROVEN at the settlement window (fail-closed floor): ${detail.slice(0, 200)}`],
+                            });
+                        }
+                        catch {
+                            console.warn(`[sema] delegation settlement terminal write failed (verdict ${verdict}, session ${settlementSeat.sessionId}): ${detail} — the pending row expires as unproven at the settlement window`);
+                        }
+                    }
+                };
                 let taskId;
                 try {
                     taskId = bg.registry.registerBackgroundAgent(reviveRow !== undefined
@@ -2427,8 +2629,17 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     dropHostAbortListener();
                     await cancelObserver();
                     const wt = await finishWorktree();
+                    if (settlementSeat !== undefined && bgSettleId !== undefined) {
+                        try {
+                            settleDelegation(settlementSeat.controlDir, { settleId: bgSettleId, status: "void", now: Date.now, note: "registration failed before invoke (not dispatched)" });
+                        }
+                        catch {
+                        }
+                    }
                     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" }));
@@ -2566,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 } : {}),
@@ -2605,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 } : {}),
@@ -2635,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;
@@ -2744,6 +2969,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         : opts.runner.runTask(bgSpec, bgInternals);
                 void bgChildPromise
                     .then(async (child) => {
+                    settleDelegationRow(child.status);
                     closeObserverWindow(child.status);
                     dropHostAbortListener();
                     await finishWorktree();
@@ -2938,6 +3164,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                 })
                     .catch(async (e) => {
+                    settleDelegationRow("failed");
                     closeObserverWindow("failed");
                     dropHostAbortListener();
                     void finishWorktree();
@@ -3043,7 +3270,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 : `Note: it is stopped automatically (killed) if still running when this task ends — do not promise the user results beyond this task.`,
                         ],
                     }),
-                    details: { type: "agent", status: "async_launched", isAsync: true, task_id: taskId, description: shortDesc, prompt },
+                    details: { type: "agent", status: "async_launched", isAsync: true, task_id: taskId, description: shortDesc, prompt, ...(bgSettleId !== undefined ? { settle_id: bgSettleId } : {}) },
                 };
             }
             let child;

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/governance-codes.d.ts

@@ -67,3 +67,16 @@ export type RuleSyncDropReason = keyof typeof RULE_SYNC_DROP_CODES;
 /** The subset that may appear on a LOCAL quarantined row (design/182 §8.1 `quarantine` instruction /
  *  fence arm / local screening). `own_actor_forged` is inbound-only by construction. */
 export type RuleQuarantineReason = Exclude<RuleSyncDropReason, "own_actor_forged">;
+/**
+ * The presentation-tier registry (the server's wire whitelist retires into this
+ * table once shipped): WHO a notice code is for. `"user"` = a session-scoped disclosure the end
+ * user of that session should see (safe to project onto the session's event stream); `"operator"`
+ * = a deployment/config/ops fact for whoever runs the process. Presentation tier is a property of
+ * the CODE (closed set, one code one tier) — never of an individual emission, which is why this is
+ * a registry and not an EngineNotice field. Codes absent from the table read as `"operator"`
+ * (the conservative default: never push an unclassified code at an end user).
+ * Orthogonal to {@link NON_GOVERNANCE_MEMORY_CODES} (a retry-semantics table, not presentation).
+ */
+export declare const NOTICE_AUDIENCE: Readonly<Record<string, "user" | "operator">>;
+/** The audience for `code` — table lookup with the conservative `"operator"` default. */
+export declare function noticeAudienceOf(code: string): "user" | "operator";

package/dist/core/governance-codes.js

@@ -29,6 +29,28 @@ export const NON_GOVERNANCE_MEMORY_CODES = new Set([
     "memory.erasure_index_residue",
     "memory.export_incomplete",
     "memory.import_rejected",
+    "memory.hold_opened",
+    "memory.hold_released",
+    "memory.hold_disposed",
+    "memory.settlement_resolve_unattributed",
+    "memory.settlement_resolve_invalid",
+    "memory.settlement_resolve_unknown",
+    "memory.session_account_resolve_unattributed",
+    "memory.session_account_resolve_unknown",
+    "memory.hold_resolve_unattributed",
+    "memory.hold_resolve_invalid",
+    "memory.hold_resolve_unknown",
+    "memory.hold_resolve_invalid_state",
+    "memory.settlement_record_failed",
+    "memory.session_account_failed",
+    "memory.origin_clear_unattributed",
+    "memory.origin_clear_invalid",
+    "memory.origin_clear_unknown",
+    "memory.origin_clear_not_marked",
+    "memory.origin_clear_challenged",
+    "memory.origin_clear_pending",
+    "memory.origin_clear_conflict",
+    "memory.origin_clear_failed",
 ]);
 export function governanceRetryClass(code) {
     if (Object.prototype.hasOwnProperty.call(GOVERNANCE_CODES, code)) {
@@ -46,3 +68,14 @@ export const RULE_SYNC_DROP_CODES = {
     below_gc_frontier: "local-quarantined",
     server_rejected: "local-quarantined",
 };
+export const NOTICE_AUDIENCE = {
+    "memory.session_polluted": "user",
+    "memory.harvest_quarantined": "user",
+    "memory.delegation_static_mark_waived": "user",
+    "memory.hold_opened": "user",
+    "memory.hold_released": "user",
+    "memory.hold_disposed": "user",
+};
+export function noticeAudienceOf(code) {
+    return NOTICE_AUDIENCE[code] ?? "operator";
+}

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

package/dist/core/mcp.js

@@ -11,6 +11,7 @@ import { MCP_IMAGE_MAX_BASE64, sharpImageResizer } from "./image-downsample.js";
 import { sliceHeadSafe, sliceTailSafe } from "./surrogate-safe-slice.js";
 import { truncateError } from "./tool-errors.js";
 import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
+import { discloseReminderShaped } from "./reminder-disclosure.js";
 import { withContentOrigin } from "./memory-engine/content-origin.js";
 import { validateJsonSchemaShape } from "./runner/strict-output-schema.js";
 export const MCP_PREFIX = MCP_NAMESPACE.prefix;
@@ -649,7 +650,10 @@ export function mcpToolSchemaProblem(schema) {
     }
     return undefined;
 }
-export async function materializeMcpTools(specs, principal, onElicit, imageResizer) {
+export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure) {
+    const mcpDisclosure = reminderDisclosure?.reminderMark !== undefined
+        ? { mark: reminderDisclosure.reminderMark, windows: new Map(), ...(reminderDisclosure.counts !== undefined ? { counts: reminderDisclosure.counts } : {}) }
+        : undefined;
     const clients = [];
     const tools = [];
     const toolAxes = [];
@@ -661,7 +665,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
     const droppedTools = [];
     let disposing = false;
     const serverHandles = [];
-    const settled = await Promise.allSettled(specs.map((spec) => connectServer(spec, principal, onElicit, imageResizer)));
+    const settled = await Promise.allSettled(specs.map((spec) => connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure)));
     try {
         for (let i = 0; i < specs.length; i++) {
             const r = settled[i];
@@ -728,7 +732,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 try {
                     const listed = await listToolsLenient(h.client);
                     cacheMcpToolMetadata(h.client, listed.tools);
-                    const { serverTools, serverAxes, dropped } = intakeListedTools(listed, h.spec, h.client, h.health, imageResizer);
+                    const { serverTools, serverAxes, dropped } = intakeListedTools(listed, h.spec, h.client, h.health, imageResizer, mcpDisclosure);
                     const newNames = serverTools.map((t) => t.name);
                     const added = newNames.filter((n) => !h.toolNames.includes(n));
                     const removed = h.toolNames.filter((n) => !newNames.includes(n));
@@ -1119,7 +1123,7 @@ const LENIENT_CALL_TOOL_RESULT_SCHEMA = { safeParse: parseCallToolResultLenient
 async function listToolsLenient(client, options) {
     return client.request({ method: "tools/list", params: {} }, LenientListToolsResultSchema, options);
 }
-async function connectServer(spec, principal, onElicit, imageResizer) {
+async function connectServer(spec, principal, onElicit, imageResizer, reminderDisclosure) {
     const elicitOn = spec.elicitation === true && onElicit !== undefined;
     const health = { dead: false, pendingElicitations: 0, lastElicitationClosedAt: 0 };
     const client = new Client({ name: `sema-core/${spec.name}`, version: "0.1.0" }, { capabilities: elicitOn ? { elicitation: { form: {} } } : {} });
@@ -1155,7 +1159,7 @@ async function connectServer(spec, principal, onElicit, imageResizer) {
         };
         const listed = await listToolsLenient(client, startupOpts);
         cacheMcpToolMetadata(client, listed.tools);
-        const { serverTools, serverAxes, dropped } = intakeListedTools(listed, spec, client, health, imageResizer);
+        const { serverTools, serverAxes, dropped } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure);
         const caps = client.getServerCapabilities();
         const resourceInfo = caps?.resources
             ? {
@@ -1188,7 +1192,7 @@ async function connectServer(spec, principal, onElicit, imageResizer) {
         throw err;
     }
 }
-function intakeListedTools(listed, spec, client, health, imageResizer) {
+function intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure) {
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
@@ -1276,8 +1280,31 @@ function intakeListedTools(listed, spec, client, health, imageResizer) {
                         type: "text",
                         text: `[structuredContent] JSON with schema: ${inferCompactSchema(sc)}\n${truncateError(JSON.stringify(sc))}`,
                     });
-                    return { content, details: { type: "mcp", structuredContent: sc }, terminate: false };
                 }
+                if (reminderDisclosure !== undefined) {
+                    const textIdx = [];
+                    const segments = [];
+                    content.forEach((b, i) => {
+                        if (b.type === "text" && typeof b.text === "string") {
+                            textIdx.push(i);
+                            segments.push(b.text);
+                        }
+                    });
+                    const d = discloseReminderShaped({
+                        segments,
+                        mark: reminderDisclosure.mark,
+                        outlet: "mcp",
+                        defuseExactMark: true,
+                        throttle: { key: `${spec.name}:${remoteName}`, windows: reminderDisclosure.windows },
+                        ...(reminderDisclosure.counts !== undefined ? { counts: reminderDisclosure.counts } : {}),
+                    });
+                    if (d.defused)
+                        textIdx.forEach((ci, si) => (content[ci] = { type: "text", text: d.segments[si] }));
+                    if (d.trailer !== undefined)
+                        content.push({ type: "text", text: d.trailer });
+                }
+                if (sc !== undefined)
+                    return { content, details: { type: "mcp", structuredContent: sc }, terminate: false };
                 return { content, details: res, terminate: false };
             },
         });