@seanhogg/builderforce-memory 2026.10.23 → 2026.10.25

package/src/working/transcript.ts

@@ -0,0 +1,291 @@
+/**
+ * The working transcript — what of a run the model is SHOWN each turn.
+ *
+ * A run's full transcript grows without bound; the request sent to the model must not.
+ * This module owns the two ways it is kept in bounds: the message-count + token WINDOW
+ * (drop-oldest, anchored on a user turn) and AUTO-COMPACTION (fold the older part into a
+ * memory note, keep every later message verbatim). A host supplies only what is
+ * run-specific: the summarizer it calls (see `summary.ts`) and what a fold records.
+ *
+ * Pure except for {@link buildWorkingTranscript}, which awaits the injected summarizer and
+ * updates the caller's `compactMemo`. Generic over the host's message shape: anything with
+ * the OpenAI-style `role` / `content` / `tool_calls` fields (`HandoffMessage`).
+ */
+
+import { defaultEstimateTokens, messageTokens as handoffMessageTokens, tokensOf as handoffTokensOf } from '../handoff/budget.js';
+import type { HandoffMessage } from '../handoff/types.js';
+
+/** A transcript message — the hand-off packer's shape, so both count a message alike. */
+export type TranscriptMessage = HandoffMessage;
+
+/** How much history we send to the model (message-count ceiling). */
+export const HISTORY_WINDOW = 80;
+
+/**
+ * Token budget for the working transcript sent to the model each turn — how much of this
+ * run the model can SEE: the file windows it read, the searches it ran, what it decided.
+ *
+ * It bounds context, which message-count windowing (HISTORY_WINDOW) alone does not: one
+ * `tasks.list` result can be tens of thousands of tokens. It is NOT what keeps a request
+ * inside the serving model's window — the gateway fits every request to a model that can
+ * hold it.
+ *
+ * It was 24k, "sized under the smallest pool model's window". That protected nothing — the
+ * ~16k-token system prompt + tool catalog in front of it already put a full turn at ~40k,
+ * past any 32k window — and it cost every coding run its memory. Six 4k-token file windows
+ * filled it, compaction folded them into a 1.2k-token note, and the model went back for the
+ * files it had just read (chat #105: 55 turns, 63% of calls revisiting, zero edits, prompt
+ * peak 40,351). 64k holds a coding task's working set — a dozen-plus file windows —
+ * verbatim, while a full turn stays well inside the 128k window every coding-capable pool
+ * model has. See {@link windowed} and {@link buildWorkingTranscript}.
+ */
+export const HISTORY_TOKEN_BUDGET = 64_000;
+/**
+ * How much of {@link HISTORY_TOKEN_BUDGET} the verbatim TAIL may keep when the older part
+ * of the transcript is compacted. The rest is headroom new work fills before the next
+ * fold, so the memo is re-folded once per ~20k tokens of progress, not on every turn.
+ */
+export const COMPACT_TAIL_TOKEN_BUDGET = 40_000;
+
+/** Estimated tokens for one message (content + tool-call payload + framing) — THE
+ *  hand-off packer's estimate, so the working transcript and a hand-off to a smaller
+ *  model count a message the same way. */
+function messageTokens(m: TranscriptMessage): number {
+  return handoffMessageTokens(m, defaultEstimateTokens);
+}
+
+/**
+ * The compressed memory of a transcript's older part: `note` summarizes
+ * `transcript[0, coveredEnd)`; every message from `coveredEnd` on is sent verbatim.
+ */
+export interface CompactMemo {
+  note: string;
+  coveredEnd: number;
+}
+
+/**
+ * What the working transcript is built from — the run's full transcript and its cached
+ * compressed memory. {@link buildWorkingTranscript} updates `compactMemo` in place.
+ */
+export interface WorkingTranscriptState<M extends TranscriptMessage = TranscriptMessage> {
+  transcript: M[];
+  compactMemo: CompactMemo | null;
+}
+
+/**
+ * Trim the in-memory transcript to the history window before sending it to the
+ * model. Slicing the last N can leave the window starting on an `assistant`
+ * tool-call turn or an orphaned `tool` result (whose owning call fell off the
+ * front). That payload is invalid for strict vendors: Gemini rejects a request
+ * whose conversation does not begin with a user turn — surfaced as the cascade
+ * `[googleai] 400 INVALID_ARGUMENT` after a long tool-loop crossed the window
+ * boundary. So anchor the window at a user turn.
+ *
+ * If the last-N slice contains no user turn (a tool loop longer than the
+ * window), fall back to the most recent user turn in the FULL transcript and
+ * keep everything after it — correctness over the size cap.
+ */
+export function windowed<M extends TranscriptMessage>(convo: M[]): M[] {
+  let w = convo.slice(-HISTORY_WINDOW);
+  while (w.length > 0 && w[0]!.role !== 'user') w = w.slice(1);
+  if (w.length === 0) {
+    const lastUser = convo.map((m) => m.role).lastIndexOf('user');
+    w = lastUser >= 0 ? convo.slice(lastUser) : convo.slice();
+  }
+  return tokenBounded(w);
+}
+
+/**
+ * Enforce the token budget on an already message-count-windowed slice. Drops the
+ * OLDEST turns first, then re-anchors on a user turn (a strict vendor rejects a window
+ * that doesn't start on `user`, and dropping a turn can orphan a `tool` result whose
+ * `assistant` tool-call fell off the front). The most recent user turn is never
+ * dropped: correctness over the budget when a single turn is itself oversized.
+ */
+function tokenBounded<M extends TranscriptMessage>(w: M[]): M[] {
+  let total = transcriptTokens(w);
+  if (total <= HISTORY_TOKEN_BUDGET) return w;
+  const lastUser = w.map((m) => m.role).lastIndexOf('user');
+  let start = 0;
+  while (total > HISTORY_TOKEN_BUDGET && start < lastUser) {
+    total -= messageTokens(w[start]!);
+    start += 1;
+  }
+  let trimmed = w.slice(start);
+  while (trimmed.length > 1 && trimmed[0]!.role !== 'user') trimmed = trimmed.slice(1);
+  return trimmed;
+}
+
+/**
+ * Is a transcript message still part of what the model sees? False once auto-compaction
+ * has folded it into the memory note, or the drop-oldest window has let it fall off the
+ * front. Deliberately conservative: it judges against the CURRENT transcript (which has
+ * grown since the last working set was built), so it can only ever call a message gone a
+ * turn early — a needless replay costs tokens, a stub for a vanished result costs the run.
+ */
+export function stillInWorkingContext<M extends TranscriptMessage>(state: WorkingTranscriptState<M>, anchor: unknown): boolean {
+  const convo = state.transcript;
+  const idx = convo.indexOf(anchor as M);
+  if (idx < 0) return false;
+  if (state.compactMemo) return idx >= verbatimStart(convo, state.compactMemo.coveredEnd);
+  return windowed(convo).includes(convo[idx]!);
+}
+
+// ---------------------------------------------------------------------------
+// Auto-compaction — summarize the bulky MIDDLE instead of dropping it.
+//
+// `tokenBounded` keeps the request inside the window by DROPPING the oldest turns. That
+// never 413s, but it silently LOSES context — which made a weak model re-read files and
+// thrash ("LOOP EXHAUSTED", chat #50). When a summarizer is available the older turns are
+// compressed into ONE memory note instead, so the model keeps working from a distilled
+// memory. Falls back to `tokenBounded` when no summarizer is reachable.
+//
+// Why this fold is NOT `packHandoff` (`../handoff`): the packer is stateless and gives the
+// verbatim tail priority, handing the note whatever room the tail leaves. The working
+// transcript needs the opposite on both counts — an INCREMENTAL memo reused across turns
+// (one summarizer call per ~20k tokens of progress), a tail capped at
+// COMPACT_TAIL_TOKEN_BUDGET so the note and the next turns have headroom, and a
+// message-count window. What the two share — the token estimate — is the packer's.
+// ---------------------------------------------------------------------------
+
+/** The fewest recent messages the verbatim tail keeps, however large they are. */
+export const COMPACT_TAIL_TURNS = 8;
+
+/** The most recent messages the verbatim tail may hold — half the message window, so a
+ *  compacted transcript stays inside {@link HISTORY_WINDOW} with room to grow. */
+const COMPACT_TAIL_MAX_MESSAGES = HISTORY_WINDOW / 2;
+
+/** The first index at or after `from` that is not a `tool` result: a tool row whose
+ *  assistant call was folded into the memo would be orphaned (strict vendors 400 on it). */
+export function verbatimStart(convo: readonly TranscriptMessage[], from: number): number {
+  let start = Math.max(0, Math.min(from, convo.length));
+  while (start < convo.length && convo[start]!.role === 'tool') start += 1;
+  return start;
+}
+
+/** Start index of the last `tailTurns` messages, walked off a leading `tool` result. */
+export function compactTailStart(convo: readonly TranscriptMessage[], tailTurns: number): number {
+  return verbatimStart(convo, convo.length - tailTurns);
+}
+
+/**
+ * Where the verbatim tail begins when the transcript is compacted: as many of the most
+ * recent messages as fit in `budgetTokens` — never fewer than {@link COMPACT_TAIL_TURNS},
+ * never more than {@link COMPACT_TAIL_MAX_MESSAGES} — walked off a leading tool result.
+ *
+ * Sized by TOKENS, not a message count: a fixed eight messages is four tool results, so
+ * after a fold the fifth file the model needed was always the one it had to read again.
+ */
+export function compactTailStartForBudget(convo: readonly TranscriptMessage[], budgetTokens: number): number {
+  let start = convo.length;
+  let tokens = 0;
+  while (start > 0) {
+    const kept = convo.length - start;
+    if (kept >= COMPACT_TAIL_MAX_MESSAGES) break;
+    const next = messageTokens(convo[start - 1]!);
+    if (kept >= COMPACT_TAIL_TURNS && tokens + next > budgetTokens) break;
+    tokens += next;
+    start -= 1;
+  }
+  return verbatimStart(convo, start);
+}
+
+/**
+ * Index of the MOST RECENT user turn to re-inject verbatim ahead of the tail — the
+ * ACTIVE directive — or -1 when the latest user turn is already inside the tail. Pinning
+ * the FIRST user turn (the old behaviour) made a multi-instruction chat revert to its
+ * opening request (chat #55); the current instruction is always the LATEST user turn.
+ */
+export function pinnedDirectiveIndex(convo: readonly TranscriptMessage[], tailStart: number): number {
+  const lastUser = convo.map((m) => m.role).lastIndexOf('user');
+  return lastUser >= 0 && lastUser < tailStart ? lastUser : -1;
+}
+
+/**
+ * Assemble the working transcript from a compressed-memory `note` that covers
+ * `convo[0, coveredEnd)`: system + the memory note + the ACTIVE user directive re-injected
+ * verbatim (when the note covers it) + EVERY message from `coveredEnd` on (tool-pairing
+ * safe via {@link verbatimStart}). Nothing is in neither the note nor the tail. The
+ * directive sits immediately before the tail so the model reads it as the CURRENT
+ * instruction.
+ */
+export function assembleCompacted<M extends TranscriptMessage>(
+  systemPrompt: string,
+  convo: M[],
+  note: string,
+  coveredEnd: number,
+): M[] {
+  const tailStart = verbatimStart(convo, coveredEnd);
+  const out: M[] = [{ role: 'system', content: systemPrompt } as M];
+  out.push({ role: 'assistant', content: note } as M);
+  const directiveIdx = pinnedDirectiveIndex(convo, tailStart);
+  if (directiveIdx >= 0) out.push(convo[directiveIdx]!);
+  out.push(...convo.slice(tailStart));
+  return out;
+}
+
+/** Estimated tokens of a message list — the ONE count compaction budgets by, exported so
+ *  a run measures what compaction kept out of a call with the same rule. */
+export function transcriptTokens(msgs: readonly TranscriptMessage[]): number {
+  return handoffTokensOf(msgs, defaultEstimateTokens);
+}
+
+/** Can these messages (plus `extraTokens` in front of them) go to the model verbatim —
+ *  inside both the token budget and the message window? */
+function fitsVerbatim(msgs: readonly TranscriptMessage[], extraTokens = 0): boolean {
+  return msgs.length <= HISTORY_WINDOW && extraTokens + transcriptTokens(msgs) <= HISTORY_TOKEN_BUDGET;
+}
+
+/** What a fold reports: how many messages it newly compressed, the note it wrote, and
+ *  the transcript index the note now covers up to (exclusive). */
+export interface TranscriptFold {
+  droppedMessages: number;
+  note: string;
+  coveredEnd: number;
+}
+
+/**
+ * Build the working transcript for a turn. When the whole transcript fits → all of it,
+ * verbatim. Otherwise → a memory note of the older part plus EVERY message after it,
+ * verbatim; `onFolded` is told about each NEW fold, so the caller can record it (a
+ * visible step, a durable consolidation marker).
+ *
+ * The note is folded INCREMENTALLY, and only when it has to be. A note whose verbatim
+ * remainder still fits is reused as-is; once it no longer fits, the previous note plus
+ * exactly the messages since it are folded into a new one, up to a token-sized tail
+ * ({@link compactTailStartForBudget}). Falls back to drop-oldest when the summarizer is
+ * unavailable (`summarize` resolves null). A message-count overflow folds too.
+ */
+export async function buildWorkingTranscript<M extends TranscriptMessage>(
+  state: WorkingTranscriptState<M>,
+  systemPrompt: string,
+  summarize: (msgs: M[]) => Promise<string | null>,
+  onFolded: (fold: TranscriptFold) => void,
+): Promise<M[]> {
+  const convo = state.transcript;
+  if (fitsVerbatim(convo)) {
+    state.compactMemo = null; // back under budget — a later overflow summarizes afresh
+    return [{ role: 'system', content: systemPrompt } as M, ...windowed(convo)];
+  }
+  // A note written against a transcript that has since been replaced covers nothing here.
+  const memo = state.compactMemo && state.compactMemo.coveredEnd <= convo.length ? state.compactMemo : null;
+  if (memo && fitsVerbatim(convo.slice(verbatimStart(convo, memo.coveredEnd)), defaultEstimateTokens(memo.note))) {
+    return assembleCompacted(systemPrompt, convo, memo.note, memo.coveredEnd);
+  }
+  const from = memo?.coveredEnd ?? 0;
+  const to = Math.max(from, compactTailStartForBudget(convo, COMPACT_TAIL_TOKEN_BUDGET));
+  const fold: M[] = memo
+    ? [{ role: 'assistant', content: memo.note } as M, ...convo.slice(from, to)]
+    : convo.slice(from, to);
+  const summary = to > from ? await summarize(fold) : null;
+  if (summary == null) {
+    // Nothing new to fold, or no summarizer: keep the note already held, else drop-oldest.
+    return memo
+      ? assembleCompacted(systemPrompt, convo, memo.note, memo.coveredEnd)
+      : [{ role: 'system', content: systemPrompt } as M, ...windowed(convo)];
+  }
+  const note = `Compressed memory of the first ${to} message(s) of this conversation:\n${summary}`;
+  state.compactMemo = { note, coveredEnd: to };
+  onFolded({ droppedMessages: to - from, note, coveredEnd: to });
+  return assembleCompacted(systemPrompt, convo, note, to);
+}

