@sema-agent/core 5.55.0 → 5.56.0

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

@@ -2,6 +2,16 @@
  *  lines from a still-running watch). Everything else is a terminal completion notification. */
 export type TaskNotificationStatus = "completed" | "failed" | "killed" | "cancelled" | "event";
 export type SystemInjectionPriority = "now" | "next" | "later";
+/** The closed value set of {@link SystemInjectionPriority}, as data — the wire-facing entries validate
+ *  against THIS rather than against three inline string literals, so widening the type widens the guard.
+ *  (Names taken verbatim from CC 2.1.223's `UYo` @ `CC:644918`; see the semantics note on
+ *  {@link SystemInjection.priority} for which of CC's behaviors this engine implements.) */
+export declare const SYSTEM_INJECTION_PRIORITIES: readonly SystemInjectionPriority[];
+/** backlog #389 伴生 (D-3, bad-value loudness) — is this a priority this engine knows at all? A value
+ *  outside the set is a caller bug that must be refused, never silently folded into a default: the
+ *  no-subscriber retain path indexes `queues[priority]` and the park path stores it verbatim, so an
+ *  unknown value used to travel until something downstream failed on it (or didn't, and lied). */
+export declare function isSystemInjectionPriority(value: unknown): value is SystemInjectionPriority;
 export interface TaskNotificationPayload {
     task_id: string;
     /** design/144 §2: `"external"` is CORE-MINTED ONLY — `TaskStream.notify()` casts it onto every
@@ -137,13 +147,30 @@ export interface ExternalNotificationInput {
 }
 export interface SystemInjection<TPayload = unknown> {
     kind: "task_notification";
-    /** design/116 §7, re-anchored 2026-08-05 (CC 2.1.221): EVERY priority delivers at the NEXT turn
-     *  boundary via harness.steer(), mid-work included — CC's queued task-notification inputs are
-     *  unconditionally deliverable at the boundary, and the old later→followUp mapping (deliver only
-     *  when the agent would otherwise stop) starved busy models of the very completion they were told
-     *  not to poll for. Delivery is ARRIVAL order (consecutive frames batch); `priority` affects only the park/uplink
-     *  path. A delivery that races the agent going idle parks on PendingSessionNotifications for the
-     *  session's next run. `drain()` serves that parked lane. */
+    /**
+     * design/116 §7 — in THIS engine every priority delivers at the NEXT turn boundary via
+     * `harness.steer()`, mid-work included, in ARRIVAL order (consecutive frames batch); `priority`
+     * affects only the park/uplink path. A delivery that races the agent going idle parks on
+     * PendingSessionNotifications for the session's next run; `drain()` serves that parked lane.
+     *
+     * **Anchor correction (backlog #389 伴生 / hallucination audit H-1).** The 2026-08-05 re-anchor
+     * justified flattening the ladder with "CC's queued task-notification inputs are UNCONDITIONALLY
+     * deliverable at the boundary (CC 2.1.221)". That sentence is FALSE as a statement about CC, on
+     * 221 and 223 alike: the mid-turn fold is gated at `getCommandsByMaxPriority("next")`
+     * (`pretty221.js:449195` / `pretty223.js:415586`), which admits `now`+`next` and EXCLUDES `later`
+     * — and `enqueuePendingNotification` defaults to `later`. CC's background-completion notices fold
+     * mid-turn because they explicitly say `priority:"next"`; its ultraplan/artifact notices take the
+     * default and deliberately do NOT. So all three of CC's values carry live delivery semantics
+     * (`now` = abort the running turn, `next` = fold into it, `later` = wait for the next one).
+     *
+     * The engineering conclusion the re-anchor reached — a background completion must reach a busy
+     * model at the boundary rather than starve behind a "deliver only when it would otherwise stop"
+     * rule — stands on its own. What does not stand is the claim that CC has no ladder. Restoring the
+     * `later` = "do not fold into the running turn" arm is a behavior-face change and `now` = "abort
+     * the running turn" is a new capability; both are ruled changes, not silent ones. Until then the
+     * gap is DISCLOSED at the injection funnel rather than left as a silently inert knob (`now` is
+     * announced, an unknown value is refused) — the bad-value loudness rule.
+     */
     priority: SystemInjectionPriority;
     dedupKey: string;
     payload: TPayload;

package/dist/core/task-notification.js

@@ -1,4 +1,8 @@
 import { inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
+export const SYSTEM_INJECTION_PRIORITIES = ["now", "next", "later"];
+export function isSystemInjectionPriority(value) {
+    return typeof value === "string" && SYSTEM_INJECTION_PRIORITIES.includes(value);
+}
 const TASK_NOTIFICATION_TAGS = [
     "task-notification",
     "task-id",
@@ -214,6 +218,9 @@ export class SystemInjectionQueue {
     listeners = new Set();
     droppedOldest = 0;
     enqueue(item) {
+        if (!isSystemInjectionPriority(item.priority)) {
+            throw new Error(`SystemInjectionQueue: unknown priority ${JSON.stringify(item.priority)} — expected one of ${SYSTEM_INJECTION_PRIORITIES.join("/")}`);
+        }
         if (this.dedup.has(item.dedupKey))
             return false;
         this.dedup.add(item.dedupKey);
@@ -239,7 +246,10 @@ export class SystemInjectionQueue {
         return true;
     }
     drain(priority) {
-        const priorities = priority ? [priority] : ["now", "next", "later"];
+        if (priority !== undefined && !isSystemInjectionPriority(priority)) {
+            throw new Error(`SystemInjectionQueue: unknown priority ${JSON.stringify(priority)} — expected one of ${SYSTEM_INJECTION_PRIORITIES.join("/")}`);
+        }
+        const priorities = priority ? [priority] : [...SYSTEM_INJECTION_PRIORITIES];
         const out = [];
         for (const p of priorities) {
             const q = this.queues[p];

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

@@ -166,11 +166,23 @@ export declare function parkBackgroundAgentLane(core: DurableAgentCore, id: stri
  * design/153 §7.1 (件1 codex HIGH split-brain fence) — the registry-aware reconciliation entry an
  * IN-PROCESS deployment calls on its retention cadence. Two halves, one call:
  *  1. LIVE half: this instance's own parked handles are probed against their checkpoint and, on
- *     expired/missing, settled failed THROUGH the handle (poll/stop/durable row stay coherent —
- *     quiescence poked, arbitration closure dropped, durable clear rides the settle write).
+ *     expired/missing/DECIDED-ELSEWHERE, settled failed THROUGH the handle (poll/stop/durable row
+ *     stay coherent — quiescence poked, arbitration closure dropped, durable clear rides the settle
+ *     write).
  *  2. STORE half: delegates to the store-level {@link reconcileParkedAgents} with
  *     `excludeWriterId` = this instance's writerId, so foreign (dead-process) rows are cleaned
  *     without ever touching a row this process is live-managing.
+ *
+ * backlog #400 — the live half used to skip EVERY non-expired/missing state, `resolved` included, and
+ * that was the whole zombie: a parked row whose checkpoint was decided by the task-level
+ * `resumeCheckpoint` leg (a serving layer's documented fallback when its parked-row discriminator
+ * misses) is decided but still says `parked`, its side effects already executed by a path that never
+ * touched this registry. Nothing else could reach it either — a re-claim answers
+ * `checkpoint_not_pending`, and the store half excludes exactly the rows this process live-manages —
+ * so it stayed `parked` for the life of the process. It now converges here. The one `resolved` case
+ * that must still be LET THROUGH is the registry's own claim window (reservation → consume flip): that
+ * skip is load-bearing, and it is now expressed as what it actually is — a claim in flight — instead
+ * of as a blanket state filter that also swallowed the case with no claimant at all.
  */
 export declare function reconcileParkedAgentsLane(core: DurableAgentCore, stores: {
     agentStore: import("./background-agent-store.js").BackgroundAgentStore;
@@ -275,7 +287,12 @@ export declare function abortBackgroundAgentsForOwnerLane(core: DurableAgentCore
  *  SendMessage consume, so the two verbs can never drift. Ladder:
  *   0a. verbatim `handle.name` match — LATEST-WINS (CC SendMessage.md: "a newer agent took the name
  *       (latest wins)"; older rows stay task_id-addressable), any status (names keep working after
- *       completion — the resume face is the CC "resumes it from its transcript" counterpart);
+ *       completion — the resume face is the CC "resumes it from its transcript" counterpart).
+ *       **Latest-wins is RESOLUTION, not permission to redirect a conversation**: CC pairs the same
+ *       resolver with a per-conversation pin guard (`send_message_pin_guard`), and SendMessage REFUSES
+ *       a send whose name has changed hands since this caller last used it. That guard lives at the
+ *       SendMessage face (`createSendMessageTool`), exactly as it does upstream — this resolver stays
+ *       a pure resolver, and TaskStop keeps its own (preferRunning) posture untouched;
  *   0b. normalized `handle.name` match — same latest-wins (the spawn regex bans whitespace, so
  *       normalization here is effectively NFKC+lowercase: "Builder"/"builder" share the name pool);
  *   1+. the pre-[c209] description layers, UNCHANGED (exact → normalized, running-preferred +

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

@@ -484,12 +484,41 @@ export async function reconcileParkedAgentsLane(core, stores, scope, now, opts)
                 state = "unreadable";
             }
         }
-        if (state !== "expired" && state !== "missing")
+        let error;
+        if (state === "expired" || state === "missing") {
+            error = `approval checkpoint ${state} while parked (reconciled)`;
+        }
+        else if (state === "resolved") {
+            let row;
+            try {
+                row = await stores.agentStore.get(handle.id, scope);
+            }
+            catch {
+                continue;
+            }
+            if (row === null || row.status !== "parked" || row.parkClaimId !== undefined)
+                continue;
+            try {
+                const reread = (await stores.checkpointStore.get(token));
+                if (reread === null || reread.status !== "resolved")
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            error =
+                "approval checkpoint resolved outside the registry's claim path while parked — the decision was " +
+                    "redeemed by another leg and this row's outcome is unknown (reconciled)";
+        }
+        else {
             continue;
+        }
         if (handle.status !== "parked")
             continue;
+        if (handle.parkedCheckpointToken !== token)
+            continue;
         handle.status = "failed";
-        handle.error = `approval checkpoint ${state} while parked (reconciled)`;
+        handle.error = error;
         handle.parkedCheckpointToken = undefined;
         handle.resolveParkedStop = undefined;
         handle.updatedAt = now;

package/dist/core/tool-policy.d.ts

@@ -384,12 +384,17 @@ export interface ToolPolicyProjection {
     readonly requiresLiveRemainder: boolean;
 }
 /**
- * The entries of a tool-NAME list whose reach is a set of names rather than one name — the MCP
- * covering spellings (`mcp__<server>`, `mcp__<server>__<glob>`) that CC's rule matcher resolves and
- * an exact-membership test silently cannot. Every name-keyed lane in this file consults these
- * ALONGSIDE its exact set: a covering spelling can never equal a minted tool name (`*` is outside the
- * minted charset and a minted name always carries a tool segment), so leaving it in the exact set too
- * costs nothing and keeps the projection/audit faces reporting the operator's own spelling.
+ * The entries of a tool-NAME list whose reach is a set of names rather than one name — the covering
+ * spellings (`<ns>__<peer>`, `<ns>__<peer>__<glob>`) of ANY protocol namespace, which CC's rule
+ * matcher resolves and an exact-membership test silently cannot. Every name-keyed lane in this file
+ * consults these ALONGSIDE its exact set: a covering spelling can never equal a minted tool name (`*`
+ * is outside the minted charset and a minted name always carries a tool segment), so leaving it in the
+ * exact set too costs nothing and keeps the projection/audit faces reporting the operator's own spelling.
+ *
+ * Namespace-generic on purpose: the covering grammar is a property of the shared `<prefix><peer>__<tool>`
+ * name shape, not of MCP, and keying it to one prefix made every sibling-namespace covering rule
+ * (`a2a__<peer>__*`) compile clean and match nothing — inert in the deny half, and in an ALLOW list the
+ * removal of that peer's whole tool set.
  *
  * The list is usually empty, which is why every call site tests it before scanning.
  *
@@ -398,9 +403,9 @@ export interface ToolPolicyProjection {
  * list these): all four publishers of {@link ToolPolicyNameSets} must resolve a covering entry the same
  * way, because the prepare-time audit's exemption for these spellings speaks for all of them at once.
  */
-export declare function mcpCoveringEntries(entries: readonly string[] | undefined): readonly string[];
-/** Does any covering entry reach `toolName`? See {@link mcpCoveringEntries}. */
-export declare function mcpCoveringHit(covering: readonly string[], toolName: string): boolean;
+export declare function namespacedCoveringEntries(entries: readonly string[] | undefined): readonly string[];
+/** Does any covering entry reach `toolName`? See {@link namespacedCoveringEntries}. */
+export declare function namespacedCoveringHit(covering: readonly string[], toolName: string): boolean;
 /**
  * Execute a persisted {@link ToolPolicyProjection} against a call (F-012 L1): returns the first
  * component's deny, or `undefined` when the projection has no opinion (it is deny-only by

package/dist/core/tool-policy.js

@@ -5,7 +5,8 @@ import { join, normalize as normalizePath, posix as posixPath, sep, win32 as win
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
 import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
-import { isMcpCoveringRuleName, mcpRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
+import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
+import { protocolOf } from "./protocol-table.js";
 import { isAbsolutePathForm, isWinFormPath, writeTargetPath } from "../tools/fs/safety.js";
 const DECISION_REASONS = ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable"];
 const DECISION_REASON_SET = new Set(DECISION_REASONS);
@@ -36,22 +37,22 @@ export const ASK_EVIDENCE_ABSENCE_VALUES = ["not_wired", "not_adjudicated", "una
 export function decisionText(d) {
     return d.message;
 }
-export function mcpCoveringEntries(entries) {
-    return (entries ?? []).filter(isMcpCoveringRuleName);
+export function namespacedCoveringEntries(entries) {
+    return (entries ?? []).filter(isNamespacedCoveringRuleName);
 }
-export function mcpCoveringHit(covering, toolName) {
-    return covering.length > 0 && covering.some((e) => mcpRuleNameCovers(e, toolName));
+export function namespacedCoveringHit(covering, toolName) {
+    return covering.length > 0 && covering.some((e) => namespacedRuleNameCovers(e, toolName));
 }
 export function checkToolPolicyProjection(projection, req) {
     for (const c of projection.components) {
         if (c.kind === "tool_deny") {
-            if (c.names.includes(req.toolName) || mcpCoveringHit(mcpCoveringEntries(c.names), req.toolName)) {
+            if (c.names.includes(req.toolName) || namespacedCoveringHit(namespacedCoveringEntries(c.names), req.toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by a frozen inherited policy projection` };
             }
             continue;
         }
         if (c.kind === "tool_allowlist") {
-            if (!c.names.includes(req.toolName) && !mcpCoveringHit(mcpCoveringEntries(c.names), req.toolName)) {
+            if (!c.names.includes(req.toolName) && !namespacedCoveringHit(namespacedCoveringEntries(c.names), req.toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is not in a frozen inherited policy projection's allowlist` };
             }
             continue;
@@ -179,11 +180,15 @@ export function createAllowDenyPolicy(opts) {
             return undefined;
         const kept = [];
         for (const entry of entries) {
-            if (entry.startsWith("mcp__")) {
-                const segments = entry.slice("mcp__".length).split("__");
-                if (segments.some((seg) => seg.length === 0)) {
-                    const lesson = `a malformed MCP tool name (empty segment) — it can never match any mounted tool. ` +
-                        `Use \`mcp__<server>\` for every tool of a server, or \`mcp__<server>__<tool>\` for one tool.`;
+            const ns = protocolOf(entry);
+            if (ns !== undefined) {
+                const suffix = entry.slice(ns.prefix.length);
+                const sep = suffix.indexOf("__");
+                const malformed = suffix.length === 0 || sep === 0 || (sep > 0 && suffix.length === sep + 2);
+                if (malformed) {
+                    const family = ns.id.toUpperCase();
+                    const lesson = `a malformed ${family} tool name (empty peer or tool segment) — it can never match any mounted tool. ` +
+                        `Use \`${ns.prefix}<peer>\` for every tool of a peer, or \`${ns.prefix}<peer>__<tool>\` for one tool.`;
                     invalid.push({ entry, list, message: `"${entry}" is ${lesson}`, lesson });
                     continue;
                 }
@@ -224,8 +229,8 @@ export function createAllowDenyPolicy(opts) {
     opts = { ...opts, ...(screenedAllow ? { allow: screenedAllow } : {}), ...(screenedDeny ? { deny: screenedDeny } : {}) };
     const allow = opts.allow ? new Set(opts.allow) : undefined;
     const deny = new Set(opts.deny ?? []);
-    const denyCovering = mcpCoveringEntries(opts.deny);
-    const allowCovering = mcpCoveringEntries(opts.allow);
+    const denyCovering = namespacedCoveringEntries(opts.deny);
+    const allowCovering = namespacedCoveringEntries(opts.allow);
     return {
         projection: {
             components: [
@@ -237,10 +242,10 @@ export function createAllowDenyPolicy(opts) {
         nameSets: [{ ...(opts.allow ? { allow: [...opts.allow] } : {}), ...(opts.deny ? { deny: [...opts.deny] } : {}) }],
         check(req) {
             const toolName = req.toolName;
-            if (deny.has(toolName) || mcpCoveringHit(denyCovering, toolName)) {
+            if (deny.has(toolName) || namespacedCoveringHit(denyCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
             }
-            if (allow && !allow.has(toolName) && !mcpCoveringHit(allowCovering, toolName)) {
+            if (allow && !allow.has(toolName) && !namespacedCoveringHit(allowCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is not in the allowlist` };
             }
             return ALLOW;
@@ -257,9 +262,9 @@ export function createApprovalPolicy(opts) {
     const need = new Set(opts.requireApproval);
     const deny = new Set(opts.deny ?? []);
     const auto = new Set(opts.autoAllow ?? []);
-    const needCovering = mcpCoveringEntries(opts.requireApproval);
-    const denyCovering = mcpCoveringEntries(opts.deny);
-    const autoCovering = mcpCoveringEntries(opts.autoAllow);
+    const needCovering = namespacedCoveringEntries(opts.requireApproval);
+    const denyCovering = namespacedCoveringEntries(opts.deny);
+    const autoCovering = namespacedCoveringEntries(opts.autoAllow);
     return {
         projection: {
             components: [
@@ -277,10 +282,10 @@ export function createApprovalPolicy(opts) {
         ],
         async check(req, signal) {
             const toolName = req.toolName;
-            if (deny.has(toolName) || mcpCoveringHit(denyCovering, toolName)) {
+            if (deny.has(toolName) || namespacedCoveringHit(denyCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
             }
-            if (need.has(toolName) || mcpCoveringHit(needCovering, toolName)) {
+            if (need.has(toolName) || namespacedCoveringHit(needCovering, toolName)) {
                 if (signal?.aborted) {
                     return withCoreMintedResolution({ action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, settledBy: "aborted" }, "task_aborted", req);
                 }
@@ -314,7 +319,7 @@ export function createApprovalPolicy(opts) {
                 }
                 return withCoreMintedResolution({ action: "deny", message: `approval denied for "${req.toolName}"`, settledBy: "human" }, "human_refused", req);
             }
-            if (opts.denyByDefault && !auto.has(toolName) && !mcpCoveringHit(autoCovering, toolName)) {
+            if (opts.denyByDefault && !auto.has(toolName) && !namespacedCoveringHit(autoCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" requires explicit allow` };
             }
             return ALLOW;

package/dist/core/types.d.ts

@@ -657,8 +657,9 @@ export interface ToolExecuteContext {
     /**
      * Subagent transcript persistence — the RESOLVED delegation entry caps for this run
      * ({@link RunnerDeps.delegationEntryCaps} after prepare's loud validation; both members always
-     * present). Runner-filled trusted seat, never a model argument — the Agent tool's background lane
-     * reads it at its registration point. Undefined outside a Runner task (the lane then applies the
+     * present). Runner-filled trusted seat, never a model argument — the Agent tool's spawn gate reads
+     * it on EVERY local lane (background, background-fork, sync fork, sync spawn), each at its own
+     * launch point. Undefined outside a Runner task (the lane then applies the
      * exported defaults itself, so a directly-driven tool is bounded too).
      */
     delegationEntryCaps?: {
@@ -2543,9 +2544,12 @@ export interface TaskSpec {
      * Override auto-compaction thresholds for this task's session. Compaction (LLM summary, persisted
      * to the session) runs in two places sharing these settings: at every within-task turn boundary
      * (design/64 §25 (A) — the long-single-task case) and once at task end (the between-task case).
-     * Defaults: enabled, reserveTokens 16384, keepRecentTokens 0 (design/169-C, CC full-compaction
-     * form: the summary replaces the compacted region entirely by default — set `keepRecentTokens`
-     * explicitly to keep a verbatim recent tail; 20000 was the pre-169 default) — repaired
+     * Defaults: enabled, reserveTokens 16384, keepRecentTokens 0 (design/169-C; 20000 was the
+     * pre-169 default). A zero budget is NOT "no verbatim tail": the cut-point search has a
+     * structural floor under the budget, so the default already leaves the last exchange verbatim
+     * after the summary (a trailing tool-result batch keeps its emitting assistant with it) — the
+     * same one-group posture CC's reactive compaction ships. Set `keepRecentTokens` explicitly only
+     * to keep a WIDER tail than that. Repaired
      * automatically when
      * pathological for the model's window: threshold ≤ 0, keepRecent ≥ threshold, or a threshold above
      * the clearStale point (0.7×window — the prefix-cache "death band", design/64 §26.4) is clamped
@@ -4862,6 +4866,24 @@ export interface EngineNotice {
      *    #257 contract's "accepted = enqueued, not consumed" sentence;
      *    `detail: { steer, taskId? }` / `{ followUp, taskId? }`. Per-run, at most once per family
      *    (the terminal sweep is a single site).
+     *    **#389 (two corrections).** ① The family now fires on the INTERRUPT path too: `abort()` used
+     *    to empty both queues before agent_end could count them, so the one loss path an operator most
+     *    needs to hear about was the one path that stayed silent. ② On a DURABLE PARK the verdict is
+     *    settled at the run tail instead of at agent_end, because the tail first carries the still-
+     *    undelivered input onto the committed checkpoint's parked-steer queue (the resume delivers it)
+     *    — what is announced is the remainder that could NOT be carried, so a fully-migrated park says
+     *    nothing at all and a queue-full / no-longer-pending row still says exactly what was lost.
+     *
+     *  - `"task.injection_priority_unimplemented"` (#389 伴生, D-3) — a notification was injected with
+     *    `priority: "now"`. The three values are CC's names (`now`/`next`/`later`) but this engine
+     *    delivers all three identically at the next turn boundary: there is no arm that aborts the
+     *    running turn, so a caller writing `"now"` and expecting an interruption gets a plain queued
+     *    delivery. The frame IS delivered (this is disclosure, not a refusal — dropping an accepted
+     *    notification would be the worse error); what is announced is that the knob's promise is not
+     *    honored, so an operator can stop building on it. Once per run (the injection funnel is a
+     *    single site, and a busy lane must not narrate the same gap once per frame);
+     *    `detail: { priority, taskId? }`. An UNKNOWN priority value is a different fact with a
+     *    different posture — `TaskStream.notify` refuses it typed (`notify.invalid_payload`).
      *
      *  - `"memory.session_polluted"` (design/178 §3, #324a; message mode-aware since design/336) —
      *    this session's memory crossed into the one-way externally-exposed state (a tool classified
@@ -5498,12 +5520,16 @@ export interface RunnerDeps {
      * Subagent transcript persistence — the delegation ENTRY caps (CC parity values: 20 concurrent /
      * 200 cumulative per session tree; defaults exported as `DELEGATION_MAX_CONCURRENT_DEFAULT` /
      * `DELEGATION_MAX_PER_SESSION_DEFAULT`). Key = `(scope, rootSessionId)`, full depth (grandchildren
-     * share the tree's pool). `maxConcurrent` bounds running/pending a* handles in this process's
-     * registry (parked does not burn a slot — a suspension is not concurrency; a revival claim counts
-     * like a spawn); `maxCumulativePerSession` bounds the RETAINED-WINDOW cumulative count (registry-
-     * retained + store-retained rows — a reaped row returns its quota; deliberately NOT CC's lifetime-
-     * monotonic session counter, which would require a persistent counting surface this economic bound
-     * does not justify — registered divergence). Refusals are coded (`delegation.concurrency_cap` /
+     * share the tree's pool). `maxConcurrent` bounds the tree's RUNNING children of every local lane:
+     * running/pending a* handles in this process's registry PLUS the synchronous and forked children in
+     * flight in this process (parked does not burn a slot — a suspension is not concurrency; a revival
+     * claim counts like a spawn); `maxCumulativePerSession` bounds the RETAINED-WINDOW cumulative count
+     * (registry-retained + store-retained rows, plus those same in-flight local children — a reaped row
+     * returns its quota, and a synchronous child retains nothing so it leaves the window when it
+     * settles; deliberately NOT CC's lifetime-monotonic session counter, which would require a
+     * persistent counting surface this economic bound does not justify — registered divergence). One
+     * consequence, stated rather than left to be discovered: a tree that only ever spawns synchronously
+     * is bounded by the concurrency cap alone. Refusals are coded (`delegation.concurrency_cap` /
      * `delegation.session_cap`) with the current value and this knob's name in the text.
      *
      * BAD VALUES REFUSE LOUDLY at prepare (`config.delegation_entry_caps`, the #123 posture): a

package/dist/core/untrusted-text.js

@@ -240,6 +240,14 @@ export const ENGINE_ENVELOPES = Object.freeze([
         fenced: false,
         disclosed: false,
     },
+    {
+        tag: "example",
+        kind: "not-an-envelope",
+        mint: "engine/compaction SUMMARIZATION_PROMPT (CC 2.1.223 `qby` verbatim — the output skeleton shown to the summarizer)",
+        guard: "no untrusted bytes reach it: the block is a CONSTANT that frames placeholder text (`[Concept 1]`), it wraps nothing, and it is never emitted back — the summarizer's own answer is read through the `<summary>` envelope, not this one",
+        fenced: false,
+        disclosed: false,
+    },
     {
         tag: "task-id",
         kind: "not-an-envelope",

package/dist/engine/compaction/compaction.d.ts

@@ -35,6 +35,22 @@ export interface CompactionDetails {
      * on pre-field entries (⇒ no disclosure, byte-identical legacy wrapper).
      */
     elidedMessages?: number;
+    /**
+     * PTL-shortfall accounting: CUMULATIVE count of folded messages the summary does NOT cover — the ones a reactive
+     * prompt-too-long retry shed from the summarization input (`summarizeWithPtlRetry`'s group
+     * rollback) after `prepareCompaction` had already committed the cut. Those messages leave the
+     * transcript with everyone else (so {@link elidedMessages} stays the honest FOLD count) but
+     * nothing in the summary stands in for them, and the wrapper used to claim otherwise.
+     *
+     * Deliberately a SECOND number rather than a correction of the first: lowering `elidedMessages`
+     * to the covered count would under-report the fold scale, which is the exact judgment that field
+     * exists to inform ("was a whole investigation folded, or three turns?"). Same cumulative +
+     * write-side + optional-absent discipline as its sibling; a lossless pass omits it entirely, so
+     * details written by the common path stay byte-identical. Counted in the summarization-input
+     * coordinate — a LOWER BOUND on uncovered transcript messages (see
+     * {@link SummarizationInputTruncation.droppedMessages}).
+     */
+    unsummarizedMessages?: number;
     /**
      * RB-398-c (blackboard [2105]): `<persisted-output ref="…">` handles found in the COMPACTED range
      * (merged over the previous compaction's retained set, oldest-first, capped at
@@ -105,12 +121,37 @@ export interface CompactionSettings {
  *  AND DISCLOSED (`compaction.clamp_disclosure`), not "lossless" — the honest wording is in the
  *  design doc. Above this, a cheap-model summary is judged too lossy and the main model takes over. */
 export declare const DEFAULT_CLAMP_TOLERANCE = 0.1;
-/** Default compaction settings used by the harness.
- *  design/169-C (CC 220 :516151 `messagesToKeep: []` parity): the DEFAULT compaction is a FULL
- *  compaction — `keepRecentTokens: 0` keeps no verbatim token budget; the summary replaces the
- *  region entirely (the cut still lands on the nearest valid floor, so tool pairs and the
- *  in-progress turn's suffix stay intact). Keeping a verbatim tail is the reactive/partial posture
- *  and remains available as the explicit `keepRecentTokens` knob (the pre-169 default was 20000). */
+/**
+ * Default compaction settings used by the harness.
+ *
+ * `keepRecentTokens: 0` is a ZERO BUDGET, not "keep nothing" — {@link findCutPoint} has a
+ * structural floor underneath the budget (see its doc), so the cut still lands on the last valid
+ * cut point and the summary is followed by the last exchange VERBATIM. Measured on the real
+ * Runner: the first request after an auto-compaction is `[summary wrapper][last assistant turn]
+ * [new user]`, and a within-turn boundary keeps `[emitting assistant][its tool results]` because
+ * a trailing tool-result batch pulls the floor back to its call site.
+ *
+ * That is the CC posture, arrived at through a different knob. CC 2.1.223's LOCAL threshold
+ * compaction always routes to the reactive pipeline (`y9s` :432704 — the `GNo` full-compaction
+ * branch with `messagesToKeep: []` :431788 is reached only for a remote/in-process runner, and a
+ * `source:"auto"` window makes the local threshold not fire at all, `hky` :432687 / `aYe` :242816).
+ * Reactive splits the session into GROUPS (`Ubr` :399459 — a new assistant `message.id` starts a
+ * group and its tool results ride with it) and preserves the last `s = 1` of them verbatim
+ * (`YMo` :399971 / :399982), zeroing the preserved assistants' usage on the way out (`ryt` :401285
+ * — our `buildSessionContext` kept-tail `stripAssistantUsage`, design/123 D1, is the same act).
+ * `s` only grows on ITS retry path, so one group is the default posture on both sides.
+ *
+ * design/169-C moved this default from 20000 to 0 and anchored the change on `messagesToKeep: []`;
+ * the anchor names the minority path, but the VALUE lands on the majority path's behavior, and
+ * raising it again would keep MORE than CC does (measured: a 2000-token budget keeps two whole
+ * exchanges). A positive `keepRecentTokens` remains the explicit knob for callers that want a
+ * wider verbatim tail than either engine's default.
+ *
+ * Known residual (recorded, not repaired): when the last entry is a USER message the floor takes
+ * it alone, where CC's group would also carry the assistant before it. The runner's lanes evaluate
+ * compaction at turn boundaries and at finish — after the assistant/tool results, before the next
+ * prompt — so that shape belongs to direct `maybeCompact` callers.
+ */
 export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
 /**
  * design/123 D2 — default structural coefficient (chars per token) for every structural token
@@ -166,7 +207,19 @@ export interface CutPointResult {
 }
 /** Find the compaction cut point that keeps approximately the requested recent-token budget.
  *  `charsPerToken` (design/123 D2): the keep-recent accumulation must live in the SAME structural
- *  coordinate as the trigger estimate, or the kept tail is systematically over/under-sized. */
+ *  coordinate as the trigger estimate, or the kept tail is systematically over/under-sized.
+ *
+ *  STRUCTURAL FLOOR — the budget can raise the kept tail, never empty it. The backward scan breaks
+ *  at the FIRST message it visits when the budget is already satisfied (a budget of 0 is satisfied
+ *  immediately), and then lands on a valid cut point, so the kept tail is never smaller than
+ *  "the last cut point onward". Two shapes follow, and both are load-bearing:
+ *    - the tail ends on an assistant/user message ⇒ that message is itself a cut point and is kept;
+ *    - the tail ends inside a tool-result batch ⇒ tool results are not cut points, so the `!found`
+ *      fallback below pulls the floor back to the LARGEST cut point ≤ i, i.e. the emitting
+ *      assistant, and the whole batch is kept with it.
+ *  Reading `keepRecentTokens: 0` as "no verbatim tail" is therefore wrong at both the name and the
+ *  behavior (see {@link DEFAULT_COMPACTION_SETTINGS} for the measured shape and the CC coordinates
+ *  it matches). The pins live in test/compaction-keep-tail-floor.test.ts. */
 export declare function findCutPoint(entries: SessionTreeEntry[], startIndex: number, endIndex: number, keepRecentTokens: number, charsPerToken?: number): CutPointResult;
 export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI coding assistant, then produce a structured summary following the exact format specified.\n\nDo NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";
 /**
@@ -250,6 +303,18 @@ export interface SummarizationInputTruncation {
     label: "history" | "turn_prefix";
     droppedChars: number;
     keptChars: number;
+    /**
+     * How many WHOLE messages this drop removed from the summarization input, when the drop was the
+     * PTL retry's group rollback (`summarizeWithPtlRetry`) rather than the proactive head+tail clamp.
+     * The clamp cuts a mid-section of TEXT and leaves every message present, so it reports chars only
+     * and omits this field; the rollback shifts entire assistant-turn groups off the front, and those
+     * messages are folded out of the transcript by the same pass WITHOUT ever reaching the summarizer
+     * — the fact the wrapper's scale disclosure has to state (see
+     * {@link CompactionDetails.unsummarizedMessages}). Counted in the summarization-INPUT coordinate
+     * (messages actually handed to the summarizer, i.e. post-`convertToLlm`), so it is a LOWER BOUND
+     * on the transcript messages the summary does not cover.
+     */
+    droppedMessages?: number;
 }
 /** design/145 §1 — result of a window-safety clamp DRY RUN (see {@link dryRunSummarizationClamp}). */
 export interface SummarizationClampDryRun {
@@ -313,6 +378,11 @@ export interface CompactionPreparation {
     /** RB-398-b①: cumulative folded-message count (this range + the previous carrier's count) —
      *  ready to persist as `CompactionDetails.elidedMessages`. Optional (same rule as above). */
     elidedMessages?: number;
+    /** PTL-shortfall accounting: the previous carrier's uncovered-message count, CARRIED FORWARD only — this pass's own
+     *  uncovered count is not knowable at prepare time (it is produced by the summary leg's PTL
+     *  rollback), so `compact()` adds its own drops on top before persisting
+     *  `CompactionDetails.unsummarizedMessages`. Absent = nothing carried. */
+    carriedUnsummarizedMessages?: number;
     /** Settings used to prepare compaction. */
     settings: CompactionSettings;
 }