@sema-agent/core 5.46.0 → 5.48.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # 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
+- design/336 slices 2+3 — the F-020 deep fix completes:
+  - **Slice 2 (settlement + hold)**: a delegation's memory-pollution verdict is a durable
+    SETTLEMENT ACCOUNT (three strict side-ledgers; write-ahead launch rows; crash-idempotent
+    retry; fork/bg lane parity), and instruction-form files under exposure ride a three-state
+    HOLD (held → released/disposed, loud timeout `config.memory_hold_timeout`;
+    `MemoryEngineOptions.holdSettleTimeoutMs`). `HarvestReport.containment` (#331) and the
+    `memory.hold_*` notice family land with it. The origin representation family is
+    serialization-closed (carrier tokenization + round-trip property laws).
+  - **Slice 3 (read side + human faces)**: `memory_search` returns two exposure bands (clean
+    first; `MemoryEntryHeader.exposure`; `MemorySearchHit` becomes a discriminated union
+    CleanHit | ExposedHit — see BREAKING); exposed entries render as opaque handles (zero
+    model-authored text on the passive face); `memory_get` delivery carries a fact-form banner
+    and marks the session derived (`onTaintedDelivery` — mechanical closure of source-scope
+    laundering); the memory-dir Read lane head-parses committed origin. Human faces (host API
+    only, deliberately no model tool): `listExternalOriginEntries` + `clearEntryOrigin` (audited
+    un-mark: write-ahead custody → committed tombstone → same-id re-record;
+    `listOriginClearances`; `memory.origin_clear_*` family). A live behavioral probe pins that a
+    marked entry in context is still used normally (deepseek-v4-flash, zero refusal).
+  - `memoryProvenance: "off"` keeps every read face byte-identical to 5.46 (pinned directly).
+- `NOTICE_AUDIENCE` + `noticeAudienceOf` — the presentation-tier registry (who a notice code is
+  for): "user" for the session-memory posture disclosures, everything else defaults "operator".
+  `EngineNotice.sessionId` typed top-level key, lifted from `detail.sessionId` at the delivery
+  throat (mint sites untouched). `ambiguousOriginRepresentation` exported (the origin ambiguity
+  predicate a third-party backend refuses multi-carrier representations with).
+- The session-reconcile never-started texts condition their re-issue cue on the blocking
+  approval/gate being resolved first (#352 — the side-effect statement stayed true; the action
+  cue no longer amplifies a blocked-approval loop).
+
+### Changed
+- **BREAKING (types)**: `MemorySearchHit` is now a discriminated union (CleanHit | ExposedHit)
+  instead of a single interface. Backend contract: the conformance suite gains two cases
+  (exposure carriage + two-band truncation boundary) — a backend implementing the pre-336 shape
+  fails them (upgrade-order duty: adopt the new clauses before taking 5.47 in a mixed fleet).
+  `memory_get` tool contract revision 3→4, `memory_search` 2→3 (execute-visible text changes).
+- The kill-tree descendant-reap suite's liveness probe reads a ZOMBIE as dead (a landed SIGKILL
+  whose parent died first waits for init to reap it; under load that outlasted any fixed poll
+  window — the 5.30.0/5.46.0 publish-gate flake, root-caused and fixed).
+
 ## 5.46.0 — 2026-08-19
 
 ### 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}.
  *