package/src/working/types.ts

@@ -0,0 +1,32 @@
+/**
+ * The working-memory contract — pure data, so the subpath stays Worker/browser/Node safe.
+ */
+
+/** One thing a run did that is worth remembering, in the memory's own terms. */
+export type Observation =
+  | { kind: 'read' | 'created' | 'edited' | 'deleted'; path: string }
+  | { kind: 'searched'; query: string };
+
+/** What a run's working memory holds. Lists keep duplicates — how often is a signal. */
+export interface WorkingMemorySnapshot {
+  /** What the run was asked. */
+  task?: string;
+  created: readonly string[];
+  edited: readonly string[];
+  deleted: readonly string[];
+  read: readonly string[];
+  searched: readonly string[];
+}
+
+/** One long-term memory, ready for a keyed store: the same key replaces (or merges). */
+export interface ConsolidatedMemory {
+  key: string;
+  content: string;
+}
+
+export interface ConsolidateOptions {
+  /** Dates the memory so a reader can judge its age. */
+  at?: Date;
+  /** The workspace root — absolute paths under it are kept, made relative. */
+  root?: string;
+}

package/src/working/working.test.ts

@@ -0,0 +1,120 @@
+/**
+ * src/working/working.test.ts
+ * Short-term working memory (the per-turn brief) and its consolidation into a long-term
+ * code map, including the write-side merge a keyed store applies.
+ */
+
+import { consolidate, mergeConsolidated, WorkingMemory, type WorkingMemorySnapshot } from './index.js';
+
+const AT = new Date('2026-10-24T12:00:00Z');
+
+function snap(partial: Partial<WorkingMemorySnapshot>): WorkingMemorySnapshot {
+  return { created: [], edited: [], deleted: [], read: [], searched: [], ...partial };
+}
+
+describe('WorkingMemory.brief', () => {
+  it('stays silent while the run is still short enough to see its own results', () => {
+    const m = new WorkingMemory();
+    for (let i = 0; i < 9; i++) m.observe({ kind: 'read', path: `a/${i}.ts` });
+    expect(m.brief()).toBeNull();
+  });
+
+  it('restates changes, reads with counts and searches once the run is long', () => {
+    const m = new WorkingMemory();
+    m.observe({ kind: 'searched', query: 'search_code "canvas"' });
+    m.observe({ kind: 'searched', query: 'search_code "canvas"' });
+    for (let i = 0; i < 6; i++) m.observe({ kind: 'read', path: 'web/src/App.tsx' });
+    m.observe({ kind: 'edited', path: 'web/src/Surface.tsx' });
+    m.observe({ kind: 'deleted', path: 'web/src/Old.tsx' });
+    const brief = m.brief()!;
+    expect(brief).toContain('## What this run has already established');
+    expect(brief).toContain('Changed:\n- web/src/Surface.tsx');
+    expect(brief).toContain('Deleted:\n- web/src/Old.tsx');
+    expect(brief).toContain('- web/src/App.tsx (6×)');
+    expect(brief).toContain('- search_code "canvas" (2×)');
+    // Verification is not discouraged.
+    expect(brief).toMatch(/re-running a search to verify an edit is fine/);
+  });
+
+  it('lets the host count its own activity toward the threshold', () => {
+    const m = new WorkingMemory();
+    m.observe({ kind: 'read', path: 'a.ts' });
+    expect(m.brief({ observations: 12 })).toContain('- a.ts');
+  });
+});
+
+describe('consolidate', () => {
+  it('keys by where most of the work was, ranks changed then most-read', () => {
+    const c = consolidate(
+      snap({
+        task: 'Move the   canvas',
+        read: ['web/src/a/x.ts', 'web/src/a/x.ts', 'web/src/a/y.ts'],
+        edited: ['web/src/a/z.ts', 'DONE.md'],
+      }),
+      { at: AT },
+    )!;
+    expect(c.key).toBe('codemap:web/src/a');
+    expect(c.content).toContain('mapped 2026-10-24 by a run asked: "Move the canvas"');
+    const entries = c.content.split('\n').filter((l) => l.startsWith('- '));
+    expect(entries).toEqual(['- web/src/a/z.ts (changed)', '- DONE.md (changed)', '- web/src/a/x.ts (read 2×)', '- web/src/a/y.ts']);
+  });
+
+  it('resolves absolute, MSYS and dotted paths against the root and drops noise', () => {
+    const c = consolidate(
+      snap({
+        read: [
+          'C:\\code\\repo\\web\\src\\a.ts',
+          '/c/code/repo/web/src/b.ts',
+          'web/./src//c.ts',
+          'web/node_modules/x.js',
+          'web/dist/out.js',
+          'pnpm-lock.yaml',
+          '/elsewhere/d.ts',
+          'scripts/build/gen.ts',
+        ],
+      }),
+      { at: AT, root: 'C:\\code\\repo' },
+    )!;
+    expect(c.key).toBe('codemap:web/src');
+    expect(c.content).toContain('- web/src/c.ts');
+    expect(c.content).toContain('- scripts/build/gen.ts');
+    expect(c.content).not.toMatch(/node_modules|dist|lock|elsewhere/);
+  });
+
+  it('skips a short lookup but keeps any change', () => {
+    expect(consolidate(snap({ read: ['a/b/c.ts', 'a/b/d.ts'] }))).toBeNull();
+    expect(consolidate(snap({ edited: ['api/src/r/x.ts'] }))?.key).toBe('codemap:api/src/r');
+  });
+});
+
+describe('mergeConsolidated', () => {
+  const prior = consolidate(snap({ read: ['w/s/a.ts', 'w/s/b.ts'], edited: ['w/s/c.ts'] }), { at: AT })!;
+
+  it('adds a small run to the area map, restating the earlier run\'s edits', () => {
+    const next = consolidate(snap({ task: 'fix d', edited: ['w/s/d.ts'] }), { at: AT })!;
+    const merged = mergeConsolidated(next.key, prior.content, next.content);
+    expect(merged).toContain('asked: "fix d"');
+    const entries = merged.split('\n').filter((l) => l.startsWith('- '));
+    expect(entries).toEqual(['- w/s/d.ts (changed)', '- w/s/c.ts (changed earlier)', '- w/s/a.ts', '- w/s/b.ts']);
+  });
+
+  it('removes a file this run deleted and never stores the deletion line', () => {
+    const next = consolidate(snap({ deleted: ['w/s/a.ts'], edited: ['w/s/e.ts'] }), { at: AT })!;
+    const merged = mergeConsolidated(next.key, prior.content, next.content);
+    expect(merged).not.toContain('w/s/a.ts');
+    expect(merged).not.toContain('(deleted)');
+    expect(mergeConsolidated(next.key, null, next.content)).not.toContain('(deleted)');
+  });
+
+  it('caps the map and says how many more', () => {
+    const big = consolidate(snap({ read: Array.from({ length: 12 }, (_, i) => `w/s/f${i}.ts`) }), { at: AT })!;
+    const next = consolidate(snap({ edited: ['w/s/new.ts'] }), { at: AT })!;
+    const merged = mergeConsolidated(next.key, big.content, next.content);
+    expect(merged.split('\n').filter((l) => l.startsWith('- '))).toHaveLength(12);
+    expect(merged).toContain('(+1 more file(s) touched)');
+  });
+
+  it('leaves every other key as sent', () => {
+    expect(mergeConsolidated('learned:x', 'old', 'new')).toBe('new');
+  });
+});

