@humwick/server 0.0.0-stage → 0.130.0

package/src/memory-preamble.ts

@@ -0,0 +1,1142 @@
+import { isolateMemoryEntry, validateMemoryEntry } from "./memory-entry-safety";
+// The unified-memory spawn preamble (#1565 P4a, design §4.2/§4.3) — `composeMemoryPreamble`.
+//
+// THE composer that renders `project_entries` into a prompt. It had a sibling —
+// `composeProjectInstructions`, a second render path over the same table for the `project` cell —
+// which #1565 P5.5 retired (§10.5): two paths over one table is how #1601 happened, and one path
+// cannot drift. Three disciplines, unchanged:
+//   • DETERMINISTIC — render order comes from `resolveMemoryForIdentity` (kind → cell specificity
+//     → own-before-inherited → title → id); overflow admission ranks by value (role, tier, recency;
+//     memory-admission-rank.ts, #3090). Both read only stored rows, so the same DB always renders
+//     the same block, byte for byte.
+//   • SIZE-BOUNDED  — a per-scope token budget (§4.3(2), `MEMORY_SCOPE_TOKEN_CAP`) AND a global
+//     ceiling on the whole block (`MEMORY_TOTAL_TOKEN_CAP`) with a documented, reproducible drop
+//     order. Worst case is the global cap, not `per-scope budget × however many cells exist`.
+//   • EMPTY IS ""   — nothing resolvable ⇒ empty string ⇒ the caller leaves `systemPromptAppend`
+//     untouched ⇒ the spawn stays BYTE-IDENTICAL to a pre-#1565 one.
+//
+// TIERS (§4.3(1)). `inject:'pinned'` renders the full body (a directive that isn't in context
+// doesn't bind); `inject:'indexed'` is on demand, never at startup (#3508): on first touch of a
+// path area it names, else via search. A pinned entry over budget demotes to an `[id] headline · Nt`
+// index line; `inject:'never'` is retrieval-only. `sensitivity:'sensitive'` and expired (`expires_at`)
+// entries are NEVER injected.
+//
+// WHAT MAY BE INJECTED IS NOT DECIDED HERE (#1565 P5.4/P5.5, §10). Audience, tier, sensitivity and
+// TTL all come from the ONE shared predicate
+// `entryInjectability` (src/memory-inject-filter.ts). It lives in its own module because it USED to
+// have two callers that each owned a copy of the checks and drifted, injecting a `sensitive`
+// project entry in full (#1601). Every refusal comes back with a REASON and is reported
+// (`filtered`/`filteredByReason`).
+//
+// PROVIDER-AGNOSTIC BY CONSTRUCTION: the input is an identity record, the output is markdown.
+// No provider handle, no provider branch, nothing that could grow one.
+
+import { contextRenderNow, renderedAtLine } from "./context-block-rendered-at";
+import type { MemoryIdentity, ResolvedMemoryEntry } from "./db/memory-resolve";
+import { readMemoryPreambleSnapshot, type MemoryPreambleSnapshot } from "./db/memory-preamble-read";
+import { countInjectionDrops, describeInjectionDrops, emptyDropCounts, type InjectionDrop, type InjectionDropCounts } from "./memory-inject-filter";
+import { errMessage } from "@humwick/sdk";
+import { warnPinnedOverflow } from "./memory-admission-rank";
+import { admitCandidates, type Candidate, type Outcome } from "./memory-preamble-admission";
+import { injectsAtStartup } from "@humwick/sdk/areas";
+import {
+  MEMORY_BASE_TOKEN_FLOOR,
+  MEMORY_INDEX_TOKEN_CAP,
+  MEMORY_INSTRUCTION_TOKEN_CAP,
+  MEMORY_MAX_TITLE_CHARS,
+  MEMORY_SCOPE_TOKEN_CAP,
+  MEMORY_TOTAL_TOKEN_CAP,
+  cutToTokens,
+  estimateEntryTokens,
+  estimateTextTokens,
+} from "./memory-tokens";
+import { renderTemplateReport } from "./prompt-resolver";
+import { MEMORY_SCOPE_CHAIN, type MemoryChainScope, type ProjectEntryKind } from "./types";
+
+/** The stable open marker (§4.2). Versioned so a future render shape can be recognized.
+ *
+ *  It makes the block REPLACEABLE, but only where relay owns the bytes: at spawn and restart the
+ *  prompt is recomposed and `stripMemoryPreamble` removes the previous copy. A `clear`/`compact`
+ *  does NOT respawn — the system prompt (and its spawn-time block) survives, and the re-injected
+ *  block lands in the transcript beside it. There, replacement is a STATEMENT, not a deletion:
+ *  `MEMORY_SUPERSEDE_NOTICE` (#1565 F-REPLACES) is what makes the later copy authoritative. */
+export const MEMORY_PREAMBLE_MARKER = "<!-- relay:memory v1 -->";
+/** The close marker. The design names only the opener; a closer is what makes the strip exact,
+ *  because the block itself legitimately contains blank lines and `#` headings. */
+export const MEMORY_PREAMBLE_END_MARKER = "<!-- /relay:memory -->";
+
+/** Marker-SHAPED comments in entry content. The block boundary is only a boundary if content
+ *  cannot forge it: a body that quotes the closer (in THIS repo, the likely author of such a
+ *  body is an agent documenting the memory system) would otherwise orphan the block's tail into
+ *  the carried-forward prompt, and the next generation would compose a fresh block on top of the
+ *  residue — stacking once per restart, and keeping content that has since been retracted,
+ *  expired, or flipped to `sensitive`. Neutralized on render, so a marker never LEAVES here
+ *  except as one the composer wrote. */
+const MARKER_SHAPED = /<!--\s*\/?\s*relay:memory\b[\s\S]*?-->/g;
+
+const KIND_HEADINGS: Record<ProjectEntryKind, string> = {
+  rule: "Rules",
+  fact: "Facts",
+  decision: "Decisions",
+  memory: "Memory",
+};
+const INDEX_HEADING = "## Index (bodies on demand — relay_project_read({ ids:[…] }))";
+/** The fetch reflex (#1979 Wave A I7), stated in the block right where the index starts. An index
+ *  is only worth its tokens if the agent PULLS from it: when a title below looks relevant to the
+ *  task in hand, retrieving its body by id is one cheap call away. Trains the reflex the charter
+ *  also carries, at the exact point the agent is looking at the titles.
+ *
+ *  #2154 retired `relay_retrieve_memory`; the ids this index prints are `pe_…` PROJECT entry ids,
+ *  so `relay_project_read({ ids })` is the by-id fetch that survives. Naming a tool the agent does
+ *  not have is worse than naming none — a coordinator followed the stale directive into a dead end,
+ *  which is why `memory-prompt-tool-references.test.ts` now looks every name here up in TOOLS. */
+const INDEX_FETCH_DIRECTIVE = "_When a title below is relevant to your task, pull its full body by id — `relay_project_read({ ids:[…] })`. Cheap; do it rather than guess._";
+/** Index headlines are a *hook*, not the entry. Bounded to the write-time title cap (#1979 I2) so a
+ *  legacy over-long title cannot bloat a row, and one essay-titled memory cannot eat the index
+ *  budget through its title alone. */
+const MAX_HEADLINE_CHARS = MEMORY_MAX_TITLE_CHARS;
+/** …and the hook that follows it (§4.2's `headline — hook · Nt`). An index the agent cannot
+ *  TRIAGE is just a token tax: the title says what the entry is about, the hook says whether it
+ *  is worth pulling. Bounded for the same reason as the headline. */
+const MAX_HOOK_CHARS = 120;
+
+/** The rendered tier of a candidate — `never` never reaches here. */
+export type MemoryPreambleTier = "pinned" | "indexed";
+
+/** Why an entry did not RENDER AT ALL — always stated in the block, never only in telemetry
+ *  (#1979 Wave A I1 narrowed this to a single entry-loss cause).
+ *  `index` = the index section's own cap (`MEMORY_INDEX_TOKEN_CAP`) was exhausted, so not even a
+ *    one-line reference fit — the ONLY way an injectable entry is now lost, and a rare one;
+ *  `instruction` = the block's INSTRUCTION preface overran its own cap and was truncated. The
+ *    second is deliberately in the same vocabulary but is NOT an entry drop: it never increments
+ *    `omitted`, because no entry was lost — an instruction can only ever cost itself (§10.1). */
+export type MemoryPreambleOmission = "index" | "instruction";
+
+/** Why a `pinned` entry did not get a FULL BODY and was demoted to a one-line index reference
+ *  instead of dropped (#1979 Wave A I1). It still renders — in the index — so this is a softening,
+ *  not a loss; the footer names it so the index's growth is explained.
+ *  `budget` = its own cell's per-scope budget was exhausted; `total` = the whole-block ceiling was. */
+export type MemoryPreambleDemotion = "budget" | "total";
+
+/** How an instruction slug resolved (#1565 P5.1, §10.1). Each state is explicit and reported;
+ *  none of them is an error, and none of them may fall back to friendlier text.
+ *  - `rendered`  — text resolved and fits;
+ *  - `missing`   — the slug is in neither the DB nor the shipped defaults;
+ *  - `blank`     — stored empty/whitespace, i.e. DELIBERATELY DISABLED (the kill switch);
+ *  - `truncated` — text resolved but overran `MEMORY_INSTRUCTION_TOKEN_CAP`;
+ *  - `failed`    — resolution itself threw. Degrades to no text, never to a failed spawn. */
+export type MemoryInstructionStatus = "rendered" | "missing" | "blank" | "truncated" | "failed";
+
+/** Per-slug accounting for the preface — the instruction-side twin of
+ *  `MemoryPreambleEntryReport`. Every requested slug appears here, rendered or not. */
+export interface MemoryInstructionReport {
+  /** The slug that was ASKED for (the profile-agnostic one). */
+  slug: string;
+  /** The slug that actually supplied the text: `<slug>.<profile>` when that one resolves,
+   *  else `slug`. Reported so "why is my coordinator seeing different wording" is answerable. */
+  resolved: string;
+  status: MemoryInstructionStatus;
+  /** What this slug contributes to the block as rendered. 0 unless `rendered`/`truncated`. */
+  tokens: number;
+  /** `{{var}}` names that rendered to "" — a hole, never a crash (§10.1). Omitted when none. */
+  emptyVariables?: string[];
+  /** Why this slug did not resolve cleanly: the throw behind `status:"failed"`, or the stored-read
+   *  failure that made a `rendered` slug fall back to the shipped default text. */
+  error?: string;
+}
+
+/** Per-entry accounting. EVERY injectable candidate appears here, rendered or not — the
+ *  "never silently" half of §4.3's token transparency. */
+export interface MemoryPreambleEntryReport {
+  id: string;
+  kind: ProjectEntryKind;
+  title: string;
+  cell: MemoryChainScope;
+  /** How the entry actually RENDERED: `pinned` = full body; `indexed` = a one-line reference (its
+   *  native tier, or a `pinned` entry demoted here — see `demoted`). */
+  tier: MemoryPreambleTier;
+  /** What this entry costs the prompt AS RENDERED (a pinned body vs. a one-line headline). For an
+   *  omitted entry, the index line it WOULD have cost. */
+  tokens: number;
+  /** What the whole entry costs if pulled — the `· Nt` an index line advertises. */
+  fullTokens: number;
+  rendered: boolean;
+  /** A `pinned` entry the full-body budget could not fit, rendered as an index reference instead of
+   *  being dropped (#1979 I1). Absent for a natively-`indexed` entry, which was never a body. */
+  demoted?: boolean;
+  /** Why a demoted entry lost its full body — set whenever `demoted` is. */
+  demotedReason?: MemoryPreambleDemotion;
+  /** Set only when `rendered` is false: the entry was omitted entirely (always `index` now). */
+  omittedReason?: MemoryPreambleOmission;
+}
+
+export interface MemoryPreambleScopeReport {
+  cell: MemoryChainScope;
+  budget: number;
+  candidates: number;
+  rendered: number;
+  tokens: number;
+  omitted: number;
+}
+
+/** The limits this compose actually ran under — reported, not just applied, so a truncated block
+ *  can be explained without re-deriving the constants (#1602 residual: the ceiling has to be
+ *  legible to whoever is looking at a short block). */
+export interface MemoryPreambleBudgetReport {
+  /** Per-cell cap (`MEMORY_SCOPE_TOKEN_CAP`). */
+  scope: number;
+  /** Whole-block ceiling (`MEMORY_TOTAL_TOKEN_CAP`) for FULL BODIES. */
+  total: number;
+  /** The index section's own cap (`MEMORY_INDEX_TOKEN_CAP`) — a SEPARATE allowance, like
+   *  `instruction`, so a complete index can never evict a full body (#1979 I1). */
+  index: number;
+  /** Tokens of `total` held back for the `base` cell — never more than base could spend. */
+  baseReserved: number;
+  /** The preface's own cap (`MEMORY_INSTRUCTION_TOKEN_CAP`) — a SEPARATE allowance, not a slice
+   *  of `total`, so instruction text can never evict an entry (§10.1). */
+  instruction: number;
+}
+
+export interface ComposedMemoryPreamble {
+  /** The markdown block, or "" when nothing applies. */
+  block: string;
+  /** Estimated token cost of the block's ENTRIES — the sum of the rendered entries' `tokens`,
+   *  from the ONE estimator (§4.3(3)), so this number matches what the tools and the dashboard
+   *  report. The preface is priced separately in `instructionTokens`; the block's own footer
+   *  states the sum, because that is what the agent actually pays. */
+  tokens: number;
+  /** What the instruction preface costs (#1565 P5.1) — 0 when every slug is blank/missing. */
+  instructionTokens: number;
+  /** Per-slug preface accounting, in request order. Every requested slug is here whatever its
+   *  status, so "the instruction is not showing up" is answerable from the event alone. */
+  instructionSlugs: MemoryInstructionReport[];
+  entries: MemoryPreambleEntryReport[];
+  /** Entries lost ENTIRELY — the index section's cap could not fit even a one-line reference
+   *  (#1979 I1). Near-zero by design; stated in the block itself, never silent. */
+  omitted: number;
+  /** `omitted`, split by WHY. Since I1 the only entry-loss cause is `index`; `instruction`
+   *  rides here for the truncation clause but is never an entry. */
+  omittedByReason: Record<MemoryPreambleOmission, number>;
+  /** `pinned` entries that could not fit a full body and were rendered as index references instead
+   *  of dropped (#1979 I1). They ARE in the block (in the index); this is why the index grew. */
+  demoted: number;
+  /** `demoted`, split by which full-body budget was full — the cell's own vs. the whole-block
+   *  ceiling. Different levers, so kept apart (the #1602 discipline, applied to demotions). */
+  demotedByReason: Record<MemoryPreambleDemotion, number>;
+  scopes: MemoryPreambleScopeReport[];
+  budgets: MemoryPreambleBudgetReport;
+  /**
+   * Candidates the SHARED injectability filter refused, itemized with their reason (#1565 P5.4,
+   * §10) — audience, TTL, `sensitive`, `inject:'never'`. Kept separate from `omitted`, which is
+   * strictly the budget/ceiling drop: the two have completely different fixes, and flattening
+   * them is the misattribution #1602 closed one level up.
+   *
+   * A `sensitive` drop carries `id` + `reason` only — never the title (see `injectionDrop`).
+   */
+  filtered: InjectionDrop[];
+  filteredByReason: InjectionDropCounts;
+  /** #3409/#3508 — injectable entries held out of the startup block: every `indexed` entry and the
+   *  agent's own project's path-only entries. Not refusals, so never in `filtered`. */
+  areaDeferredCount: number;
+  /** What `tokens` would be had nothing been deferred: the same admission over every candidate.
+   *  Equals `tokens` when `areaDeferredCount` is 0. */
+  counterfactualTokens: number;
+}
+
+export interface ComposeMemoryPreambleOptions {
+  /** Per-scope token budget (§4.3(2)). Default `MEMORY_SCOPE_TOKEN_CAP` (2048). */
+  scopeTokenBudget?: number;
+  /**
+   * Ceiling on the WHOLE block. Default `MEMORY_TOTAL_TOKEN_CAP`.
+   *
+   * The per-scope budget alone bounds each cell but not their sum, so the real cost of a spawn
+   * would grow with however many cells the chain happens to have. This is the number that
+   * actually bounds a prompt. Spent MOST-SPECIFIC-CELL FIRST, so what the ceiling drops is the
+   * least specific content — the same drop direction §4.3(2) gives the per-scope budget.
+   */
+  totalTokenBudget?: number;
+  /**
+   * Tokens of `totalTokenBudget` reserved for the `base` cell. Default `MEMORY_BASE_TOKEN_FLOOR`.
+   *
+   * Without it, the most-specific-first spend order lets a well-stocked `host`/`provider` cell
+   * consume the whole ceiling and evict the operator's own base memory — which under #559 had a
+   * budget nothing else could touch. The reservation is capped at what base can actually use, so
+   * an under-stocked base cell hands its unused share straight back.
+   */
+  baseTokenFloor?: number;
+  /**
+   * Cap on the whole INDEX SECTION (#1979 I1). Default `MEMORY_INDEX_TOKEN_CAP`.
+   *
+   * A SEPARATE allowance from `scopeTokenBudget`/`totalTokenBudget`, which bound full bodies only.
+   * Hooked reference lines spend THIS cap. A `pinned` entry the body budget demoted never gets
+   * omitted: past the cap it renders hookless (#3525). Only a natively-`indexed` entry is omitted
+   * (reason `index`).
+   */
+  indexTokenBudget?: number;
+  /** Injected clock for TTL evaluation. Default `Date.now()`. */
+  now?: number;
+  /**
+   * Which chain cells participate. Default: all of `MEMORY_SCOPE_CHAIN`.
+   *
+   * Lifecycle seams derive this set from the selected profile's Project Instructions cell. When
+   * that switch is off, `project` is absent and cannot participate in resolution or overrides.
+   *
+   * Filtering happens BEFORE resolution, so an excluded cell can never win an override collapse
+   * and take the surviving entry down with it. `base` always participates — it is the floor of
+   * any identity — and `profile` always applies, because it selects AUDIENCE, not a cell.
+   */
+  cells?: readonly MemoryChainScope[];
+  /** Provider-native repo instruction filenames. Matching ingested project mirrors are excluded
+   * before override collapse and reported as source-policy drops. */
+  projectNativeInstructionFiles?: readonly string[];
+  /**
+   * Which instruction slugs render as the block's preface, in order (#1565 P5.1, §10.1).
+   * Default `MEMORY_INSTRUCTION_SLUGS`. Pass `[]` for a block with no instruction at all — the
+   * shape a byte-identical-to-pre-P5 prompt has.
+   */
+  instructionSlugs?: readonly string[];
+  /** Cap on the whole preface. Default `MEMORY_INSTRUCTION_TOKEN_CAP`. */
+  instructionTokenBudget?: number;
+}
+
+/**
+ * The instruction slugs the preface renders, in order (#1565 P5.1, §10.1).
+ *
+ * `memory.charter` says what relay memory IS and how to use it; `memory.native-off` (seeded
+ * BLANK) says it outranks the provider's own store, and is populated only when §10.3.3's rollout
+ * reaches Stage 0. The other two `memory.*` slugs are not here on purpose: they are boundary
+ * payload text (P5.2), not system-prompt text.
+ */
+export const MEMORY_INSTRUCTION_SLUGS = ["memory.charter", "memory.native-off"] as const;
+
+/**
+ * Resolve the preface (#1565 P5.1, §10.1).
+ *
+ * Every failure mode is EXPLICIT and reported, and none of them invents friendlier text:
+ *  - a slug in neither DB nor defaults is `missing` — `renderTemplateReport` returns undefined
+ *    instead of `renderTemplate`'s throw, because an unknown slug must never fail a spawn;
+ *  - a stored-blank slug is `blank` — the deliberate disable that K2 depends on, so it has to be
+ *    a first-class reportable state rather than a reason to fall back to the default text;
+ *  - a resolution that THROWS is `failed`: no text, the error recorded, the spawn unaffected;
+ *  - an unknown `{{var}}` is already substituted "" by the renderer — reported by NAME here, so
+ *    a hole in the prompt is visible rather than merely harmless;
+ *  - marker-shaped text is neutralized exactly like an entry body. The slug is dashboard-editable,
+ *    i.e. caller text: a `<!-- relay:memory v1 -->` inside it would forge the block boundary and
+ *    defeat strip-and-replace (the F2 lesson, applied to a new input).
+ *
+ * Per-profile specialization is a one-deep fallback chain, `<slug>.<profile>` → `<slug>`, and the
+ * probe is SILENT: nobody has a per-profile slug by default, so reporting ten `missing` statuses
+ * per spawn would make the report useless. A per-profile slug that exists WINS EVEN WHEN BLANK —
+ * it can only exist because somebody created it, so blanking it is a per-profile kill switch, not
+ * a hole to paper over with the shared text.
+ */
+function resolveInstructionPreface(
+  slugs: readonly string[],
+  profile: string | undefined,
+  cap: number,
+): { parts: string[]; reports: MemoryInstructionReport[]; tokens: number; truncated: number } {
+  const parts: string[] = [];
+  const reports: MemoryInstructionReport[] = [];
+  let used = 0;
+  let truncated = 0;
+  const own = profile?.trim();
+  for (const slug of slugs) {
+    let resolved = slug;
+    let rendered;
+    try {
+      const specific = own ? renderTemplateReport(`${slug}.${own}`) : undefined;
+      if (specific) resolved = `${slug}.${own}`;
+      rendered = specific ?? renderTemplateReport(slug);
+    } catch (error) {
+      reports.push({ slug, resolved, status: "failed", tokens: 0, error: errMessage(error) });
+      continue;
+    }
+    if (!rendered) {
+      reports.push({ slug, resolved, status: "missing", tokens: 0 });
+      continue;
+    }
+    // A stored-lookup failure degraded to the SHIPPED default rather than to nothing (the better
+    // outcome — the instruction survives, only the operator's edit is lost). Carried through as
+    // `error` so the degradation is reported instead of passing for a healthy render.
+    const extra = {
+      ...(rendered.emptyVariables.length ? { emptyVariables: rendered.emptyVariables } : {}),
+      ...(rendered.lookupError ? { error: rendered.lookupError } : {}),
+    };
+    const text = neutralizeMarkers(rendered.text.trim());
+    if (!text) {
+      reports.push({ slug, resolved, status: "blank", tokens: 0, ...extra });
+      continue;
+    }
+    const cost = estimateTextTokens(text);
+    if (used + cost <= cap) {
+      parts.push(text);
+      used += cost;
+      reports.push({ slug, resolved, status: "rendered", tokens: cost, ...extra });
+      continue;
+    }
+    // Over the cap: cut to what is left, deterministically (chars = the estimator's own chars/4,
+    // one reserved for the ellipsis that marks the cut). The scan CONTINUES — a later slug that
+    // still fits in the remainder is not punished for an earlier slug's size.
+    truncated += 1;
+    const cut = cutToTokens(text, cap - used);
+    const cutCost = cut ? estimateTextTokens(cut) : 0;
+    if (cut) {
+      parts.push(cut);
+      used += cutCost;
+    }
+    reports.push({ slug, resolved, status: "truncated", tokens: cutCost, ...extra });
+  }
+  return { parts, reports, tokens: used, truncated };
+}
+
+/**
+ * The preface statuses that are DEFECTS rather than decisions (#1565 P5.1).
+ *
+ * `blank` is deliberate — an operator disabled the slug, and a disabled instruction reporting
+ * itself at every spawn would be noise that trains everyone to ignore the report. Everything else
+ * means an instruction the fleet was supposed to have did not arrive, which must be audible even
+ * when the block itself is "" and has nowhere to say so.
+ */
+export function memoryInstructionDefects(reports: readonly MemoryInstructionReport[]): MemoryInstructionReport[] {
+  return reports.filter((report) => report.status === "missing" || report.status === "failed" || report.status === "truncated" || report.error);
+}
+
+/**
+ * Remove a previously injected memory block (marker to marker), so a restart/re-inject REPLACES
+ * it instead of stacking a second copy. Mirrors `stripHumwickIdentitySection`.
+ *
+ * STRICT, BY CONSTRUCTION (#1565 F2). This runs over text the CALLER wrote — `composeProfileSpawn`
+ * applies it to `callerSystemPromptAppend`, which is the raw parent brief — so anything it removes
+ * that is not actually a relay block is a caller's own words, silently deleted from every restart
+ * of that agent. The markers are also ordinary text: this repo's own design doc carries them, and
+ * a review brief quotes them. So only a well-formed pair THE COMPOSER COULD HAVE EMITTED is a
+ * block: the opener must start a line and be followed immediately by the block's `# Memory` header
+ * line, and the closer must sit alone on its own line (`isComposedOpener`/`isComposedCloser`). A
+ * brief that mentions a marker in prose is not a boundary and is left byte-for-byte alone.
+ *
+ * Within a block, removal runs to the LAST composer-shaped closer BEFORE the next composer-shaped
+ * opener. A closer forged inside an entry body can only live ahead of that block's real terminator,
+ * so the last one in the region is the real one — and render-side neutralization
+ * (`neutralizeMarkers`) means only prompts already in flight from an older generation can contain
+ * one at all.
+ *
+ * An opener with NO closer after it (a block truncated in transit) has only its opener line
+ * removed. It deliberately does NOT swallow the following region: the earlier "merge a closer-less
+ * region into the next one" rule (#1602 residual 2) rested on truncation being the only way to
+ * reach that shape, and that is false — ordinary caller prose reaches it, and the rule then ate
+ * everything from the prose mention to the end of the next real block. A one-time cosmetic
+ * fragment is a far better outcome than deleting a caller's acceptance criteria; the fragment
+ * carries no marker, so nothing stacks on it either way.
+ */
+export function stripMemoryPreamble(value: string): string {
+  const spans = memoryPreambleSpans(value);
+  if (!spans.length) return value;
+  let out = "";
+  let last = 0;
+  for (const { from, end } of spans) {
+    out += value.slice(last, from);
+    last = end;
+  }
+  out += value.slice(last);
+  return out.replace(/^\n\n+/, "").replace(/\n\n+$/, "");
+}
+
+/**
+ * What the re-injected copy says about the copy already in context (#1565 F-REPLACES).
+ *
+ * A `clear`/`compact` does not respawn, so the spawn-time block stays in the system prompt while
+ * this one arrives in the transcript: two blocks with identical markers and nothing to tell the
+ * agent which is current. Without this line, "an entry retracted mid-session is gone at the next
+ * boundary" is false for the system-prompt copy — and the delta gate hides it, because the only
+ * time a boundary re-injects at all is when the set CHANGED, i.e. exactly when a retraction has to
+ * take effect. Prose is the whole mechanism available here: nothing mid-session can rewrite a
+ * system prompt.
+ */
+export const MEMORY_SUPERSEDE_NOTICE = "_This block SUPERSEDES any earlier relay memory block in this context (a clear/compact does not rewrite the system prompt, so an older copy may still be above). Where they differ, THIS one is current — anything present there and absent here was retracted, expired, or is no longer injectable._";
+
+/**
+ * The same statement WITHOUT the retraction claim, for the case relay cannot stand behind it
+ * (#1625).
+ *
+ * The notice above says a difference between the two copies means a retraction. That is only true
+ * if both copies were resolved under the SAME launch-recorded memory identity.
+ * When the boundary had to re-derive its seam — an agent whose launch predates the recorded seam,
+ * or one that never went through a composing spawn path — agreement is unproven, and the difference
+ * could just as easily be a resolution difference (a different host cell, a narrower source set).
+ *
+ * Claiming retraction there is worse than saying nothing, because the agent ACTS on it: it treats
+ * live, still-injectable instruction as withdrawn. So the claim is downgraded to what is actually
+ * known. The supersede statement itself is unchanged — the later copy is still the current one.
+ */
+export const MEMORY_SUPERSEDE_NOTICE_UNVERIFIED = "_This block SUPERSEDES any earlier relay memory block in this context (a clear/compact does not rewrite the system prompt, so an older copy may still be above). Where they differ, THIS one is current. Relay could NOT confirm this block resolved under the same launch identity and project-memory selection as the earlier copy, so treat anything present there and absent here as UNVERIFIED rather than retracted._";
+
+/**
+ * The block as it is DELIVERED at a boundary: the composed block with the supersede notice on the
+ * line after its header, inside the markers so a later strip takes it with the block.
+ *
+ * The composed block stays the canonical one — it is what gets hashed for the delta gate and what a
+ * spawn prompt carries — so adding this line can never make the gate compare two shapes and
+ * re-inject forever. "" stays "": there is nothing to supersede with. A boundary that must retract
+ * an EARLIER copy with nothing of its own uses {@link memoryRetractionBlock} instead — only that
+ * caller knows a stale copy is actually in the prompt.
+ *
+ * `seamVerified` is required rather than defaulted (#1625): the caller is the only one that knows
+ * whether the earlier copy was composed from the same seam, and a default would silently pick the
+ * stronger claim exactly where it is least justified.
+ */
+export function withMemorySupersedeNotice(block: string, opts: { seamVerified: boolean }): string {
+  if (!block.trim()) return block;
+  const lines = block.split("\n");
+  // [0] is the opener, [1] the `# Memory — …` header; the notice reads as the block's own subtitle.
+  const at = lines.length > 1 ? 2 : 1;
+  const notice = opts.seamVerified ? MEMORY_SUPERSEDE_NOTICE : MEMORY_SUPERSEDE_NOTICE_UNVERIFIED;
+  return [...lines.slice(0, at), "", notice, ...lines.slice(at)].join("\n");
+}
+
+/**
+ * An EMPTY block that still carries the supersede notice — the retraction payload for a boundary
+ * that composed nothing while the agent's prompt is still carrying an earlier copy.
+ *
+ * #2154 made this reachable: with the project cell the only one left, switching Project Instructions
+ * off composes to "" once the charter slugs are also blank, and a clear/compact does not rewrite the
+ * system prompt. Sending nothing would leave the launched block standing as current forever.
+ *
+ * Marker-wrapped, so `extractMemoryPreamble`/`stripMemoryPreamble` take it like any other block. It
+ * is deliberately HEADER-LESS — there is no cell left to name — which means `isComposedOpener` does
+ * NOT recognize it as a composed block. That is inert today (nothing re-composes a delivered
+ * retraction), but a header must be added here before anything starts to.
+ */
+export function memoryRetractionBlock(opts: { seamVerified: boolean }): string {
+  const notice = opts.seamVerified ? MEMORY_SUPERSEDE_NOTICE : MEMORY_SUPERSEDE_NOTICE_UNVERIFIED;
+  return [MEMORY_PREAMBLE_MARKER, "", notice, MEMORY_PREAMBLE_END_MARKER].join("\n");
+}
+
+/**
+ * The memory block a prompt CARRIES, marker to marker, or null when it carries none — the read
+ * side of the same scan `stripMemoryPreamble` removes with.
+ *
+ * This is what lets the compact delta-gate ask "what is already in this agent's system prompt?"
+ * of the durable spawn command instead of a parallel bookkeeping write: the answer is derived
+ * from the bytes that were actually launched, so it cannot drift from them. The LAST block wins —
+ * a prompt with more than one is malformed, and the last is the one composed most recently.
+ */
+export function extractMemoryPreamble(value: string): string | null {
+  const span = memoryPreambleSpans(value).at(-1);
+  return span ? value.slice(span.open, span.end) : null;
+}
+
+interface MemoryPreambleSpan {
+  /** The opener's own index — where the BLOCK starts. */
+  open: number;
+  /** Where REMOVAL starts: the opener, or the blank line that joined it to what precedes it. */
+  from: number;
+  end: number;
+}
+
+/** The header line the composer ALWAYS writes immediately after the opener (`memoryHeader`). Part
+ *  of what makes an opener a composer-shaped one rather than a prose mention of the marker. */
+const OPENER_HEADER_LINE = /^\r?\n# Memory\b/;
+
+/** An opener the composer could have written: alone at the start of a line, with the block's own
+ *  `# Memory` header on the next. Anything else is prose that happens to contain the marker. */
+function isComposedOpener(value: string, at: number): boolean {
+  if (at > 0 && value[at - 1] !== "\n") return false;
+  return OPENER_HEADER_LINE.test(value.slice(at + MEMORY_PREAMBLE_MARKER.length));
+}
+
+/** A closer the composer could have written: alone on its own line (it is pushed as its own line,
+ *  after the accounting footer). */
+function isComposedCloser(value: string, at: number): boolean {
+  if (at > 0 && value[at - 1] !== "\n") return false;
+  const after = at + MEMORY_PREAMBLE_END_MARKER.length;
+  return after === value.length || value[after] === "\n" || value[after] === "\r";
+}
+
+function nextComposedOpener(value: string, from: number): number {
+  for (let at = value.indexOf(MEMORY_PREAMBLE_MARKER, from); at >= 0; at = value.indexOf(MEMORY_PREAMBLE_MARKER, at + 1)) {
+    if (isComposedOpener(value, at)) return at;
+  }
+  return -1;
+}
+
+/** The LAST composer-shaped closer inside `[from, until)` — a forged one can only sit ahead of the
+ *  real terminator, so the last is the real one. -1 when the region holds none. */
+function lastComposedCloser(value: string, from: number, until: number): number {
+  let found = -1;
+  for (let at = value.indexOf(MEMORY_PREAMBLE_END_MARKER, from); at >= 0 && at < until; at = value.indexOf(MEMORY_PREAMBLE_END_MARKER, at + 1)) {
+    if (isComposedCloser(value, at)) found = at;
+  }
+  return found;
+}
+
+function memoryPreambleSpans(value: string): MemoryPreambleSpan[] {
+  if (!value.includes(MEMORY_PREAMBLE_MARKER)) return [];
+  const spans: MemoryPreambleSpan[] = [];
+  let cursor = 0;
+  for (;;) {
+    const open = nextComposedOpener(value, cursor);
+    if (open < 0) break;
+    const openEnd = open + MEMORY_PREAMBLE_MARKER.length;
+    // One region per block: from this opener to the next composer-shaped opener (or end of input).
+    // A closer-less region terminates at the opener line and NOTHING is merged into the region
+    // after it — see `stripMemoryPreamble` for why that direction is the safe one.
+    const nextOpen = nextComposedOpener(value, openEnd);
+    const closeAt = lastComposedCloser(value, openEnd, nextOpen < 0 ? value.length : nextOpen);
+    const end = closeAt < 0 ? openEnd : closeAt + MEMORY_PREAMBLE_END_MARKER.length;
+    // Swallow the blank line that joined the block to whatever preceded it, so removal does not
+    // leave a double separator behind.
+    spans.push({ open, from: value.slice(open - 2, open) === "\n\n" ? open - 2 : open, end });
+    cursor = end;
+  }
+  return spans;
+}
+
+/** Defuse any marker-shaped comment in entry content by escaping its opening `<`. The text stays
+ *  readable ("&lt;!-- /relay:memory -->"), but it is no longer a boundary anything can match. */
+function neutralizeMarkers(text: string): string {
+  return text.replace(MARKER_SHAPED, (match) => `&lt;${match.slice(1)}`);
+}
+
+/**
+ * The same defusing, for text relay did not compose (#1565 F2) — applied to the caller brief AFTER
+ * `stripMemoryPreamble` has removed any real block from it.
+ *
+ * Two things it buys, both about the NEXT generation rather than this one: a caller's marker can
+ * never be mistaken for the prompt's memory block by `extractMemoryPreamble` (which the compact
+ * delta-gate reads out of the launched prompt), and it can never grow into a boundary that a future
+ * strip acts on. Cost is cosmetic and one-way: `<!--` renders as `&lt;!--` in the brief, with every
+ * word the caller wrote still there.
+ */
+export function neutralizeMemoryMarkers(text: string): string {
+  return neutralizeMarkers(text);
+}
+
+/** A title as one neutralized line, capped at the write-time title limit. */
+export function memoryHeadline(title: string): string {
+  const clean = neutralizeMarkers(title.trim()).replace(/\s+/g, " ");
+  return clean.length > MAX_HEADLINE_CHARS ? `${clean.slice(0, MAX_HEADLINE_CHARS - 1)}…` : clean;
+}
+
+/** The `— hook` half of an index line: the entry's first paragraph, collapsed and bounded. The
+ *  headline says what the entry is ABOUT; the hook is what lets an agent decide whether to spend
+ *  the `· Nt` on pulling it. "" when the entry has no body (the headline is the whole story). */
+function indexHook(body: string | undefined): string {
+  const first = body?.trim().split(/\n\s*\n/)[0]?.replace(/\s+/g, " ").trim();
+  if (!first) return "";
+  const clean = neutralizeMarkers(first);
+  return clean.length > MAX_HOOK_CHARS ? `${clean.slice(0, MAX_HOOK_CHARS - 1)}…` : clean;
+}
+
+/** The `headline — hook` text of an index line (§4.2), shared by the renderer and the cost
+ *  estimate so the price an entry is charged is the text it actually contributes. */
+function indexText(entry: ResolvedMemoryEntry): string {
+  const hook = indexHook(entry.body);
+  return hook ? `${memoryHeadline(entry.title)} — ${hook}` : memoryHeadline(entry.title);
+}
+
+/** The EXACT index line the renderer emits for an entry (§4.2: `- [id] headline — hook · Nt`).
+ *  ONE source for both the rendered bytes and the price, so the `· Nt` an entry advertises is the
+ *  cost it is actually charged. */
+function indexLine(entry: ResolvedMemoryEntry, fullTokens: number, bare = false): string {
+  return `- [${entry.id}] ${bare ? memoryHeadline(entry.title) : indexText(entry)} · ${fullTokens}t`;
+}
+
+/** What an index reference costs the prompt — the estimator run over the LITERAL line above
+ *  (#1979 I1, the `renderedCost` overpricing fix).
+ *
+ *  It used to price the line through `estimateEntryTokens`, which adds the 24t per-ENTRY framing
+ *  overhead (a title bullet, an id, a scope label) that a full row carries — but an index line is
+ *  not a framed entry, it is one line of prose the composer prints verbatim, so that overhead was
+ *  pure overcharge (~24t too high on EVERY index line, which is exactly the tax that made a
+ *  complete index look unaffordable). `estimateTextTokens` is the chars/4 arithmetic WITHOUT the
+ *  framing — the same estimator the instruction preface (also verbatim prose) is priced by.
+ *
+ *  Capped at the whole entry, still: for a short entry the reference line can out-price the body it
+ *  stands in for, and an index line advertising "· 47t" while costing 48t tells the agent to spend
+ *  more to say less. A reference is only ever a saving. */
+function indexRenderedCost(entry: ResolvedMemoryEntry, fullTokens: number, bare = false): number {
+  return Math.min(fullTokens, estimateTextTokens(indexLine(entry, fullTokens, bare)));
+}
+
+/**
+ * Compose the memory block for an identity.
+ *
+ * The pipeline: narrow the identity to `opts.cells` → resolve (shared-filtered, override-collapsed,
+ * deterministically sorted) → admit in TWO passes → render pinned bodies by kind, then the index,
+ * then the accounting footer.
+ *
+ * TWO ADMISSION PASSES (#1979 I1 — "complete index by construction"):
+ *   1. FULL BODIES. `pinned` candidates compete per cell (most-specific first) for the per-scope
+ *      budget and the whole-block ceiling, exactly as before. A pinned entry that does not fit is
+ *      NOT dropped — it DEMOTES to the index pass, carrying the reason (`budget`/`total`).
+ *   2. THE INDEX. Demoted pinned rules come first, most-specific first, hooked while the index cap
+ *      (`MEMORY_INDEX_TOKEN_CAP`) has room and hookless (title + id) past it, so none is ever
+ *      omitted (#3525). Natively-`indexed` entries take what the cap has left; only they can be
+ *      omitted (reason `index`), and the footer says so.
+ *
+ * DETERMINISTIC AND REPORTED throughout: first-fit in a fixed order, so the block is reproducible
+ * byte for byte, and every entry appears in `entries` with its fate — rendered, demoted, or omitted
+ * — even when NOTHING renders and the block is "" (the caller still emits the accounting event).
+ */
+export function composeMemoryPreamble(
+  identity: MemoryIdentity,
+  opts: ComposeMemoryPreambleOptions = {},
+  snapshot: MemoryPreambleSnapshot = readMemoryPreambleSnapshot(identity, opts),
+): ComposedMemoryPreamble {
+  const budget = opts.scopeTokenBudget ?? MEMORY_SCOPE_TOKEN_CAP;
+  const totalBudget = opts.totalTokenBudget ?? MEMORY_TOTAL_TOKEN_CAP;
+  // …and never more than HALF the ceiling, so protecting base can never starve the specific cells
+  // the ceiling is meant to favour. At the defaults (2048 of 4096) the two halves are equal.
+  const baseFloor = Math.max(0, Math.min(opts.baseTokenFloor ?? MEMORY_BASE_TOKEN_FLOOR, budget, Math.floor(totalBudget / 2)));
+  const instructionBudget = Math.max(0, opts.instructionTokenBudget ?? MEMORY_INSTRUCTION_TOKEN_CAP);
+  const indexBudget = Math.max(0, opts.indexTokenBudget ?? MEMORY_INDEX_TOKEN_CAP);
+
+  const narrowed = scopedIdentity(identity, opts.cells);
+  // ONE shared filter with the project render path (#1565 P5.4) — audience, tier, sensitivity and
+  // TTL are decided by `entryInjectability`, and every refusal comes back itemized so no drop is
+  // silent. `inject:'never'` is refused THERE now (pre-collapse), not skipped here.
+  const { entries: resolved, drops: filtered } = snapshot.memory;
+  const filteredByReason = filtered.length ? countInjectionDrops(filtered) : emptyDropCounts();
+  // The preface resolves FIRST and unconditionally: its slug statuses are reported even when
+  // nothing renders, because "the charter is missing" is exactly the case an operator needs to
+  // see and the one with no block to state it in.
+  const instruction = resolveInstructionPreface(opts.instructionSlugs ?? MEMORY_INSTRUCTION_SLUGS, narrowed.profile, instructionBudget);
+  const budgets: MemoryPreambleBudgetReport = { scope: budget, total: totalBudget, index: indexBudget, baseReserved: 0, instruction: instructionBudget };
+  const emptyOmittedByReason = (): Record<MemoryPreambleOmission, number> => ({ index: 0, instruction: instruction.truncated });
+  const emptyDemotedByReason = (): Record<MemoryPreambleDemotion, number> => ({ budget: 0, total: 0 });
+  const empty: ComposedMemoryPreamble = {
+    block: "",
+    tokens: 0,
+    instructionTokens: 0,
+    instructionSlugs: instruction.reports,
+    entries: [],
+    omitted: 0,
+    omittedByReason: emptyOmittedByReason(),
+    demoted: 0,
+    demotedByReason: emptyDemotedByReason(),
+    scopes: [],
+    budgets,
+    filtered,
+    filteredByReason,
+    areaDeferredCount: 0,
+    counterfactualTokens: 0,
+  };
+
+  // An empty `cells` set (Project Instructions off, now that #2154 left the project cell as the only
+  // one) still renders the PREFACE, so under shipped config OFF means a CHARTER-ONLY block, not "".
+  // Suppressing it was tried and reverted: an agent whose memory is off should still be told the
+  // store exists and that its coordinator is the fallback — otherwise the capability is invisible
+  // and it silently drops durable facts. (The retraction of an EARLIER block is handled separately,
+  // by `memoryRetractionBlock`, so that is no longer the reason.)
+  // #3508 — the startup block carries only `pinned` rules. An `indexed` entry is on demand (search,
+  // or on-touch when it names a path area) and a path-only entry of the agent's OWN project arrives
+  // when it first touches that area (#3409). Ancestor-project pinned entries stay: on-touch delivery
+  // serves the agent's own project only. Not a refusal, so it never enters `filtered`.
+  const all: Candidate[] = [];
+  const candidates: Candidate[] = [];
+  let order = 0;
+  for (const raw of resolved) {
+    isolateMemoryEntry(raw, () => {
+      const entry = { ...raw };
+      validateMemoryEntry(entry);
+      const fullTokens = estimateEntryTokens(entry);
+      const candidate: Candidate = {
+        entry,
+        nativeTier: entry.inject === "pinned" ? "pinned" : "indexed",
+        fullTokens,
+        indexTokens: indexRenderedCost(entry, fullTokens),
+        bareTokens: indexRenderedCost(entry, fullTokens, true),
+        order: order++,
+        specificity: MEMORY_SCOPE_CHAIN.indexOf(entry.cell),
+      };
+      all.push(candidate);
+      if (injectsAtStartup(entry) || (entry.inject === "pinned" && entry.projectId !== narrowed.projectId)) candidates.push(candidate);
+    });
+  }
+  const areaDeferredCount = all.length - candidates.length;
+
+  const limits = { scope: budget, total: totalBudget, index: indexBudget, baseFloor };
+  const admission = admitCandidates(candidates, limits, (overflow) => warnPinnedOverflow({
+    ...overflow,
+    ...(narrowed.profile ? { profile: narrowed.profile } : {}),
+  }));
+  const { outcome, byScope, omitted, demotedByReason, pinnedTokens, indexTokens } = admission;
+  budgets.baseReserved = admission.baseReserved;
+  const omittedByReason = { ...emptyOmittedByReason(), index: omitted };
+  const demoted = demotedByReason.budget + demotedByReason.total;
+  const tokens = pinnedTokens + indexTokens;
+  // What the block would have cost without the deferral: the SAME admission over every candidate,
+  // so the demotions and omissions the deferred entries would have caused are priced, not summed.
+  const counterfactual = areaDeferredCount ? admitCandidates(all, limits) : admission;
+  const counterfactualTokens = counterfactual.pinnedTokens + counterfactual.indexTokens;
+
+  // Per-cell rollup, from the settled outcomes so it is independent of which pass placed an entry.
+  const scopeReports = new Map<MemoryChainScope, MemoryPreambleScopeReport>();
+  for (const [cell, cellCandidates] of byScope) {
+    let rendered = 0;
+    let cellTokens = 0;
+    for (const candidate of cellCandidates) {
+      const o = outcome.get(candidate.order)!;
+      if (o.rendered) { rendered += 1; cellTokens += o.tokens; }
+    }
+    scopeReports.set(cell, { cell, budget, candidates: cellCandidates.length, rendered, tokens: cellTokens, omitted: cellCandidates.length - rendered });
+  }
+  const scopes = MEMORY_SCOPE_CHAIN.flatMap((cell) => scopeReports.get(cell) ?? []);
+
+  const reports: { order: number; report: MemoryPreambleEntryReport }[] = candidates.map((candidate) => ({
+    order: candidate.order,
+    report: reportFor(candidate, outcome.get(candidate.order)!),
+  }));
+
+  const pinnedRendered = candidates
+    .filter((c) => { const o = outcome.get(c.order)!; return o.tier === "pinned" && o.rendered; })
+    .sort((a, b) => a.order - b.order);
+  const indexRendered = candidates
+    .filter((c) => { const o = outcome.get(c.order)!; return o.tier === "indexed" && o.rendered; })
+    .sort((a, b) => a.order - b.order);
+
+  // "Empty templates + empty store ⇒ empty block ⇒ byte-identical spawn" (§10.1). Both halves have
+  // to be empty: an instructed agent with an empty store still gets the instruction, and an
+  // uninstructed one with entries still gets them. A deferral is content too (#3409): the block is
+  // the only place the agent learns those memories exist.
+  if (pinnedRendered.length === 0 && indexRendered.length === 0 && instruction.parts.length === 0 && areaDeferredCount === 0) {
+    return { ...empty, entries: sortReports(reports), omitted, omittedByReason, demoted, demotedByReason, scopes, budgets, areaDeferredCount, counterfactualTokens };
+  }
+
+  // The header describes the identity the block was actually COMPOSED FOR (`narrowed`), not the
+  // one the caller holds: naming a project whose cell the walk excluded would advertise knowledge
+  // that is not in the block.
+  // #3698 — the render time sits right under the header, from the one render clock (`opts.now` is the
+  // TTL clock); content hashes strip it (memoryBlockHash).
+  const lines: string[] = [MEMORY_PREAMBLE_MARKER, memoryHeader(narrowed, snapshot.project), renderedAtLine(contextRenderNow())];
+  // The instruction preface sits between the header and the first `##` section (§10.1): inside the
+  // markers, so strip-and-replace already owns it and no second marker/strip rule exists to stack.
+  for (const part of instruction.parts) lines.push("", part);
+  let lastKind: ProjectEntryKind | null = null;
+  for (const candidate of pinnedRendered) {
+    // `pinnedRendered` is resolver-ordered and the resolver sorts by kind FIRST, so entries of one
+    // kind are contiguous and each `## heading` is emitted exactly once.
+    if (candidate.entry.kind !== lastKind) {
+      lines.push("", `## ${KIND_HEADINGS[candidate.entry.kind]}`);
+      lastKind = candidate.entry.kind;
+    }
+    // Content is neutralized, never interpolated raw — see `MARKER_SHAPED`.
+    const line = isolateMemoryEntry(candidate.entry, () => {
+      const title = neutralizeMarkers(candidate.entry.title.trim());
+      const body = candidate.entry.body?.trim();
+      return body ? `- ${title}: ${neutralizeMarkers(body)}` : `- ${title}`;
+    });
+    if (line) lines.push(line);
+  }
+  if (indexRendered.length) {
+    lines.push("", INDEX_HEADING, INDEX_FETCH_DIRECTIVE);
+    for (const candidate of indexRendered) {
+      // §4.2: `headline + hook + id + token cost`. Without the hook an index is a list of
+      // titles, and the agent has to spend a retrieval to learn what it declined to read.
+      const line = isolateMemoryEntry(candidate.entry, () => indexLine(candidate.entry, candidate.fullTokens, outcome.get(candidate.order)!.bare));
+      if (line) lines.push(line);
+    }
+  }
+  lines.push("", accountingFooter(pinnedRendered.length, pinnedTokens, indexRendered.length, indexTokens, tokens, instruction.tokens, omittedByReason, demotedByReason, budgets, filteredByReason, areaDeferredCount), MEMORY_PREAMBLE_END_MARKER);
+
+  return {
+    block: lines.join("\n"),
+    tokens,
+    instructionTokens: instruction.tokens,
+    instructionSlugs: instruction.reports,
+    entries: sortReports(reports),
+    omitted,
+    omittedByReason,
+    demoted,
+    demotedByReason,
+    scopes,
+    budgets,
+    filtered,
+    filteredByReason,
+    areaDeferredCount,
+    counterfactualTokens,
+  };
+}
+
+/** Apply `opts.cells` by narrowing identity-only keys before resolution. `operator` and `profile`
+ * survive because they identify the caller and select audience; `ResolveMemoryOptions.cells` is
+ * the authoritative cell filter, so retaining them cannot re-enable the legacy base anchor. */
+function scopedIdentity(identity: MemoryIdentity, cells: readonly MemoryChainScope[] | undefined): MemoryIdentity {
+  if (!cells) return identity;
+  const included = new Set(cells);
+  return {
+    ...(identity.operator ? { operator: identity.operator } : {}),
+    ...(identity.profile ? { profile: identity.profile } : {}),
+    ...(included.has("provider") && identity.provider ? { provider: identity.provider } : {}),
+    ...(included.has("host") && identity.host ? { host: identity.host } : {}),
+    ...(included.has("project") && identity.projectId ? { projectId: identity.projectId } : {}),
+  };
+}
+
+function reportFor(candidate: Candidate, outcome: Outcome): MemoryPreambleEntryReport {
+  return {
+    id: candidate.entry.id,
+    kind: candidate.entry.kind,
+    title: candidate.entry.title,
+    cell: candidate.entry.cell,
+    tier: outcome.tier,
+    tokens: outcome.tokens,
+    fullTokens: candidate.fullTokens,
+    rendered: outcome.rendered,
+    ...(outcome.demoted ? { demoted: true } : {}),
+    ...(outcome.demotedReason ? { demotedReason: outcome.demotedReason } : {}),
+    ...(outcome.omittedReason ? { omittedReason: outcome.omittedReason } : {}),
+  };
+}
+
+/** Reports come back in the RESOLVER's order regardless of which pass produced them, so the
+ *  telemetry a spawn emits is as reproducible as the block itself. */
+function sortReports(reports: { order: number; report: MemoryPreambleEntryReport }[]): MemoryPreambleEntryReport[] {
+  return [...reports].sort((a, b) => a.order - b.order).map(({ report }) => report);
+}
+
+/** `# Memory — worker @ wbox-1 · humwick` (§4.2). Built from the identity alone, so it is
+ *  stable across spawns of the same agent shape. */
+function memoryHeader(identity: MemoryIdentity, project: MemoryPreambleSnapshot["project"]): string {
+  const who = [identity.profile?.trim() || "agent", identity.host?.trim() ? `@ ${identity.host.trim()}` : ""]
+    .filter(Boolean)
+    .join(" ");
+  // The SLUG rides beside the title (never instead of it): the fetch directive below tells the
+  // agent to call relay_project_read, and a cwd the relay cannot resolve to a project answers
+  // "no project: pass `project`" — with nothing in the block to pass. A title is not an accepted
+  // ref; the slug is. Omitted when they are the same string, so the common case costs nothing.
+  const label = project ? (project.title?.trim() || project.slug) : "";
+  const where = project ? ` · ${label}${label === project.slug ? "" : ` (${project.slug})`}` : "";
+  // Neutralized like entry content: a profile name / hostname / project title is data too.
+  return neutralizeMarkers(`# Memory — ${who}${where}`);
+}
+
+function entriesLabel(count: number): string {
+  return `${count} ${count === 1 ? "entry" : "entries"}`;
+}
+
+/** The §4.2 accounting line: what was injected, what it cost, what was dropped, and how to get
+ *  the rest. This is the agent-facing half of the token transparency the epic asks for. */
+function accountingFooter(
+  pinnedCount: number,
+  pinnedTokens: number,
+  indexCount: number,
+  indexTokens: number,
+  tokens: number,
+  instructionTokens: number,
+  omittedByReason: Record<MemoryPreambleOmission, number>,
+  demotedByReason: Record<MemoryPreambleDemotion, number>,
+  budgets: MemoryPreambleBudgetReport,
+  filteredByReason: InjectionDropCounts,
+  areaDeferredCount: number,
+): string {
+  // The preface is priced beside the entries rather than folded into them: it is charged against a
+  // different cap, and an agent reading "= N tokens" is owed the number it actually pays.
+  const parts = [
+    pinnedCount ? `${entriesLabel(pinnedCount)} pinned (${pinnedTokens}t)` : "",
+    indexCount ? `${indexCount} indexed headline${indexCount === 1 ? "" : "s"} (${indexTokens}t)` : "",
+    instructionTokens ? `instructions (${instructionTokens}t)` : "",
+  ].filter(Boolean);
+  // Nothing priced is reachable only when every entry was deferred (#3409).
+  const cost = parts.length ? `${parts.join(" + ")} = ${tokens + instructionTokens} tokens` : "0 tokens";
+  return `_Injected memory: ${cost}.${omissionSentence(omittedByReason, demotedByReason, budgets)}${filterSentence(filteredByReason)}${areaDeferredSentence(areaDeferredCount)} Full list: relay_project_read()._`;
+}
+
+/**
+ * The filter's drops, stated IN THE BLOCK (#1565 P5.4) — counts and causes only, never a title.
+ *
+ * An agent that is told "2 entries were not injectable" can ask, or retrieve; one told nothing
+ * cannot tell "there is no such rule" from "there is a rule you were not given", which is the
+ * difference between a bounded prompt and a misleading one. Counts are safe where content is not:
+ * naming a sensitive entry is the leak the refusal exists to prevent.
+ */
+function filterSentence(filteredByReason: InjectionDropCounts): string {
+  const described = describeInjectionDrops(filteredByReason);
+  if (!described) return "";
+  const total = Object.values(filteredByReason).reduce((sum, count) => sum + count, 0);
+  return ` ${entriesLabel(total)} not injectable (${described}).`;
+}
+
+/** #3409/#3508 — deferred entries are not refusals, so they get their own sentence. Counts only. */
+function areaDeferredSentence(count: number): string {
+  if (!count) return "";
+  return ` ${count === 1 ? "1 memory loads" : `${count} memories load`} on demand: when you first touch a file in ${count === 1 ? "its" : "their"} area, or via relay_project_search.`;
+}
+
+/**
+ * The one true entry loss, with its cause (#1979 I1). Since I1 an injectable entry is dropped ONLY
+ * when even a one-line index reference will not fit the index cap — every budget/ceiling miss now
+ * DEMOTES to the index instead (see `describeMemoryDemotions`). So this describes the `index` reason
+ * alone.
+ *
+ * Exported so the block's footer and the `relay-injection` event's summary say the same thing — the
+ * agent and the operator must not be told different stories about the same drop. `budgets` adds the
+ * actual cap; omit it where the line has to stay short.
+ *
+ * ENTRY drops only. The `instruction` reason is described by `describeInstructionTruncation`,
+ * because every caller of this one renders it inside an "N entries omitted (…)" sentence and a
+ * truncated instruction slug is not an entry.
+ */
+export function describeMemoryOmissions(
+  omittedByReason: Record<MemoryPreambleOmission, number>,
+  budgets?: MemoryPreambleBudgetReport,
+): string {
+  if (!omittedByReason.index) return "";
+  return `${omittedByReason.index} over the ${budgets ? `${budgets.index}t ` : ""}index cap`;
+}
+
+/**
+ * The DEMOTIONS, with their real cause (#1979 I1 — the softening that replaced the old omission).
+ * A `pinned` entry the full-body budget could not fit is not dropped; it is rendered as a one-line
+ * index reference, and this names WHY its body did not fit: a cell's own per-scope budget vs. the
+ * whole-block ceiling. Different levers (#1602's discipline), so they stay distinct.
+ *
+ * Exported for the same reason as `describeMemoryOmissions`: the footer and the event must agree.
+ */
+export function describeMemoryDemotions(
+  demotedByReason: Record<MemoryPreambleDemotion, number>,
+  budgets?: MemoryPreambleBudgetReport,
+): string {
+  // The ceiling a non-base cell actually spent against is the ceiling MINUS base's reservation
+  // (#1565 F4). Naming only the raw ceiling points at a number the demotion did not happen at.
+  const ceiling = budgets
+    ? `${budgets.total}t ${budgets.baseReserved > 0 ? `whole-block cap (${budgets.total - budgets.baseReserved}t for cells other than base, which reserves ${budgets.baseReserved}t)` : "whole-block cap"}`
+    : "whole-block cap";
+  return [
+    demotedByReason.budget ? `${demotedByReason.budget} over the ${budgets ? `${budgets.scope}t ` : ""}per-cell budget` : "",
+    demotedByReason.total ? `${demotedByReason.total} over the ${ceiling}` : "",
+  ].filter(Boolean).join(", ");
+}
+
+function omissionSentence(
+  omittedByReason: Record<MemoryPreambleOmission, number>,
+  demotedByReason: Record<MemoryPreambleDemotion, number>,
+  budgets: MemoryPreambleBudgetReport,
+): string {
+  const demoted = demotedByReason.budget + demotedByReason.total;
+  // Demotion first (a softening — the entry is still in the block, in the index), then the rare
+  // true omission, then instruction truncation. Each is a separate cause with a separate fix, so
+  // none is folded into another's count (#1602's discipline).
+  const demotionSentence = demoted ? ` ${entriesLabel(demoted)} demoted to the index (${describeMemoryDemotions(demotedByReason, budgets)}).` : "";
+  const omittedSentence = omittedByReason.index ? ` ${entriesLabel(omittedByReason.index)} omitted (${describeMemoryOmissions(omittedByReason, budgets)}; oldest and least role-specific first — relay_project_search finds them).` : "";
+  return `${demotionSentence}${omittedSentence}${describeInstructionTruncation(omittedByReason, budgets)}`;
+}
+
+/**
+ * The instruction slugs that did not resolve AT ALL — a slug in neither the store nor the shipped
+ * defaults (`missing`), or one whose resolution threw (`failed`). Both mean the preface is quietly
+ * shorter than the operator believes it is.
+ *
+ * `blank` is deliberately NOT a defect: a blanked slug is §10.3.5's K2 kill switch WORKING, and
+ * counting it here would make every deliberately-uninstructed agent report a defect at every
+ * boundary. `truncated` is not here either — it has its own reason (`omittedByReason.instruction`)
+ * and its own clause (`describeInstructionTruncation`), and reporting it twice would double-count
+ * one slug. `rendered` with an `error` is a degraded-to-shipped-default render: text DID reach the
+ * prompt, so it is not this list's business.
+ */
+export function unresolvedInstructionSlugs(reports: readonly MemoryInstructionReport[]): MemoryInstructionReport[] {
+  return reports.filter((report) => report.status === "missing" || report.status === "failed");
+}
+
+/** The instruction-side clause for slugs that did not resolve at all — the twin of
+ *  `describeInstructionTruncation`, for the defect that produces NO text rather than short text.
+ *  "" when every requested slug resolved (or was deliberately blanked), so callers can splice it
+ *  into a sentence unconditionally. */
+export function describeUnresolvedInstructions(reports: readonly MemoryInstructionReport[]): string {
+  const unresolved = unresolvedInstructionSlugs(reports);
+  if (!unresolved.length) return "";
+  const slugs = unresolved.length === 1 ? "slug" : "slugs";
+  const named = unresolved.map((report) => `${report.resolved}: ${report.status}`).join(", ");
+  return ` ${unresolved.length} instruction ${slugs} did not resolve (${named}).`;
+}
+
+/** The instruction-side omission clause (§10.1's `instruction` reason). Exported so the block's
+ *  footer and the `relay-injection` summaries say the same thing about the same truncation. */
+export function describeInstructionTruncation(
+  omittedByReason: Record<MemoryPreambleOmission, number>,
+  budgets?: MemoryPreambleBudgetReport,
+): string {
+  if (!omittedByReason.instruction) return "";
+  const cap = budgets ? `${budgets.instruction}t ` : "";
+  const slugs = omittedByReason.instruction === 1 ? "slug" : "slugs";
+  return ` ${omittedByReason.instruction} instruction ${slugs} truncated at the ${cap}instruction cap (charged outside the entry budgets — no entry was dropped for it).`;
+}
+
+// #2097 — a TRANSPORT bound on the spawn memory-injection EVENT detail (NOT the injected block).
+//
+// #1979 Wave A (55d4422d) made the index "complete by construction": the composed `entries` and
+// `filtered` arrays now enumerate EVERY entry — injected, demoted, and every not-injectable one —
+// each with a title up to 120 chars. Those arrays grow with the whole store, so a large store
+// pushed the spawn memory event's `detail` past the 64 KiB `cleanParams` payload cap
+// (src/validation.ts, POST /api/messages). The spawn event is emitted by the RUNNER over HTTP, so
+// that POST was rejected and the visible "injected memory" timeline entry silently vanished for
+// large-memory agents — while the block itself still injected via `systemPromptAppend` (a separate
+// field). The clear/compact re-inject event is emitted server-side (emitRelayInjectionEvent →
+// sendMessageWithResult) and never goes through that route, so it is deliberately NOT bounded here.
+//
+// The bound is by COUNT, not by measuring bytes: per-entry size is already bounded (titles capped at
+// 120 chars by #1979, ids/cells/reasons short), so a fixed head count gives an arithmetic ceiling
+// well under 64 KiB regardless of how many entries the store holds. The dashboard cost panel
+// (MemoryInjectionCost.tsx) reads authoritative `*Total`/`*Count` scalars the caller sets before
+// bounding, so its headline numbers stay exact even when the arrays are trimmed; it renders a
+// "N more" tail from the same totals.
+export const SPAWN_MEMORY_EVENT_MAX_ENTRIES = 50;
+export const SPAWN_MEMORY_EVENT_MAX_FILTERED = 50;
+export const SPAWN_MEMORY_EVENT_MAX_CONTENT_CHARS = 16_384;
+/** Serialized-byte backstop threshold — safely under the 64 KiB (`65_536`) `cleanParams` cap. The
+ *  fixed head/char caps above assume per-entry size is bounded (titles ≤120), but that cap is only
+ *  enforced at the MCP write boundary: blackboard-promotion, consolidation, imports and legacy
+ *  pre-#1979 rows can persist longer titles. So after the head trim we MEASURE the actual payload
+ *  and shed further until under this threshold — defending every field, not just title length
+ *  (#2097 review GAP-1). */
+export const SPAWN_MEMORY_EVENT_MAX_DETAIL_BYTES = 60_000;
+
+const SPAWN_MEMORY_EVENT_CONTENT_TRUNCATED_SUFFIX = "\n\n… (block truncated for the timeline event — the full block is in the agent's context)";
+
+/** Trim the heavy, store-size-dependent fields of a spawn memory-injection event `detail` so the
+ *  POSTed session payload stays comfortably under the 64 KiB `cleanParams` cap regardless of store
+ *  size AND regardless of any single field's size. Returns a shallow copy — the input (and the
+ *  composed preamble it came from) is untouched. Only `entries`, `filtered` and `content` are
+ *  bounded; every scalar/accounting field is preserved verbatim, so the authoritative counts the
+ *  caller attached survive (the dashboard renders exact totals + a "N more" tail from them). */
+export function boundMemoryInjectionEventDetail(detail: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...detail };
+  // Pass 1 — fixed head/char caps: the common large-store case is bounded in one shot.
+  if (Array.isArray(out.entries) && out.entries.length > SPAWN_MEMORY_EVENT_MAX_ENTRIES) {
+    out.entries = out.entries.slice(0, SPAWN_MEMORY_EVENT_MAX_ENTRIES);
+  }
+  if (Array.isArray(out.filtered) && out.filtered.length > SPAWN_MEMORY_EVENT_MAX_FILTERED) {
+    out.filtered = out.filtered.slice(0, SPAWN_MEMORY_EVENT_MAX_FILTERED);
+  }
+  if (typeof out.content === "string" && out.content.length > SPAWN_MEMORY_EVENT_MAX_CONTENT_CHARS) {
+    out.content = `${out.content.slice(0, SPAWN_MEMORY_EVENT_MAX_CONTENT_CHARS)}${SPAWN_MEMORY_EVENT_CONTENT_TRUNCATED_SUFFIX}`;
+    out.contentTruncated = true;
+  }
+  // Pass 2 — serialized-byte backstop (#2097 GAP-1): if the head-trimmed detail still exceeds the
+  // threshold (e.g. a handful of entries with pathologically long titles that never went through
+  // the ≤120 MCP write cap), shed until under. Content is cut first (the full block is already in
+  // the agent's context), then entries/filtered one at a time from the tail; the authoritative
+  // count scalars are never touched, so the panel's totals + "N more" stay exact. Guaranteed to
+  // terminate: every iteration strictly shrinks a field, and once the arrays are empty and the
+  // content copy is gone only bounded scalars remain (well under the threshold).
+  while (JSON.stringify(out).length > SPAWN_MEMORY_EVENT_MAX_DETAIL_BYTES) {
+    if (typeof out.content === "string" && out.content.length > 2_000) {
+      out.content = `${out.content.slice(0, 2_000)}${SPAWN_MEMORY_EVENT_CONTENT_TRUNCATED_SUFFIX}`;
+      out.contentTruncated = true;
+      continue;
+    }
+    const entries = Array.isArray(out.entries) ? (out.entries as unknown[]) : [];
+    const filtered = Array.isArray(out.filtered) ? (out.filtered as unknown[]) : [];
+    if (entries.length > 0 && entries.length >= filtered.length) {
+      out.entries = entries.slice(0, entries.length - 1);
+    } else if (filtered.length > 0) {
+      out.filtered = filtered.slice(0, filtered.length - 1);
+    } else if (typeof out.content === "string" && out.content.length > 0) {
+      out.content = "… (block omitted for the timeline event — the full block is in the agent's context)";
+      out.contentTruncated = true;
+    } else {
+      break;
+    }
+  }
+  return out;
+}