@sema-agent/core 5.20.0 → 5.21.1

package/dist/core/runner/turn-attachments.d.ts

@@ -1,5 +1,17 @@
 import type { McpDroppedTool } from "../mcp.js";
 import { type SkillListingEntry } from "./synthetic-tools.js";
+/**
+ * design/133 §R3 — turn-boundary attachment seam: the PURE producer layer (CC `getContextAttachments`
+ * parity). This module is the single home of the CC-parity cadence judgment + reminder copy (提示词主权批:
+ * harness 语料归 core); it holds NO harness handle, does NO I/O, and never injects anything itself — the
+ * run loop (runtask onTurnBoundary) is the ONLY steerer. That split exists so every trigger window is
+ * offline-testable and the injection gate/ordering stays at the one arbitration point the engine already has.
+ *
+ * F3 (wrapper semantics): a {@link TurnAttachment} carries the BODY ONLY — no `<system-reminder>` shell.
+ * The steerer wraps each body exactly once at a single call site, so double-wrap/no-wrap can't drift
+ * per-producer.
+ */
+/** CC-verbatim cadence constants (CC attachments.ts:254-262). */
 export declare const TODO_REMINDER_CONFIG: {
     readonly TURNS_SINCE_WRITE: 10;
     readonly TURNS_BETWEEN_REMINDERS: 10;
@@ -8,107 +20,407 @@ export declare const PLAN_MODE_ATTACHMENT_CONFIG: {
     readonly TURNS_BETWEEN_ATTACHMENTS: 5;
     readonly FULL_REMINDER_EVERY_N_ATTACHMENTS: 5;
 };
+/** RB-313 — CC 2.1.220 tool-search reminder cadence, the shipped defaults of its `juniper_shoal`
+ *  config block (`sru = 15` / `aru = 10` @185913-185914, read as `{everyNTurns, maxNames}` @185836-185849).
+ *  `EVERY_N_TURNS` gates BOTH windows (since-last-ToolSearch and since-last-reminder, @608920);
+ *  `MAX_NAMES` bounds how many undiscovered names the body enumerates before the `(+N more)` tail. */
 export declare const TOOL_SEARCH_REMINDER_CONFIG: {
     readonly EVERY_N_TURNS: 15;
     readonly MAX_NAMES: 10;
 };
+/** F5: per-boundary stat scan upper bound — at most this many most-recently-read files are stat'ed. */
 export declare const CHANGED_FILES_MAX = 20;
+/**
+ * F5 (记档 known limitation): `ReadEntry.lastReadAt` is wall-clock (Date.now) while `FileInfo.mtimeMs`
+ * is the fs clock — a cross-clock comparison (CC getChangedFiles is the same shape: its readFileState
+ * timestamp is also wall-clock). The 2s epsilon absorbs ordinary skew/mtime granularity; git-checkout /
+ * formatter storms remain a documented false-positive source (hash-confirm 抗假阳 = v2).
+ */
 export declare const CHANGED_FILES_MTIME_EPS_MS = 2000;
+/** Per-boundary payload byte cap over the whole bundle (weak-model context economics). */
 export declare const ATTACHMENT_BYTE_CAP: number;
 export type AttachmentSource = "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
+/** G1 续批 — one agent type on the delegation tool's roster (ToolSpec.agentListing, filled by
+ *  createSubagentTool: defined agents + the built-in fork when offered). */
 export interface AgentListingEntry {
     name: string;
     description: string;
+    /** Pre-rendered tool-boundary note for the `(Tools: …)` line tail (CC `gHm`/220 `WW_` @465651-465663:
+     *  "All tools" / "All tools except X, Y" / an explicit list / "None"). Computed by the producer
+     *  (createSubagentTool → {@link import("../../agents/subagent.js").agentToolsNote}).
+     *
+     *  RB-312③: omitting it no longer drops the tail. 220's `fvd` (@465664-465668) interpolates
+     *  `WW_(def)` UNCONDITIONALLY and `WW_` is total — its no-allow/no-deny arm returns the literal
+     *  "All tools" — so every roster line in 220 carries the boundary. sema's optional field only ever
+     *  meant "a hand-built entry did not precompute one"; that entry's real boundary IS the full offered
+     *  pool, so {@link AGENT_TOOLS_NOTE_DEFAULT} is substituted and the tail is now always present. Reading a line
+     *  with no tail as "unknown boundary" was never available to the model anyway — it read as "this type
+     *  has no tools", the one thing that is never true. */
     tools?: string;
 }
+/** G1 通告层: a background task visible to THIS run, snapshotted at the boundary by the
+ *  runtask-side getter (registry ground truth — the producer never touches the registry itself). */
 export interface BackgroundTaskSnapshot {
     id: string;
     description?: string;
     status: string;
 }
+/** One due reminder. `body` is the inner text — the steerer adds the `<system-reminder>` wrapper (F3). */
 export interface TurnAttachment {
     source: AttachmentSource;
     body: string;
 }
+/** H4 — the thin projection of a todo list kept run-local (NEVER the wire-capped structuredFrom card).
+ *  Pure CONTENT memory: the write-window anchor lives on {@link AttachmentState.todoLastWriteTurn}
+ *  (task #51 F3 — the window resets on tool-call INITIATION, which may precede/outlive any ingest). */
 export interface ListProjection {
+    /** ≤{@link PROJECTION_ITEMS_MAX} items, content clipped to {@link PROJECTION_CONTENT_MAX} chars. */
     items: Array<{
         content: string;
         status: string;
     }>;
 }
+/**
+ * Run-local mutable producer state, owned by the run loop (one per run, torn down with it). Mutated by
+ * {@link reduceToolEnd} (ingest) and {@link collectDueAttachments} (window bookkeeping on fire) — both
+ * synchronous and deterministic, so the state stays offline-testable despite the mutation.
+ */
 export interface AttachmentState {
+    /** TodoWrite family snapshot; undefined = TodoWrite never used this run (CC still reminds: the
+     *  gentle "hasn't been used recently" nudge with no list section). */
     todo?: ListProjection;
+    /** Task family (TaskCreate/TaskUpdate/TaskGet/TaskList) — keyed by task id so per-task updates from a
+     *  PARALLEL tool batch commute (F10: distinct ids reduce to the same map in either completion order). */
     taskItems?: Map<string, {
         content: string;
         status: string;
     }>;
+    /** Cadence-clock value AT the last task WRITE anchor block, INCLUSIVE (task #51 F1 block units — see
+     *  {@link advanceCadenceClock}). 口径① (CC 198 pretty.js:480254): CC's `qFm` counter resets ONLY on a
+     *  TaskCreate/TaskUpdate tool_use (`a.name === bD || a.name === hF`) — a TaskGet/TaskList READ is NOT
+     *  engagement and leaves the 10-unit window running. F3: stamped on tool-call INITIATION (the tool_use
+     *  block existing in the transcript IS CC's anchor — qFm never checks execution outcome, so a failed or
+     *  policy-blocked write still resets the window), via {@link stampWriteAnchor} from the message walk. */
     taskLastWriteTurn?: number;
+    /** TodoWrite counterpart of {@link taskLastWriteTurn} (same block coordinate, same initiation-anchor
+     *  semantics — CC BFm :480217-480219 matches the TodoWrite tool_use block by name only). */
     todoLastWriteTurn?: number;
     lastTodoReminderTurn: number;
     lastTaskReminderTurn: number;
+    /** RB-313 — cadence-clock value at the last `ToolSearch` tool_use block (CC 220 `cFy` @608887-608914
+     *  finds it by BACKWARD transcript scan: `turnsSinceLastToolSearch`). Same INITIATION-anchor semantics
+     *  as {@link taskLastWriteTurn} — the block existing in the transcript is the anchor, no outcome check.
+     *  `undefined` = never used this leg, which is the state the reminder exists for (220's scan returns the
+     *  full transcript length there). */
     toolSearchLastUseTurn?: number;
+    /** RB-313 — cadence-clock value at the last tool_search_usage_reminder emitted (CC 220 `cFy`'s
+     *  `turnsSinceLastReminder`, found by scanning back for the attachment entry itself). */
     lastToolSearchReminderTurn: number;
+    /** plan_mode attachments emitted so far — drives CC's full/sparse rotation (1st, 6th, 11th… = full).
+     *  0 also encodes "never attached": CC always attaches on the FIRST plan-mode boundary, then throttles. */
     planAttachmentCount: number;
     lastPlanReminderTurn: number;
+    /** changed_files per-path dedup: the last mtime already surfaced for a path — the same (path, mtime)
+     *  is never reported twice. Evicted alongside readFileState's ENOENT eviction (LOW-9: bounded by it). */
     surfacedMtime: Map<string, number>;
+    /** G1 backgroundTasks (CC /compact parity): SET by the run loop when a compaction LANDS,
+     *  CONSUMED at the next boundary the collector actually runs (a steered-away boundary carries it
+     *  forward untouched — the collector is never called there). One-shot: post-compact announce once,
+     *  never per-boundary nagging. A cap-starved bundle loses this one snapshot (documented trade-off,
+     *  same class as the truncated changed_files batch): the next compaction re-arms it. */
     postCompactPending: boolean;
+    /** G1 续批 agent_listing (CC `agent_listing_delta`): name → description of the agent types already
+     *  ANNOUNCED this leg. `undefined` = the initial full-roster announcement is still pending (CC
+     *  isInitial). Advanced ONLY by {@link commitAgentListing} (run-loop-owned: first-frame delivery and
+     *  intact cap survival at a boundary — MED-3①). A durable-resume leg is SEEDED by the run loop from
+     *  the checkpoint's `announcedListings.agents` name-set when present ([c209-C] Q5 — the boundary
+     *  producer then diffs the CURRENT roster against the seed, so cross-leg roster drift IS
+     *  delta-announced now that the listing frame is the ONLY roster source); an old checkpoint without
+     *  the field falls back to the MED-3② transcript probe (seeded as the current entries when a listing
+     *  reminder is found — drift undetectable there, conservative full re-announce when not found). */
     announcedAgentTypes?: Map<string, string>;
+    /** [c209-C] skills_listing counterpart of {@link announcedAgentTypes}: name → description of the
+     *  skills already ANNOUNCED this leg. `undefined` = the initial full `<skills>` block is still
+     *  pending. Advanced ONLY by {@link commitSkillsListing} (same first-frame / intact-cap-survival
+     *  discipline); resume seeding mirrors the agent arm (checkpoint name-set → drift diff; MED-3②
+     *  transcript probe fallback). No CC anchor for a skills delta exists (209 ships only the initial
+     *  full listing) — the delta arm is a mechanism-family derivation from `agent_listing_delta`,
+     *  registered in cc-divergences. */
     announcedSkills?: Map<string, string>;
+    /** [c209-C] R2 C7 — the model-catalog names last ANNOUNCED to the model (the initial frame's
+     *  "Models available for the 'model' parameter:" tail, Q4). `undefined` = never announced /
+     *  unknowable (old checkpoint, transcript-probe seed) — the delta arm then stays silent on models
+     *  (conservative, pre-C7 behavior). Advanced by {@link commitAgentListing} when the committed
+     *  frame carried a catalog; a durable-resume leg is seeded from the checkpoint's
+     *  `announcedListings.models` so a catalog change across a suspend IS re-announced (the drift
+     *  line rides the first boundary's agent_listing frame). */
     announcedModels?: readonly string[];
+    /** [c209-C] R2 C4② — same-boundary anti-starvation latch: set by {@link collectDueAttachments}
+     *  when a rendered skills_listing block did NOT survive its own bundle intact (clipped/starved —
+     *  typically because the higher-priority agent_listing spent the byte budget first), cleared when
+     *  one survives. While set, the NEXT boundary orders skills_listing BEFORE agent_listing, so two
+     *  listing frames that cannot share one 8KB bundle alternate to completion instead of the
+     *  agent frame permanently starving the skills frame (each frame individually fits the cap by
+     *  construction — agent roster ≤ cap by deployment size, skills block ≤ SKILLS_BLOCK_MAX_BYTES). */
     skillsListingStarved?: boolean;
 }
+/**
+ * [918] A1-R (codex reopen ①) — the date_change lane's OWN state, deliberately NOT an
+ * {@link AttachmentState} member: allocating that for a date-only run would activate the cadence
+ * content scan + projection reducers on every non-opted run (the reopen's exact finding). Two
+ * fields, zero reducers. `announcedDate` starts at the leg's frozen prefix date; the RUN LOOP
+ * commits it (the producer below is pure) — the date block rides ABOVE the 8KB bundle cap as a
+ * fixed ~140-byte item, so no clipping face exists and commit-at-append is sound (contrast
+ * tools_delta's drain-on-intact, which lives inside the capped bundle).
+ */
 export interface DateChangeState {
     announcedDate: string;
 }
+/**
+ * [A2] C-4 (design-A §4.2/§4.3) — the instructions_change lane's OWN state, the date_change
+ * discipline exactly: deliberately NOT an {@link AttachmentState} member (allocating that would
+ * activate the cadence reducers on runs that only carry an instruction snapshot), one field, zero
+ * reducers. `lastAnnouncedHash` starts as the snapshot's declared per-path hashes
+ * (`ProjectMemoryLoad.instructionSources` — what the model is already seeing) and the RUN LOOP
+ * commits it via {@link commitInstructionsChange} when it actually appends the frame (the producer
+ * below is pure). The frame rides ABOVE the 8KB bundle cap as a fixed ≤{@link INSTRUCTIONS_CHANGE_BYTE_CAP}
+ * item — no clipping face exists, so commit-at-append is sound (the [918] A1-R argument verbatim).
+ * `null` value = "announced as removed" (a reappearing file re-announces by hash inequality).
+ */
 export interface InstructionsChangeState {
     lastAnnouncedHash: Map<string, string | null>;
 }
+/** [A2] C-4 — hard byte ceiling of one instructions_change frame body (design-A §4.3: fixed small
+ *  frame riding above the 8KB bundle cap; paths are ellipsis-truncated and overflow files are
+ *  summarized as a count rather than ever growing the frame). */
 export declare const INSTRUCTIONS_CHANGE_BYTE_CAP = 512;
+/**
+ * `workflow_size_guideline_change` (the third above-cap fixed-frame lane) has NO state interface and
+ * no producer here on purpose: its copy is the Workflow tool's own
+ * `workflowSizeGuidelineChangeNotice`, and rendering it from this module would put an
+ * orchestration dependency on the pure attachment producer layer. Its one-field run-local state and
+ * its baseline/live comparison live at the single steerer instead (runtask.ts, next to the
+ * date_change and instructions_change lanes it is structurally identical to). The kind is listed in
+ * {@link AttachmentSource} because the steer wrapper, the byte accounting and the
+ * `steering_injected` echo are all keyed on that wordlist.
+ */
 export declare function createAttachmentState(): AttachmentState;
+/**
+ * H4 — thin-projection reducer over a tool's RAW `result.details` (NOT the wire `structuredFrom`
+ * projection and its 4×16K caps: a huge todo list must shrink into a bounded snapshot here, never
+ * disarm the reminder by being dropped wholesale). Only the first-party discriminants `todo` /
+ * `task` / `task-list` are recognized — every other card type (subagent `agent`/`fork`/`task-output`,
+ * bash, fs, mcp, …) is structurally ignored, which is also the child-isolation contract: a subagent's
+ * own todo state never reaches the parent's onToolEnd, and its delegation-card types don't parse here.
+ *
+ * task #51 F3 (窗口复位/投影摄入拆分, 复审 confirmed): this reducer is PROJECTION INGEST ONLY — it
+ * never touches the write windows. CC's window anchor is the tool_use block's PRESENCE in the
+ * transcript (qFm/BFm match the block by name, :480217-480219/:480253-480254, with no execution-
+ * outcome check), so the run loop stamps the windows on INITIATION via {@link stampWriteAnchor}
+ * (inside {@link advanceCadenceClock}'s message walk); ingest stays success-only — a failed write
+ * has no trustworthy `details`, exactly like CC's reminder body rendering from the authoritative
+ * store rather than from tool results.
+ *
+ * Idempotent (same event twice ⇒ same state) and commutative across DISTINCT task ids (F10); two
+ * whole-list writes (TodoWrite / TaskList) racing in one batch are last-write-wins by nature — the
+ * later list IS the truer snapshot, documented rather than fought.
+ */
 export declare function reduceToolEnd(state: AttachmentState, details: unknown): void;
+/** task #51 F2/F3 — which reminder window a tool_use block resets. Resolved by the run loop (alias-aware:
+ *  ToolSpec.aliases over the mounted roster; RB-476-A retired-name normalization is gone); the producers
+ *  here never inspect tool names themselves.
+ *  RB-313 adds `tool_search`: not a write, but the same INITIATION-anchor mechanism (a `ToolSearch`
+ *  tool_use block resets that lane's "haven't used it recently" window), so it rides the same walk
+ *  instead of duplicating the message scan. */
 export type WriteFamily = "todo" | "task" | "tool_search";
+/**
+ * task #51 F3 (发起锚) — reset a write window at the cadence-clock value of the write tool_use block
+ * (INCLUSIVE of that block). CC's qFm/BFm anchor is the tool_use block's presence in the transcript
+ * (:480217-480219/:480253-480254) with NO execution-outcome check — a failed, policy-blocked, or
+ * suspended call still resets the 10-unit window. Callers: {@link advanceCadenceClock}'s message walk
+ * (the transcript-anchor moment) and the durable-resume gated-write replay (leg-local clock).
+ */
 export declare function stampWriteAnchor(state: AttachmentState, family: WriteFamily, clock: number): void;
+/**
+ * 口径④ cadence clock, task #51 F1 (复审 HIGH, verified against observed CC behavior 2026-07-10) — CC's cadence unit is the
+ * per-content-block assistant TRANSCRIPT ENTRY, not the physical turn. CC 198 mints ONE
+ * `{type:"assistant"}` entry PER content block: the streaming layer at `content_block_stop`
+ * (pretty.js:593011-593038 — `content: pnn([Pr],…)` single-block array, `rn.push` per block) and the
+ * `tgf` normalizer (:597284 — `content.map` → one single-block entry each). The reminder counters
+ * BFm/qFm (:480210-480226/:480246-480262) then tick `r++`/`o++` once per non-`_or` entry, and `_or`
+ * (:599513-599517) applied to a single-block entry degenerates to "is this block thinking/
+ * redacted_thinking" — so the 10/10 windows consume ONE unit per NON-THINKING CONTENT BLOCK. A
+ * `[text, tool_use]` turn costs 2 units, a parallel-k tool batch costs k(+lead) — live probe
+ * (bench/probes/task51-cadence-live, real CC 2.1.198 + stub API): `[text, tool_use]×N` fires the
+ * task_reminder at request #7, block-exact, where a turn-level clock predicts #11-12.
+ *
+ * Applied by the run loop once per completed assistant MESSAGE; returns the advanced clock. CC edge
+ * semantics kept verbatim: non-array content → `_or` false → counted as ONE entry; an empty array is
+ * vacuously all-thinking (`.every`) → 0. sema folds `redacted_thinking` into `{type:"thinking",
+ * redacted:true}` (brain/anthropic.ts B2) so matching "thinking" covers both; the literal
+ * "redacted_thinking" arm serves CC-shape inputs. `stats.turns` is untouched — it has unrelated
+ * consumers (limits/budget/telemetry) whose physical-turn semantics must not drift.
+ *
+ * F3 write anchors ride the SAME walk: a toolCall block whose name resolves (alias-aware, F2) to a
+ * write family stamps that window at the block's inclusive clock value — CC-exact: same-message
+ * leading text blocks sit BEFORE the anchor (they consumed budget but are not part of the
+ * since-write distance), later sibling blocks count toward it; the LAST write block wins, matching
+ * qFm's tail-first scan.
+ */
 export declare function advanceCadenceClock(state: AttachmentState, clock: number, content: unknown, writeFamilyOf: (toolName: string) => WriteFamily | undefined): number;
+/**
+ * task #51 F4 (压缩交互, 复审 confirmed) — rebase every reminder window to the CURRENT cadence clock
+ * when a compaction LANDS. CC's windows are recomputed per request by BACKWARD TRANSCRIPT SCAN
+ * (BFm/qFm): compaction removes the write tool_use anchors and the reminder attachment entries, so
+ * both counters find nothing (t=-1/n=-1) and only count post-compaction entries — the windows
+ * effectively RESET, needing another 10 non-thinking entries before the next fire. sema's stateful
+ * windows would otherwise survive compaction and fire at the first post-compact boundary where CC
+ * stays silent. Setting all four fields to `clock` makes each window measure distance from the
+ * compaction point — arithmetic-identical to CC's anchor loss. (If a messagesToKeep-style preserved
+ * segment is ever implemented, a recent anchor inside the kept tail would survive in CC — refine
+ * this to check the preserved segment then; recorded caveat.)
+ */
 export declare function rebaseCadenceWindows(state: AttachmentState, clock: number): void;
 export interface AttachmentInputs {
+    /** COMPLETED assistant turns at this boundary (`stats.turns`). */
     turn: number;
+    /** 口径④/F1 — the BLOCK-level cadence clock at this boundary: total NON-THINKING content blocks
+     *  across all completed assistant messages ({@link advanceCadenceClock}, CC per-block transcript
+     *  entries :593011/:597284 ticked by BFm/qFm :480210-480226/:480246-480262). This is the todo/task
+     *  reminder-cadence clock — thinking blocks never consume 10/10 budget (`_or` :599513), and a
+     *  multi-block turn consumes one unit PER block, so the windows run 2-3× faster than physical
+     *  turns on real transcripts (text+tool_use is the norm). Write anchors ({@link stampWriteAnchor})
+     *  are stamped in this SAME coordinate. Omitted ⇒ falls back to `turn` (correct only for the
+     *  degenerate one-non-thinking-block-per-turn transcript). plan_mode keeps `turn` (its cadence is
+     *  a recorded sema deviation already — assistant turns, not CC human turns). */
     cadenceTurn?: number;
+    /** Whether TodoWrite is mounted (CC gate: no tool ⇒ no reminder, ever). */
     todoMounted: boolean;
+    /** Whether the task-family tools are mounted. Both mounted ⇒ task_reminder wins (CC isTodoV2 branch). */
     taskListMounted: boolean;
+    /** Live plan-mode flag (planModeRef.active). One-way in sema: exit re-prepares the run, so a false
+     *  here simply stops the producer — no re-entry cycle reset is needed (documented deviation from CC's
+     *  countPlanModeAttachmentsSinceLastExit, which sema's lifecycle makes unreachable). */
     planActive: boolean;
+    /** SR-3 budget_usd lane (CC 198 `QFm` producer :480424-480428 + renderer :600225; 220 `_Fy` @609096
+     *  with the mount at @607474): the run's cost progress against its $ ceiling, in USD. Only passed
+     *  when `config.budgetUsd` opted in AND the task actually carries a ceiling (CC gate
+     *  `e === void 0 → []` — no `maxBudgetUsd`, no lane). CC computes `used = sy()` (session-cumulative
+     *  totalCostUSD) and `remaining = total − used`, both raw JS numbers; sema feeds the SAME coordinate
+     *  its budget gate enforces (`stats.costMicroUsd`/`maxCostMicroUsd`, ÷1e6 → USD) so the model-visible
+     *  numbers can never disagree with the `limits.max_cost_exceeded` verdict. */
     budgetUsd?: {
         used: number;
         total: number;
     };
     config: {
         todoReminder: boolean;
+        /** 口径③ — CC `r2o()` kill-switch parity (pretty.js:479167-479171; consumed by both producers at
+         *  :480232/:480268 as `if (r2o() === "off") return []`). CC resolves the mode from env
+         *  `CLAUDE_CODE_TODO_REMINDER_MODE` (highest precedence) else the `tengu_soft_slate_nudge` gate;
+         *  `"off"` silences BOTH the todo and task reminder lanes even when otherwise wired on, any other
+         *  value (or absence) = CC `"baseline"` (on). sema keeps env resolution at the deployment shell
+         *  and carries only the resolved mode here — core reads no env. */
         todoReminderMode?: "baseline" | "off";
+        /** RB-313 — tool_search_usage_reminder lane (opt-in, default OFF; CC 220 mounts it only when the
+         *  `toolSearchReminder` config resolves non-null, @607450-607456 / `cXi` @185859). */
         toolSearchReminder?: boolean;
         changedFiles: boolean;
         planModeReminder: boolean;
+        /** SR-3: budget_usd progressive reminder lane (opt-in, default OFF like every 133 member). CC fires
+         *  it on EVERY attachment cycle while `maxBudgetUsd` is set; there is NO threshold ladder and no
+         *  throttle window (QFm/`_Fy` are unconditional) — the "progression" is the numbers advancing with
+         *  spend. sema mirrors that: one line per collected clean boundary, no window state here; the run
+         *  loop adds a continuation gate (tool-calling turns only — a boundary steer must never EXTEND a
+         *  finished run, see runtask's `lastTurnHadToolCalls`).
+         *
+         *  RB-311 — attribution CORRECTED (the previous note claimed "gated `d = !t.agentId` :479177 —
+         *  subagents never see it", which reads 220 wrong). In 220 the `!agentId` flag gates only the
+         *  MAIN-AGENT-EXCLUSIVE producer group (`_` @607478-607522: ide_selection / output_style /
+         *  diagnostics / memory_update / token_usage / output_token_usage). `budget_usd` sits in the SHARED
+         *  group `g` (@607474) and its ONLY door is `maxBudgetUsd === undefined → []` — so a 220 SUBAGENT
+         *  whose own options carry a ceiling DOES see the readout. Core裁定: follow 220. There is no
+         *  agent-identity door in this collector to remove — the lane's reachability is entirely
+         *  "does this task's spec carry a ceiling and opt in", which is true for a child exactly when the
+         *  deployment gave it both. Capability位 (what the delegation lane does NOT do): `buildChildSpec`
+         *  (agents/subagent.ts) propagates neither `maxCostUsd` nor `attachments`, so a child spawned by the
+         *  delegation tool inherits no ceiling and no opt-in and is silent by construction; a child spawned
+         *  through a workflow governance baseline (`WorkflowGovernanceBaseline.base`, which explicitly
+         *  snapshots `maxCostUsd` and every other governance field) reaches the lane. */
         budgetUsd?: boolean;
+        /** G1: post-compact background-task announce (opt-in, default OFF like the 133 members). */
         backgroundTasks?: boolean;
+        /** G1: deferred-tool materialization announce (design/36 setTools delta → boundary notice). */
         toolsDelta?: boolean;
+        /** G1 续批: agent-type roster announce (CC `agent_listing_delta`). [c209-C]: listing-family
+         *  member — default ON at the TaskSpec layer (the frame is the ONLY roster source since the
+         *  roster left the tool description), unlike the rest of the 133 family. */
         agentListing?: boolean;
+        /** [c209-C]: skills listing announce (initial `<skills>` block + drift deltas). Listing-family
+         *  member — default ON at the TaskSpec layer, same rationale as `agentListing`. */
         skillsListing?: boolean;
+        /** G1 续批: MCP server-instruction delta announce (CC `mcp_instructions_delta`). */
         mcpInstructions?: boolean;
     };
+    /** RB-313 — deferred tools whose schemas the model has NOT loaded yet (design/36: declared but not
+     *  activated), sorted, snapshotted by the run loop. CC 220's equivalent is
+     *  `tools.filter(iY(u) && !discovered.has(u.name)).map(name).sort()` (@608934-608938). Only passed
+     *  when `config.toolSearchReminder` is opted in AND the task actually has deferred tools — an empty
+     *  or absent list silences the lane permanently (CC `no_undiscovered_tools`, @608939). */
     undiscoveredTools?: readonly string[];
+    /** RB-403 — is the direct-call lane mounted on this run's placeholders (`Prepared.deferDirectCall`,
+     *  i.e. `TaskSpec.deferSelfResolve` not disabled)? Selects which closing sentence the
+     *  tool_search_usage_reminder body carries; absent ⇒ the default direct-lane posture, matching the
+     *  spec field's own default. Meaningless unless `config.toolSearchReminder` is on. */
     deferDirectCall?: boolean;
+    /** Boundary-time scan result (already stat'ed + EPS-filtered by the prepare-task closure). Only
+     *  passed when `changedFiles` is opted in — OFF must mean zero stat calls upstream. */
     changedFiles?: ReadonlyArray<{
         path: string;
         mtimeMs: number;
     }>;
+    /** G1 backgroundTasks: registry snapshot (pending/running only, filtered by the runtask getter).
+     *  Only fetched when opted in AND `state.postCompactPending` — OFF means zero registry reads. */
     backgroundTasks?: ReadonlyArray<BackgroundTaskSnapshot>;
+    /** G1 toolsDelta: deferred tools MATERIALIZED since the last announcement (prepare-task's
+     *  rematerialize diff — already newly-added-only, resume-seeded actives never appear here). The
+     *  CALLER owns consumption: drain its pending list only when the returned capped bundle actually
+     *  retained the `tools_delta` block (cap starvation must not lose the announcement forever). */
     newTools?: readonly string[];
+    /** design/168 — `true` when the run materializes statically (activation never swaps the tools
+     *  block): the tools_delta wording must then not claim "full schemas are loaded". Rides beside
+     *  `newTools` because it qualifies the same frame. */
     newToolsStaticFace?: boolean;
+    /** design/168 — the subset of `newTools` that the static face could not carry in result text and
+     *  that materialized into the tools block instead. See {@link renderToolsDelta}. */
     newToolsSwappedUnderStatic?: readonly string[];
+    /** design/168 — the same fact for the READDED arm. See {@link renderToolsDelta}. */
     readdedToolsSwappedUnderStatic?: readonly string[];
+    /** RB-309 — the MCP-driven arms of the SAME tools_delta frame (removed / readded / failed servers).
+     *  Same pre-diffed input + CALLER-owned intact-survival consumption discipline as `newTools`; only
+     *  passed when `config.toolsDelta` is opted in. See {@link McpToolsDeltaFacts} for reachability. */
     mcpToolsDelta?: McpToolsDeltaFacts;
+    /** G1 续批 agent_listing: the boundary-time roster snapshot of the mounted delegation tool
+     *  (prepare-time static in practice; the producer's delta path serves dynamic-registration
+     *  deployments and tests). Only passed when `config.agentListing` opted in. */
     agentListing?: ReadonlyArray<AgentListingEntry>;
+    /** The delegation tool's mounted name — interpolated into the CC-verbatim headers ("…for the
+     *  Agent tool:"); byte-identical to CC under the default name "Agent". */
     agentToolName?: string;
+    /** [c209-C] Q4 — model catalog names for the agent_listing INITIAL frame's trailing
+     *  "Models available for the 'model' parameter:" line (no CC anchor — CC's model face is a static
+     *  tier enum; sema's catalog is deployment-dynamic, so the names ride the same frame the roster
+     *  does instead of the tool description's cached prefix). [c209-C] R2 C7: a delta frame re-carries
+     *  the full line ONLY on catalog drift against the KNOWN announced catalog
+     *  ({@link AttachmentState.announcedModels}, checkpoint-seeded across legs); otherwise the
+     *  execute-time unknown-model error text remains the fallback disclosure (design/C §2.2). */
     agentModels?: readonly string[];
+    /** [c209-C] skills_listing: the boundary-time skills snapshot (prepare-time static in practice —
+     *  the delta path serves dynamic-installation deployments and tests, same posture as
+     *  `agentListing`). Only passed when `config.skillsListing` is on. */
     skillsListing?: ReadonlyArray<SkillListingEntry>;
+    /** G1 续批 mcp_instructions: pending deltas snapshotted from `MaterializedMcp.instructionsDelta`.
+     *  CALLER-owned consumption on intact cap survival (same `newTools` discipline). */
     mcpInstructions?: {
         added: ReadonlyArray<{
             server: string;
@@ -116,12 +428,88 @@ export interface AttachmentInputs {
         }>;
         removed: readonly string[];
     };
+    /** [cc216] mcp_dropped_tools: intake-dropped MCP tools snapshotted from
+     *  `MaterializedMcp.droppedTools` (rides the `mcpInstructions` opt-in — same MCP announce lane).
+     *  CALLER-owned consumption on intact cap survival (same `newTools` discipline). Tool names are
+     *  pre-neutralized at the mcp.ts producer; reasons are core-authored. */
     mcpDroppedTools?: ReadonlyArray<McpDroppedTool>;
 }
+/**
+ * Compute every reminder due at this clean turn boundary. Pure decision + render — no I/O; the only
+ * mutation is the window bookkeeping on the state the caller owns (reminder turns, surfacedMtime),
+ * done HERE because the caller only invokes this once per boundary after its injection gate passed —
+ * splitting "decide" from "mark sent" would just invite a drift between the two.
+ *
+ * Returns attachments in EVIDENCE-STRENGTH order (todo/task → plan_mode → budget_usd →
+ * background_tasks → tools_delta → agent_listing → skills_listing → mcp_instructions → changed_files), which is also the §R3 MED-6
+ * truncation order read backwards: under the 8KB cap changed_files is sacrificed first, the todo/task
+ * list last. The G1/续批 members are registry/engine ground truth (strong), but the
+ * todo/plan lane keeps priority: it carries the run's own work-tracking state, which the model can
+ * least afford to lose.
+ */
 export declare function collectDueAttachments(state: AttachmentState, inp: AttachmentInputs): readonly TurnAttachment[];
+/**
+ * RB-313 — CC 2.1.220 (@626269-626280, the `tool_search_usage_reminder` renderer), with the two
+ * interpolations resolved: the name list (+ `(+N more)` tail when the census exceeds
+ * {@link TOOL_SEARCH_REMINDER_CONFIG}.MAX_NAMES) and the ToolSearch tool's mounted name — sema mounts
+ * the same name. The quoted `select:<name>[,<name>...]` form is also sema's real ToolSearch contract
+ * (tool-disclosure.ts's `select:` prefix parser), so the copy stays true rather than merely quoted.
+ *
+ * ONE sema amendment, the same one DD-5 already applied to the sibling ToolSearch description: the
+ * closing sentence is POSTURE-AWARE rather than an absolute failure promise. With the RB-403
+ * direct-call lane mounted — the default (`TaskSpec.deferSelfResolve` not disabled) — a call on a
+ * still-deferred tool whose arguments match the real schema EXECUTES and activates it, so "calling a
+ * tool before its schema is loaded will fail" is false for that posture. This face must not assert an
+ * execution gate the engine does not implement; the steer stays pessimistic on purpose (activate
+ * rather than guess — inventing arguments for an unseen schema is the real failure) but is phrased as
+ * the reason it is true. The `deferSelfResolve: false` posture keeps the absolute wording, which is
+ * exactly true for it.
+ */
 export declare function renderToolSearchUsageReminder(undiscovered: readonly string[], directCallEnabled?: boolean): string;
+/**
+ * SR-3 — CC 2.1.198 VERBATIM template (bundle pretty.js:600225, the `budget_usd` attachment renderer):
+ *   `USD budget: $${used}/$${total}; $${remaining} remaining`
+ * `remaining = total − used` is computed producer-side in CC (QFm :480427 `n = e - t`) and re-derived
+ * here from the two inputs — one fewer number to drift. CC interpolates RAW JS numbers (sy() is a
+ * float accumulator; no rounding anywhere in QFm or the renderer), kept verbatim: sema's inputs come
+ * from integer micro-USD ÷ 1e6, so they render with ≤6 decimals by construction.
+ */
+/** [915] A1 — CC messages.ts:4162 verbatim shape (de-branded is a no-op here: the text is neutral). */
 export declare function renderDateChange(newDate: string): string;
+/**
+ * [918] A1-R — the date_change producer (CC attachments.ts:1400-1443 parity): the system-prefix
+ * date is FROZEN for the leg (upstream: "cached for the duration of the conversation" — re-rendering
+ * the prefix at midnight costs ~920K effective tokens per overnight session, upstream's own comment);
+ * when the boundary-time LOCAL date walks away from the last announced one, the model is told at the
+ * TAIL instead. String INEQUALITY (backward NTP jumps announce too). PURE — the caller commits
+ * `state.announcedDate = today` when it actually appends the attachment (see {@link DateChangeState}).
+ */
 export declare function collectDateChange(state: DateChangeState, today: string): TurnAttachment | undefined;
+/**
+ * [A2] C-4 — the instructions_change producer (design-A §4.3): the project-instruction snapshot is
+ * FROZEN for the session (§4.1); when the deployment probe reports a file hash that walked away from
+ * the last ANNOUNCED one, the model is told at the tail — it can Read the truth on demand (the
+ * seeded-read dedup disarms on a changed file, §4.4, so the Read returns the real new content).
+ *
+ * PURE — same split as {@link collectDateChange}: the caller commits via
+ * {@link commitInstructionsChange} when it actually appends the frame (append-⇔-commit holds because
+ * the frame rides ABOVE the byte-capped bundle). Rules:
+ * - `probed === null` ⇒ the probe declined this boundary (remote cwd / EACCES / transient IO):
+ *   silent skip, nothing committed, next boundary retries.
+ * - string INEQUALITY against the last announced hash triggers (a rollback to an old value is also
+ *   a change — the date lane's same rule); the SAME value never announces twice (终身一次).
+ * - `contentHash: null` = the file is GONE — announced once as removed (`hash → absent`);
+ *   a reappearing file re-announces by inequality against the committed `null`.
+ * - probed paths the snapshot never declared are ignored (the deployment owns the file-name policy;
+ *   core only compares against the declared baseline).
+ * - the frame body is HARD-BOUNDED to {@link INSTRUCTIONS_CHANGE_BYTE_CAP}: paths are
+ *   ellipsis-truncated, and files that don't fit are summarized as `(+N more…)` — those stay
+ *   UNCOMMITTED (absent from `announced`) and re-announce at the next boundary.
+ * - multi-file changes merge into ONE frame, one line per file (§4.3).
+ *
+ * Returns the frame plus the `announced` entries that actually rode it (the caller's commit set),
+ * or `undefined` when nothing is due.
+ */
 export declare function collectInstructionsChange(state: InstructionsChangeState, probed: ReadonlyArray<{
     path: string;
     contentHash: string | null;
@@ -132,56 +520,302 @@ export declare function collectInstructionsChange(state: InstructionsChangeState
         contentHash: string | null;
     }>;
 } | undefined;
+/** [A2] C-4 — the run loop's commit half (append-⇔-commit, {@link InstructionsChangeState}): advance
+ *  the per-path last-announced hashes for exactly the entries that rode the appended frame. */
 export declare function commitInstructionsChange(state: InstructionsChangeState, announced: ReadonlyArray<{
     path: string;
     contentHash: string | null;
 }>): void;
 export declare function renderBudgetUsd(used: number, total: number): string;
+/**
+ * SR-7 — CC 2.1.198 VERBATIM inner text (bundle pretty.js:698391-698398, `F6c`): the aggregated
+ * orphaned-background-task notice a restarted/resumed leg injects ONCE (CC's own `<system-reminder>`
+ * wrapper is added by the caller — sema's single-wrap-point discipline, F3). Line shape CC-exact:
+ * `- ${description || "(no description)"} (task ${id})` — `||` kept (an EMPTY description also reads
+ * "(no description)", CC-same). Consumed by the runtask durable-resume path, NOT a boundary producer:
+ * the trigger is the resume itself (CC gate `CLAUDE_CODE_RESUME_INTERRUPTED_TURN`, :707384), not a
+ * cadence window.
+ */
 export declare function renderOrphanedBackgroundTasks(tasks: ReadonlyArray<{
     id: string;
     description?: string;
 }>): string;
+/**
+ * RB-309 — CC's per-frame list cap for the `deferred_tools_delta` arms (`lP`, pretty220.js:518269).
+ * Lists longer than this collapse to a grouped one-liner + "…and N more".
+ */
 export declare const TOOLS_DELTA_LIST_MAX = 30;
+/** RB-309 — the MCP-driven arms of the deferred-tools announce. All fields are pre-diffed by the
+ *  producer (prepare-task's `rematerialize` seam / the materialize-time failed-server projection) and
+ *  are CALLER-drained on intact cap survival, exactly like {@link AttachmentInputs.newTools}. */
 export interface McpToolsDeltaFacts {
+    /** Previously-announced deferred tools that LEFT the harness roster (their server withdrew them —
+     *  reached through RefreshMcpTools's prefix re-splice). CC `removedNames` @626530. */
     removed?: readonly string[];
+    /** Previously-announced-then-withdrawn deferred tools that came BACK. CC `readdedNames` @626525. */
     readded?: readonly string[];
+    /** Declared MCP servers that failed to connect at materialize (`MaterializedMcp.statuses`, status
+     *  `"failed"`). `error` is REMOTE/transport text — the producer neutralizes + bounds it at intake.
+     *  CC `failedMcpServers` @626561. */
     failedServers?: ReadonlyArray<{
         name: string;
         error?: string;
     }>;
 }
+/**
+ * G1 — deferred-tool materialization announce (design/36 boundary notice). CC 2.1.198 template
+ * (bundle pretty.js:599148, `deferred_tools_delta` case) verbatim reads: "The following deferred
+ * tools are now available via ${ToolSearch}. Their schemas are NOT loaded — calling them directly
+ * will fail with InputValidationError. Use ${ToolSearch} with query \"select:<name>[,...]\" to load
+ * tool schemas before calling them:" — but CC announces DISCOVERABLE tools (schemas still deferred),
+ * while sema announces MATERIALIZED tools (tool_search already ran setTools; schemas ARE live), so
+ * the middle clause is inverted to match sema's actual contract. Same CC shape: lead sentence +
+ * name list.
+ *
+ * RB-309 — CC 2.1.220 (`deferred_tools_delta`, pretty220.js:626512-626600) carries SIX arms; sema
+ * shipped only the `added` one. The arms below are the ones whose STATE IS REACHABLE in this engine
+ * (data-side audit, RB-309):
+ * - `readded` (@626525) / `removed` (@626530): reachable via RefreshMcpTools — the refresh splices a
+ *   server's whole `mcp__<server>__` prefix domain out of the live tool array and pushes the fresh
+ *   listing back, so a withdrawn tool genuinely leaves (and a re-advertised one genuinely returns)
+ *   the roster mid-task. CC's trailing "Load via ToolSearch as before" / "Do not search for them —
+ *   ToolSearch will return no match" clauses are kept, because sema mounts the SAME ToolSearch name.
+ * - `failed` (@626561): reachable from `MaterializedMcp.statuses` (`status: "failed"`, fail-open
+ *   connect skip). CC additionally splits a MANAGED-POLICY sub-arm off this list (`jlr`/`Oy_` error
+ *   codes @626575) — sema has no managed-policy error taxonomy, so only the connection-failure form
+ *   is rendered.
+ * DELIBERATELY ABSENT (state unreachable — announcing them would be a §25 honesty breach):
+ * - `needs-auth` (@626543): sema's MCP auth surface is STATIC deployment-supplied headers
+ *   (`McpServerSpec.transport.headers` / `principalHeader`) with no OAuth flow and no
+ *   authorization-required status — an auth rejection surfaces as an ordinary connect failure and is
+ *   covered by the `failed` arm above.
+ * - `pending` (@626586): `materializeMcpTools` is fully AWAITED inside prepareTask (one
+ *   `Promise.allSettled` over every server) before the run loop's first turn, so "still connecting"
+ *   does not exist at any turn boundary — `McpServerStatus.status` is `connected | failed` only.
+ * Returns `undefined` when every arm is empty (CC `i.length === 0 → []`).
+ */
 export declare function renderToolsDelta(input: {
     added?: readonly string[];
     staticFace?: boolean;
+    /** design/168 — the subset of `added` that the STATIC face could not carry and that therefore
+     *  materialized into the tools block instead (a declaration too large to inline in result text,
+     *  or one that does not serialize; see the per-tool exemption in prepare-task). Empty/absent on
+     *  every ordinary static run, which keeps the common frame byte-identical; when it is non-empty
+     *  the static wording below would otherwise assert compact placeholders for a name the model can
+     *  see carries a full schema. Meaningless unless `staticFace` is true. */
     swappedUnderStatic?: readonly string[];
+    /** The same exemption fact for the READDED arm (a name announced earlier, withdrawn, and now back).
+     *  The exemption is sticky within a leg, so a tool that was ever exempt is remounted with its full
+     *  declaration on readdition — and the readded wording, like the added wording, would otherwise
+     *  assert compact placeholders the model can see are not there. */
     readdedSwappedUnderStatic?: readonly string[];
 } & McpToolsDeltaFacts): string | undefined;
+/** RB-312③ — the `(Tools: …)` value for an entry that precomputed none (CC 220 `WW_`'s terminal arm
+ *  @465662: no allowlist and no denylist ⇒ the literal "All tools"). */
 export declare const AGENT_TOOLS_NOTE_DEFAULT = "All tools";
+/** CC 2.1.198 verbatim (bundle pretty.js:599221, `agent_listing_delta` isInitial+showConcurrencyNote arm). */
 export declare const AGENT_CONCURRENCY_NOTE = "When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.";
+/** CC-verbatim ambient-context tail (CC 2.1.198 `Emr`, pretty.js:599992 — resolved by the 2026-07-10
+ *  parity spot audit, PARITY-SPOT-AGENT-TYPES F5 / PARITY-SPOT-REMINDERS SR-V1). CC appends it after BOTH
+ *  removal lists (agent types :599211, mcp instructions :599240) so the model treats the drift notice as
+ *  background, not something to announce. */
 export declare const AMBIENT_CONTEXT_NOTE = "This is ambient context \u2014 do not narrate it to the user unless they ask or it is directly relevant to their request.";
+/** CC-verbatim initial-roster header (interpolated tool name) — single-sourced here for the renderer
+ *  AND the run loop's resume transcript probe (MED-3②: "was the listing ever delivered?"). */
 export declare function agentListingInitialHeader(toolName: string): string;
+/**
+ * [clay session-dedup, codex F1] Rebuild the EXACT announced name-set by replaying every listing
+ * frame in a transcript, in order: an initial frame RESETS the set to its names, a delta frame ADDS,
+ * a removal frame DELETES. Header-presence alone is NOT a safe seed (it proves "announced once", not
+ * WHAT was announced — seeding the current entries would swallow the A→A+B delta and removal-to-zero
+ * on ordinary session continuations). Single-sourced next to the renderers so a frame-shape change
+ * cannot desync the parser. Returns undefined when NO frame exists (fresh session — announce fully).
+ */
 export declare function replayAnnouncedListing(texts: readonly string[], headers: {
     initial: string;
     delta: string;
     removed: string;
 }): Set<string> | undefined;
+/** Removal-frame header for the agent-type roster (single-sourced for renderer + replay parser). */
 export declare const AGENT_LISTING_REMOVED_HEADER = "The following agent types are no longer available:";
+/** CC-verbatim roster-drift header — same single-source rationale as {@link agentListingInitialHeader}. */
 export declare function agentListingDeltaHeader(toolName: string): string;
+/**
+ * G1 续批 — agent-type roster announce (CC 2.1.198 `agent_listing_delta`, bundle pretty.js:599199-599223,
+ * headers VERBATIM with the tool name interpolated — byte-identical to CC under the default "Agent").
+ * First call (no announced map) = CC `isInitial`: full roster under "Available agent types…", plus the
+ * concurrency note when more than one type is offered. Later
+ * calls announce only drift: adds under "New agent types are now available…", removals under "The
+ * following agent types are no longer available:" + `- <name>` lines, followed by the CC-verbatim
+ * {@link AMBIENT_CONTEXT_NOTE} (CC `Emr`, pretty.js:599211/599992). Name-keyed like CC: a description
+ * change on an existing name is not re-announced. Every line carries a `(Tools: …)` tail (RB-312③,
+ * 220 `fvd`/`WW_` @465651-465668 — the model needs each type's tool boundary to pick a type;
+ * PARITY-SPOT-AGENT-TYPES F3), defaulted to {@link AGENT_TOOLS_NOTE_DEFAULT} when the entry precomputed none.
+ *
+ * RB-312① — showConcurrencyNote, honest attribution: `entries.length > 1` is a sema APPROXIMATION, not
+ * CC semantics. 220's real predicate (@607882) is `Aa() !== "pro" && Cq() === "default"` — subscription
+ * tier is not "pro" AND the output style is the default one. Neither axis exists in core (BYOM has no
+ * subscription plane; there is no output-style plane at all), so the predicate is untranslatable, and
+ * 220's intent — "show the parallel-launch hint to users who have not already been told it elsewhere" —
+ * has no sema carrier either. The roster-size proxy is kept because it is the one honest thing core can
+ * say: a single-type roster cannot be launched concurrently with a different type, so the note would be
+ * noise. RESIDUAL (divergences candidate): under a >1 roster sema shows the note where 220 would hide it
+ * for a pro/non-default-style user.
+ *
+ * RB-312② — added/removed ordering: adds are sorted by `localeCompare` and removals by the default
+ * `sort()`, exactly as 220 does at @607873 (`c.sort((p,f) => p.agentType.localeCompare(f.agentType)), u.sort()`).
+ * This is not cosmetic here: the announced-set advance ({@link commitAgentListing}) is gated on the
+ * rendered block surviving the capped bundle BYTE-IDENTICAL against a re-render, so a deployment that
+ * merely reorders its declarations between two boundaries used to mint a different byte string for the
+ * same content. Sorting makes the frame a function of the SET, which is what that predicate assumes.
+ * SCOPED to the DRIFT arms (recorded residual): 220's `c.sort` also covers the isInitial roster, but
+ * sema's initial order is CURATED and load-bearing — general-purpose first (the type that is always
+ * pickable), the deployment's definitions in declared order, `fork` last — and that curation carries
+ * information an alphabetical sort would destroy. The initial frame renders one array once, so it has
+ * no re-render byte-identity exposure of its own.
+ *
+ * 1.256 复审 MED-3①: PURE — never mutates `state`. The announced-set advance is CALLER-owned via
+ * {@link commitAgentListing}, committed ONLY when the rendered block survived the byte cap INTACT
+ * (tools_delta/mcp_instructions discipline — a cap-clipped/dropped block previously advanced the
+ * announced map anyway, losing the roster announcement forever).
+ */
 export declare function renderAgentListingDelta(state: AttachmentState, entries: ReadonlyArray<AgentListingEntry>, toolName: string, models?: readonly string[]): string | undefined;
+/** [c209-C] R2 C7 — the Q4 catalog line, single-sourced for the initial frame's tail AND the
+ *  drift re-announce arm so the two can never diverge byte-wise. [c209-C] codex 收口 C7 补口: an
+ *  EMPTY catalog renders an honest "(none)" — reachable only from the DRIFT arm (a known announced
+ *  catalog shrank to nothing; the initial frame still omits the line when there is nothing to offer). */
+/** Single-sourced carrier prefix of the model-catalog line (renderer + replay parser). */
 export declare const MODELS_AVAILABLE_PREFIX = "Models available for the 'model' parameter: ";
+/** [codex S3 round 3] Replay the ANNOUNCED model catalog from stamped transcript texts — the last
+ *  carried "Models available…" line wins (the line is re-carried in full on every drift, [c209-C]
+ *  C7). Undefined = the catalog was never carried (unknowable — the drift compare stays silent,
+ *  same conservative arm as an old checkpoint). */
 export declare function replayAnnouncedModels(texts: readonly string[]): readonly string[] | undefined;
+/**
+ * MED-3① commit half of {@link renderAgentListingDelta}: mark the CURRENT roster as announced. The run
+ * loop calls this only when the `agent_listing` block survived the capped bundle INTACT (body equality
+ * against a re-render — same predicate as the tools_delta drain); a clipped/dropped block leaves the
+ * announced map untouched so the next quiet boundary re-announces. Snapshotting `entries` wholesale is
+ * equivalent to add/remove bookkeeping (the diff is name-keyed; descriptions are never re-diffed).
+ */
 export declare function commitAgentListing(state: AttachmentState, entries: ReadonlyArray<AgentListingEntry>, models?: readonly string[]): void;
+/** [c209-C] skills drift-frame header — single-sourced for the renderer AND the run loop's resume
+ *  transcript probe (MED-3② skills arm). Phrasing mirrors {@link agentListingDeltaHeader} (no CC
+ *  anchor for a skills delta — mechanism-family derivation, registered in cc-divergences). */
 export declare const SKILLS_LISTING_DELTA_HEADER = "New skills are now available:";
+/** [c209-C] skills removal-arm header — mirrors the agent-listing removal arm's phrasing. */
 export declare const SKILLS_LISTING_REMOVED_HEADER = "The following skills are no longer available:";
+/**
+ * [c209-C] skills_listing producer — the skills counterpart of {@link renderAgentListingDelta}.
+ * First call (no announced map) = the full `<skills>` disclosure block VERBATIM (buildSkillsBlock —
+ * the exact bytes that used to sit in the stable system prompt now ride the reminder lane; CC 209
+ * classic ships its skills listing the same way, as a first-user-turn reminder ~5.9KB, report §5.1).
+ * Later calls announce only drift, name-keyed like the agent arm: adds under
+ * {@link SKILLS_LISTING_DELTA_HEADER} with the SAME `- name: description` line shape the block uses,
+ * removals under {@link SKILLS_LISTING_REMOVED_HEADER} + `- <name>` lines, followed by the
+ * CC-verbatim {@link AMBIENT_CONTEXT_NOTE} (agent-removal-arm parity). A description change on an
+ * existing name is not re-announced (name-keyed, agent-arm parity).
+ *
+ * MED-3① discipline: PURE — the announced-set advance is CALLER-owned via {@link commitSkillsListing},
+ * committed only on first-frame delivery or intact cap survival at a boundary.
+ */
 export declare function renderSkillsListingDelta(state: AttachmentState, entries: ReadonlyArray<SkillListingEntry>): string | undefined;
+/** [c209-C] commit half of {@link renderSkillsListingDelta} — same MED-3① contract as
+ *  {@link commitAgentListing}: called by the run loop only on first-frame delivery or when the
+ *  `skills_listing` block survived the capped bundle INTACT; a clipped/dropped block leaves the
+ *  announced map untouched so the next quiet boundary re-announces. */
 export declare function commitSkillsListing(state: AttachmentState, entries: ReadonlyArray<SkillListingEntry>): void;
+/**
+ * RB-308 — per-server bound (in CODE POINTS, matching every other clipper in `untrusted-text.ts`) on
+ * ONE MCP server's `instructions` text. The text is SERVER-controlled and UNBOUNDED on the wire: the
+ * bundle byte cap ({@link ATTACHMENT_BYTE_CAP}) is a per-frame structural backstop on the delta lane
+ * and does not exist AT ALL on the stable system-prompt lane, so without this a single server could
+ * pin an arbitrarily large blob into the cached prompt prefix for the whole task (and, on the delta
+ * lane, wedge the frame permanently against the 8KB cap — the codex 1362 F2 failure shape).
+ * Sized at the delta lane's own order of magnitude (the 8KB frame budget), leaving fence + header
+ * room under the bundle cap once the "…" truncation marker lands.
+ */
 export declare const MCP_INSTRUCTIONS_MAX_CHARS: number;
+/**
+ * RB-308 — the ONE way MCP server-provided instruction text becomes model-facing, used by BOTH the
+ * stable system-prompt lane (prepare-task's `# MCP Server Instructions` block, design/64 §17.3) and
+ * the boundary delta lane ({@link renderMcpInstructionsDelta}).
+ *
+ * The bug this closes: the same server-authored string was carried with TWO DIFFERENT trust postures
+ * — fenced on the delta lane, RAW-INTERPOLATED (no fence, no bound) into the stable prompt. A single
+ * source makes the divergence unrepresentable.
+ *
+ * Truncation is DISCLOSED (§25 honesty): `delimitUntrusted` clips silently with an ellipsis, which
+ * reads to the model as the server's own text. The trailing note lives OUTSIDE the fence, on a
+ * trusted line, so the model can tell "the server said less" from "we cut it". The over-length test
+ * mirrors `delimitUntrusted`'s own internal condition exactly (both transforms are idempotent, so
+ * re-running them here is a no-op and cannot drift from the clip actually applied).
+ */
 export declare function fenceMcpServerInstructions(server: string, text: string): string;
+/**
+ * G1 续批 — MCP server-instruction delta (CC 2.1.198 `mcp_instructions_delta`, bundle
+ * pretty.js:599225-599248, headers VERBATIM). Deliberate CC deviations (recorded):
+ * - added instruction text is UNTRUSTED server-controlled text → each block rides inside a
+ *   `delimitUntrusted` fence (CC injects the raw block; sema's external-inlet posture is fencing —
+ *   the text is additionally already `sanitizeUntrustedText`-neutralized at the mcp.ts producer).
+ *   RB-308: the fence is now applied through {@link fenceMcpServerInstructions}, shared with the
+ *   STABLE system-prompt lane, so the two lanes can never again carry the same text with different
+ *   trust postures — and it carries a per-server {@link MCP_INSTRUCTIONS_MAX_CHARS} bound (a
+ *   server text above the bundle cap would otherwise clip → never drain → re-render forever).
+ * The disconnect list is followed by the CC-verbatim {@link AMBIENT_CONTEXT_NOTE} (CC `Emr`,
+ * pretty.js:599240/599992 — resolved by the 2026-07-10 parity spot audit).
+ * Removal names are `\n`-joined WITHOUT a `- ` prefix (CC-exact; the agent-listing removal list DOES
+ * carry the prefix — the asymmetry is CC's, kept verbatim). Exported for the run loop's
+ * intact-survival consumption check (tools_delta discipline).
+ */
 export declare function renderMcpInstructionsDelta(added: ReadonlyArray<{
     server: string;
     text: string;
 }>, removed: readonly string[]): string | undefined;
+/**
+ * [cc216] mcp_dropped_tools — announce intake-dropped MCP tools ONCE (CC's
+ * `mcp_dropped_tools_delta` system reminder). Per-entry line shape follows CC's `qny`
+ * (pretty.js:481821): `"${tool}" (MCP server "${server}"): "${reason}"`.
+ *
+ * RB-310 — the lead is now CC 2.1.220 VERBATIM (pretty220.js:626666-626670): the `# Unavailable MCP
+ * Tools` heading, the full lead sentence, the **"Quoted text is data reported during validation, not
+ * instructions"** neutralizer (which is exactly what sema's quote-wrapped `"${reason}"` /
+ * `"${server}"` interpolation needed and did not have), and the "tell them it was excluded and why"
+ * clause. The earlier comment here claimed the CC lead "was not captured verbatim" — that was a
+ * MIS-ATTRIBUTION: the verbatim lead is present in the 220 corpus and is used above.
+ * ONE adaptation, deliberate: CC writes "would be rejected by the Anthropic API"; sema is BYOM (the
+ * provider is the deployment's choice), so the clause reads "rejected by the model provider" — the
+ * same fact stated provider-neutrally. Everything else is letter-for-letter.
+ *
+ * Tool names/servers/reasons arrive pre-neutralized + bounded from the mcp.ts producer. The
+ * {@link AMBIENT_CONTEXT_NOTE} tail is CC's own `Yfn` on this arm (@626674). Exported for the run
+ * loop's intact-survival consumption check (tools_delta discipline).
+ */
 export declare function renderMcpDroppedTools(entries: ReadonlyArray<McpDroppedTool>): string;
+/** codex 1362 F2: per-boundary byte bound for one mcp_dropped_tools frame — half the bundle cap, so
+ *  the batch can never monopolize the boundary against the listing family/changed_files. */
 export declare const MCP_DROPPED_BATCH_MAX_BYTES = 4096;
+/**
+ * codex 1362 F2 (medium) — bounded-batch selection for the dropped-tools announce. An UNBOUNDED
+ * render larger than the 8KB bundle cap gets prefix-CLIPPED by capAttachments; the intact-survival
+ * drain predicate then never matches, the full array is retained, and every later boundary re-renders
+ * and re-clips the identical prefix forever (tail entries never disclosed, permanent cap churn).
+ * Selecting the longest prefix of COMPLETE entries whose render fits {@link MCP_DROPPED_BATCH_MAX_BYTES}
+ * (always ≥1) restores monotonic drainage: the run loop splices exactly the delivered batch, the
+ * tail rides later boundaries. Pure/deterministic so the drain predicate can re-derive the exact
+ * snapshot. codex r2 F3: the ≥1 floor is SAFE only because entries are bounded at the mcp.ts
+ * producer (tool ≤160 cps, reason ≤240 cps, both single-lined) — one rendered entry is always a
+ * few hundred bytes, far under both this bound and the 8KB bundle cap, so the single-entry frame
+ * can never be cap-clipped into a permanent re-render wedge.
+ */
 export declare function selectMcpDroppedBatch<T extends McpDroppedTool>(entries: ReadonlyArray<T>): T[];
+/**
+ * Largest prefix of `s` that fits `maxBytes` UTF-8 bytes (binary search — never splits the budget math).
+ *
+ * REF-B5 (car R11): the ONE byte-budget prefix search in the runner. runtask.ts's batch-context clip
+ * (design/134 §3.1b) used to carry a hand-copied twin whose doc claimed this module "doesn't export
+ * it" — that layering argument died once runtask started importing {@link ATTACHMENT_BYTE_CAP} from
+ * here, so the budget CONSTANT and the budget MATH now come from the same place. Producer-layer purity
+ * is unchanged: this is a pure function of (string, number).
+ */
 export declare function clipToBytes(s: string, maxBytes: number): string;