package/src/working/workingMemory.ts

@@ -0,0 +1,103 @@
+/**
+ * Short-term memory for one run: what it has read, searched and changed so far.
+ *
+ * ## Why the brief exists
+ *
+ * A model's reasoning is stripped from the transcript it reads next (models copy
+ * reasoning markup instead of calling tools), and a bounded working window compacts old
+ * tool results away. So by turn forty a run cannot see what it concluded at turn ten,
+ * and re-derives the whole architecture in every turn's reasoning — measured: 8–10k
+ * completion tokens a turn for two tool calls each, the same files re-read a dozen
+ * times. {@link WorkingMemory.brief} is the run's own record, handed to EVERY turn on
+ * that request only (never into the transcript, so it neither grows history nor breaks
+ * prompt caching), so the model reasons from "here is what I have" instead of from
+ * scratch.
+ *
+ * Record SUCCESSFUL observations only: a memory claiming a file was written when the
+ * write failed grounds every later turn — and run — on a lie.
+ */
+
+import { rankByCount } from './rank.js';
+import type { Observation, WorkingMemorySnapshot } from './types.js';
+
+/**
+ * Below this many observations the run's own results are still in its window, so a
+ * restatement only costs tokens. Past it, compaction starts dropping them.
+ */
+const BRIEF_MIN_OBSERVATIONS = 10;
+const BRIEF_MAX_FILES = 25;
+const BRIEF_MAX_SEARCHES = 15;
+
+export class WorkingMemory {
+  private task: string | undefined;
+  private readonly created: string[] = [];
+  private readonly edited: string[] = [];
+  private readonly deleted: string[] = [];
+  private readonly read: string[] = [];
+  private readonly searched: string[] = [];
+  private observations = 0;
+
+  /** What the run was asked — the consolidation names it, so a map is a lesson, not a list. */
+  setTask(task: string): void {
+    const asked = task.replace(/\s+/g, ' ').trim();
+    if (asked) this.task = asked;
+  }
+
+  observe(o: Observation): void {
+    this.observations++;
+    if (o.kind === 'searched') {
+      if (o.query.trim()) this.searched.push(o.query.trim());
+      return;
+    }
+    const p = o.path.trim();
+    if (!p) return;
+    this[o.kind].push(p);
+  }
+
+  /** Observations recorded so far (searches and file events alike). */
+  get size(): number {
+    return this.observations;
+  }
+
+  get snapshot(): WorkingMemorySnapshot {
+    return {
+      ...(this.task ? { task: this.task } : {}),
+      created: this.created,
+      edited: this.edited,
+      deleted: this.deleted,
+      read: this.read,
+      searched: this.searched,
+    };
+  }
+
+  /**
+   * What this run has ALREADY established, to put in front of its next turn — or `null`
+   * until it has done enough for a restatement to be worth its tokens. `observations`
+   * lets a host count its own activity (every tool call, not only memory-relevant ones).
+   * Hosts deliver it inside the per-request volatile tail (`/handoff` `volatileTail`), so
+   * it never becomes the cached prefix nor "the latest user directive".
+   */
+  brief(opts: { observations?: number } = {}): string | null {
+    if ((opts.observations ?? this.observations) < BRIEF_MIN_OBSERVATIONS) return null;
+    const changed = [...new Set([...this.created, ...this.edited])];
+    const changedSet = new Set(changed);
+    const deleted = [...new Set(this.deleted)];
+    const reads = rankByCount(this.read).filter(([p]) => !changedSet.has(p));
+    const searches = rankByCount(this.searched);
+    if (changed.length === 0 && deleted.length === 0 && reads.length === 0 && searches.length === 0) return null;
+    const lines = [
+      '## What this run has already established',
+      'Your own record so far, kept by the runtime — not a new request. Build on it instead of re-deriving it: earlier results may have been compressed out of your context, but what you concluded from them still holds. Re-read a file only when it may have changed since (a command rewrote it) or you need a part you have not seen; re-running a search to verify an edit is fine. If you already know where the change goes, make it.',
+    ];
+    if (changed.length) lines.push('', 'Changed:', ...changed.slice(0, BRIEF_MAX_FILES).map((p) => `- ${p}`));
+    if (deleted.length) lines.push('', 'Deleted:', ...deleted.slice(0, BRIEF_MAX_FILES).map((p) => `- ${p}`));
+    if (reads.length) {
+      lines.push('', 'Read:', ...reads.slice(0, BRIEF_MAX_FILES).map(([p, n]) => `- ${p}${n > 1 ? ` (${n}×)` : ''}`));
+      if (reads.length > BRIEF_MAX_FILES) lines.push(`- … ${reads.length - BRIEF_MAX_FILES} more`);
+    }
+    if (searches.length) {
+      lines.push('', 'Searched:', ...searches.slice(0, BRIEF_MAX_SEARCHES).map(([s, n]) => `- ${s}${n > 1 ? ` (${n}×)` : ''}`));
+    }
+    return lines.join('\n');
+  }
+}