@seanhogg/builderforce-memory 2026.10.23 → 2026.10.25

package/src/working/consolidationMarker.test.ts

@@ -0,0 +1,95 @@
+/**
+ * src/working/consolidationMarker.test.ts
+ * Consolidation markers (moved unchanged from brain-embedded) + the auto-fold coverage rule.
+ */
+import {
+  consolidationMetadata,
+  consolidationMarkerContent,
+  isConsolidationMarker,
+  lastConsolidationIndex,
+  scopeToConsolidation,
+  CONSOLIDATION_MARKER_PREFIX,
+  consolidationMarkerOf,
+  foldKeepFromId,
+} from './consolidationMarker.js';
+
+const msg = (content: string, metadata: string | null = null) => ({ content, metadata });
+
+describe('consolidation markers', () => {
+  it('flags a message tagged in metadata', () => {
+    expect(isConsolidationMarker(msg('x', consolidationMetadata()))).toBe(true);
+    expect(isConsolidationMarker(msg('x', null))).toBe(false);
+    expect(isConsolidationMarker(msg('x', '{"feedback":"up"}'))).toBe(false);
+    expect(isConsolidationMarker(msg('x', 'not json'))).toBe(false);
+  });
+
+  it('finds the LAST marker index', () => {
+    const list = [
+      msg('a'),
+      msg('sum1', consolidationMetadata()),
+      msg('b'),
+      msg('sum2', consolidationMetadata()),
+      msg('c'),
+    ];
+    expect(lastConsolidationIndex(list)).toBe(3);
+    expect(lastConsolidationIndex([msg('a'), msg('b')])).toBe(-1);
+  });
+
+  it('scopes the seed from the last marker (inclusive)', () => {
+    const list = [msg('a'), msg('b'), msg('sum', consolidationMetadata()), msg('c')];
+    expect(scopeToConsolidation(list).map((m) => m.content)).toEqual(['sum', 'c']);
+  });
+
+  it('returns the full list unchanged when there is no marker', () => {
+    const list = [msg('a'), msg('b')];
+    expect(scopeToConsolidation(list)).toBe(list);
+  });
+
+  it('wraps a summary with the visible marker prefix', () => {
+    const content = consolidationMarkerContent('  hello  ');
+    expect(content).toBe(`${CONSOLIDATION_MARKER_PREFIX}hello`);
+  });
+});
+
+describe('auto consolidation markers (a persisted fold)', () => {
+  const row = (id: number, content: string, metadata: string | null = null) => ({ id, content, metadata });
+
+  it('keeps every message from keepFromId on, after the marker, and drops older notes', () => {
+    const list = [
+      row(1, 'old user'), row(2, 'old reply'),
+      row(3, 'superseded note', consolidationMetadata({ keepFromId: 2 })),
+      row(4, 'user turn'), row(5, 'narration'),
+      row(6, 'note', consolidationMetadata({ keepFromId: 4, folded: 12 })),
+      row(7, 'final reply'),
+    ];
+    expect(scopeToConsolidation(list).map((m) => m.content)).toEqual(['note', 'user turn', 'narration', 'final reply']);
+  });
+
+  it('reads as manual when keepFromId is gone or after the marker', () => {
+    const gone = [row(1, 'a'), row(2, 'note', consolidationMetadata({ keepFromId: 99 })), row(3, 'b')];
+    expect(scopeToConsolidation(gone).map((m) => m.content)).toEqual(['note', 'b']);
+  });
+
+  it('round-trips the auto metadata', () => {
+    expect(consolidationMarkerOf(row(1, 'x', consolidationMetadata({ keepFromId: 4, folded: 3 })))).toEqual({ consolidation: true, auto: true, keepFromId: 4, folded: 3 });
+    expect(consolidationMarkerOf(row(1, 'x', consolidationMetadata()))).toEqual({ consolidation: true });
+    expect(consolidationMarkerOf(row(1, 'x', null))).toBeNull();
+  });
+});
+
+describe('foldKeepFromId', () => {
+  const anchors = [{ index: 0, id: 10 }, { index: 1, id: 11 }, { index: 2, id: 12 }, { index: 7, id: 20 }];
+
+  it('is exact when a persisted message sits at the cut', () => {
+    expect(foldKeepFromId(anchors, 2)).toBe(12);
+  });
+
+  it('falls back to the nearest persisted message before the cut (covered twice, never lost)', () => {
+    expect(foldKeepFromId(anchors, 5)).toBe(12);
+    expect(foldKeepFromId(anchors, 30)).toBe(20);
+  });
+
+  it('is undefined with nothing persisted before the cut', () => {
+    expect(foldKeepFromId([{ index: 4, id: 1 }], 2)).toBeUndefined();
+  });
+});

package/src/working/consolidationMarker.ts

@@ -0,0 +1,115 @@
+/**
+ * Chat consolidation markers — the durable form of a compressed conversation.
+ *
+ * A long conversation is compressed into ONE summary that becomes the new base context:
+ * everything before the marker stays visible in the transcript, but the next run's model
+ * seed starts from the marker instead of the full history. The marker is a normal
+ * assistant message (so a reader SEES the summary) tagged in its metadata.
+ *
+ * Two writers:
+ *   - MANUAL — "Consolidate" / "Fork": the summary covers everything before the marker.
+ *   - AUTO — a run's working-transcript fold (`transcript.ts`), persisted so the next run
+ *     (after a reload, on another surface) starts from the note instead of summarizing the
+ *     whole history again. A fold covers only the OLDER part of the transcript; its
+ *     `keepFromId` names the first persisted message it did NOT cover, and every message
+ *     from there on stays verbatim in the seed. Nothing is in neither.
+ */
+
+/** The marker's metadata. `auto` / `keepFromId` / `folded` are set only by a run's fold. */
+export interface ConsolidationMarkerMeta {
+  consolidation: true;
+  /** Written by auto-compaction, not by a person. */
+  auto?: true;
+  /** The first persisted message the note does NOT cover (kept verbatim after the marker). */
+  keepFromId?: number;
+  /** How many transcript messages the fold newly compressed. */
+  folded?: number;
+}
+
+/** The metadata of a manual marker. */
+export const CONSOLIDATION_META: ConsolidationMarkerMeta = { consolidation: true };
+
+/** Serialized metadata for a marker message (ready to persist). Manual when no `auto`. */
+export function consolidationMetadata(auto?: { keepFromId?: number; folded?: number }): string {
+  if (!auto) return JSON.stringify(CONSOLIDATION_META);
+  const meta: ConsolidationMarkerMeta = {
+    consolidation: true,
+    auto: true,
+    ...(auto.keepFromId !== undefined ? { keepFromId: auto.keepFromId } : {}),
+    ...(auto.folded !== undefined ? { folded: auto.folded } : {}),
+  };
+  return JSON.stringify(meta);
+}
+
+/** The marker metadata a persisted message carries, or null when it is not a marker. */
+export function consolidationMarkerOf(msg: { metadata?: string | null }): ConsolidationMarkerMeta | null {
+  if (!msg.metadata) return null;
+  try {
+    const m = JSON.parse(msg.metadata) as Partial<ConsolidationMarkerMeta> | null;
+    if (m?.consolidation !== true) return null;
+    return {
+      consolidation: true,
+      ...(m.auto === true ? { auto: true as const } : {}),
+      ...(typeof m.keepFromId === 'number' && Number.isFinite(m.keepFromId) ? { keepFromId: m.keepFromId } : {}),
+      ...(typeof m.folded === 'number' && Number.isFinite(m.folded) && m.folded > 0 ? { folded: m.folded } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** True when a persisted message is a consolidation marker (by its metadata flag). */
+export function isConsolidationMarker(msg: { metadata?: string | null }): boolean {
+  return consolidationMarkerOf(msg) !== null;
+}
+
+/** The index of the LAST consolidation marker in a message list, or -1 if none. */
+export function lastConsolidationIndex(messages: ReadonlyArray<{ metadata?: string | null }>): number {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (isConsolidationMarker(messages[i]!)) return i;
+  }
+  return -1;
+}
+
+/**
+ * Trim a message list to the compressed context: the last marker, then what it does not
+ * cover. A manual marker covers everything before it (the list from the marker on). An
+ * auto marker covers up to its `keepFromId`: the marker, then every message from that id
+ * on (other markers dropped — an older note is superseded by the newer one). Unchanged
+ * when there is no marker; a `keepFromId` no longer in the list reads as manual.
+ */
+export function scopeToConsolidation<T extends { id?: number; metadata?: string | null }>(messages: T[]): T[] {
+  const idx = lastConsolidationIndex(messages);
+  if (idx < 0) return messages;
+  const marker = messages[idx]!;
+  const keepFromId = consolidationMarkerOf(marker)?.keepFromId;
+  const from = keepFromId === undefined ? -1 : messages.findIndex((m) => m.id === keepFromId);
+  if (from < 0 || from > idx) return messages.slice(idx);
+  return [marker, ...messages.slice(from).filter((m) => m !== marker && !isConsolidationMarker(m))];
+}
+
+/**
+ * Where an auto marker's verbatim part begins: given the persisted messages the run's
+ * transcript holds (`anchors`: transcript index → message id) and the index the fold now
+ * covers up to (exclusive), the id of the persisted message the next seed must keep from.
+ *
+ * Exact when a persisted message sits AT `coveredEnd` (the fold ended inside seeded
+ * history). Otherwise the nearest persisted message BEFORE it — conservative: the span
+ * between it and `coveredEnd` is then both in the note and verbatim, never in neither.
+ * Undefined when no persisted message precedes the cut (nothing to keep from).
+ */
+export function foldKeepFromId(anchors: ReadonlyArray<{ index: number; id: number }>, coveredEnd: number): number | undefined {
+  let best: { index: number; id: number } | undefined;
+  for (const a of anchors) {
+    if (a.index <= coveredEnd && (!best || a.index > best.index)) best = a;
+  }
+  return best?.id;
+}
+
+/** The visible header prefixed onto a consolidation summary so a reader recognizes it. */
+export const CONSOLIDATION_MARKER_PREFIX = '📌 **Consolidated summary** — context continues from here.\n\n';
+
+/** Wrap a raw summary as the marker's visible content (prefix + summary). */
+export function consolidationMarkerContent(summary: string): string {
+  return `${CONSOLIDATION_MARKER_PREFIX}${summary.trim()}`;
+}

package/src/working/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Working memory — the `@seanhogg/builderforce-memory/working` subpath.
+ *
+ * A run has two memories, and they do different jobs:
+ *
+ *   - SHORT-TERM: {@link WorkingMemory}, what THIS run has read, searched and changed.
+ *     Restated before every turn ({@link WorkingMemory.brief}), because a model's own
+ *     reasoning is not carried into its next turn and old tool results are compacted
+ *     out of its window — without it a long run re-derives the codebase every turn.
+ *   - LONG-TERM: {@link consolidate}, what survives the run — a map of where the code
+ *     for that area lives, keyed per area so the next run on it (any surface) opens the
+ *     right files first. {@link mergeConsolidated} is the write-side rule that makes
+ *     consolidations of one area accumulate instead of overwriting each other.
+ *
+ * The memory knows observations ("read this file", "changed that one"), never tool
+ * names — a host maps its own tool vocabulary onto {@link Observation}.
+ *
+ * And what the MODEL sees of a run each turn — the working TRANSCRIPT (`transcript.ts`):
+ * the drop-oldest window and the incremental auto-compaction fold, the ONE summarizer
+ * prompt it folds with (`summary.ts`), and the consolidation markers a fold or a
+ * "Consolidate" persists so the next run starts from the note (`consolidationMarker.ts`).
+ *
+ * Pure: no `node:*`, no I/O — runs in a Cloudflare Worker, a browser page and Node alike.
+ */
+
+export { WorkingMemory } from './workingMemory.js';
+export { consolidate, mergeConsolidated, consolidatedKey, CONSOLIDATED_KEY_PREFIX, MIN_CONSOLIDATED_FILES } from './consolidate.js';
+export { rankByCount } from './rank.js';
+export type { Observation, WorkingMemorySnapshot, ConsolidatedMemory, ConsolidateOptions } from './types.js';
+export {
+  HISTORY_WINDOW,
+  HISTORY_TOKEN_BUDGET,
+  COMPACT_TAIL_TOKEN_BUDGET,
+  COMPACT_TAIL_TURNS,
+  windowed,
+  stillInWorkingContext,
+  verbatimStart,
+  compactTailStart,
+  compactTailStartForBudget,
+  pinnedDirectiveIndex,
+  assembleCompacted,
+  transcriptTokens,
+  buildWorkingTranscript,
+} from './transcript.js';
+export type { TranscriptMessage, CompactMemo, WorkingTranscriptState, TranscriptFold } from './transcript.js';
+export { TRANSCRIPT_SUMMARY_PROMPT, TRANSCRIPT_SUMMARY_MAX_TOKENS, renderForSummary, summarizeTranscript } from './summary.js';
+export type { SummaryCompletion } from './summary.js';
+export {
+  CONSOLIDATION_META,
+  CONSOLIDATION_MARKER_PREFIX,
+  consolidationMetadata,
+  consolidationMarkerOf,
+  consolidationMarkerContent,
+  isConsolidationMarker,
+  lastConsolidationIndex,
+  scopeToConsolidation,
+  foldKeepFromId,
+} from './consolidationMarker.js';
+export type { ConsolidationMarkerMeta } from './consolidationMarker.js';

package/src/working/rank.ts

@@ -0,0 +1,10 @@
+/**
+ * Each distinct item with how often it occurs, most frequent first, ties by name — the
+ * one ranking the brief, the consolidation and its area all use (and that hosts reuse
+ * for their own renderings of a run, so a run reads the same everywhere).
+ */
+export function rankByCount(items: readonly string[]): [string, number][] {
+  const counts = new Map<string, number>();
+  for (const i of items) counts.set(i, (counts.get(i) ?? 0) + 1);
+  return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+}

package/src/working/summary.test.ts

@@ -0,0 +1,51 @@
+/**
+ * src/working/summary.test.ts
+ * The ONE transcript summarizer: what it asks, how it renders tool calls, and that a
+ * failing or empty completion reads as "no summary" (the caller falls back).
+ */
+
+import { renderForSummary, summarizeTranscript, TRANSCRIPT_SUMMARY_MAX_TOKENS, TRANSCRIPT_SUMMARY_PROMPT } from './summary.js';
+import { buildWorkingTranscript, HISTORY_TOKEN_BUDGET, type TranscriptFold, type TranscriptMessage, type WorkingTranscriptState } from './transcript.js';
+
+describe('renderForSummary', () => {
+  it('names the tools an assistant turn called', () => {
+    const text = renderForSummary([
+      { role: 'user', content: 'fix it' },
+      { role: 'assistant', content: '', tool_calls: [{ function: { name: 'read_file' } }, { function: { name: 'edit' } }] },
+      { role: 'tool', content: { ok: true } },
+    ]);
+    expect(text).toBe('user: fix it\n\nassistant [called: read_file, edit]: \n\ntool: {"ok":true}');
+  });
+});
+
+describe('summarizeTranscript', () => {
+  it('asks the shared prompt with the bounded budget and trims the answer', async () => {
+    const seen: Array<{ system: string; maxTokens: number }> = [];
+    const out = await summarizeTranscript(async (req) => { seen.push(req); return '  the note  '; }, [{ role: 'user', content: 'x' }]);
+    expect(out).toBe('the note');
+    expect(seen[0]).toMatchObject({ system: TRANSCRIPT_SUMMARY_PROMPT, maxTokens: TRANSCRIPT_SUMMARY_MAX_TOKENS });
+  });
+
+  it('is null for nothing to summarize, an empty answer, or a failure', async () => {
+    expect(await summarizeTranscript(async () => 'x', [])).toBeNull();
+    expect(await summarizeTranscript(async () => '   ', [{ role: 'user', content: 'x' }])).toBeNull();
+    expect(await summarizeTranscript(async () => { throw new Error('down'); }, [{ role: 'user', content: 'x' }])).toBeNull();
+  });
+});
+
+describe('buildWorkingTranscript fold report', () => {
+  it('reports the note and the index it covers up to', async () => {
+    const big = 'x'.repeat(HISTORY_TOKEN_BUDGET); // ~16k tokens each
+    const state: WorkingTranscriptState = {
+      transcript: Array.from({ length: 12 }, (_, i): TranscriptMessage => ({ role: i % 2 ? 'assistant' : 'user', content: big })),
+      compactMemo: null,
+    };
+    const folds: TranscriptFold[] = [];
+    const out = await buildWorkingTranscript(state, 'sys', async () => 'summary', (f) => folds.push(f));
+    expect(folds).toHaveLength(1);
+    expect(folds[0]!.droppedMessages).toBe(folds[0]!.coveredEnd);
+    expect(folds[0]!.note).toContain('summary');
+    expect(state.compactMemo).toEqual({ note: folds[0]!.note, coveredEnd: folds[0]!.coveredEnd });
+    expect(out[1]).toEqual({ role: 'assistant', content: folds[0]!.note });
+  });
+});

package/src/working/summary.ts

@@ -0,0 +1,68 @@
+/**
+ * The transcript summarizer — the ONE prompt every fold, hand-off note and chat
+ * consolidation compresses a conversation with. The model call is the host's
+ * ({@link SummaryCompletion}); this module owns what is asked and how the transcript is
+ * rendered for it, so a compaction note, a hand-off note and a "Consolidate" summary read
+ * the same everywhere.
+ */
+
+import type { TranscriptMessage } from './transcript.js';
+
+/** The summarizer's instructions. */
+export const TRANSCRIPT_SUMMARY_PROMPT =
+  'You compress an in-progress AI agent transcript into a concise MEMORY the agent keeps working from. Capture: the CURRENT outstanding instruction from the user (the most recent user message is authoritative — earlier requests it supersedes are history, not the active task), concrete facts/answers discovered, tool results that matter (ids, paths, values), decisions made, and what still remains to do. Keep every file path, symbol name and line number the remaining work depends on, with the specific facts learned from each file — the agent no longer sees those results, so what you leave out it must read again. Be information-dense; drop pleasantries. No preamble.';
+
+/**
+ * The note's output ceiling. A compaction note is a UTILITY completion: a bounded answer
+ * with no thinking. ~2.5k tokens: the note is the agent's only record of every file it
+ * folds (paths, symbols, line numbers), and 1.2k was too little to carry them.
+ */
+export const TRANSCRIPT_SUMMARY_MAX_TOKENS = 2_500;
+
+/** One no-tools, no-reasoning completion — the host's model call. Resolves the text. */
+export type SummaryCompletion = (request: {
+  system: string;
+  user: string;
+  maxTokens: number;
+  signal?: AbortSignal;
+}) => Promise<string | null | undefined>;
+
+interface NamedToolCall {
+  function?: { name?: unknown };
+}
+
+/** Render a slice of the transcript to the compact text the summarizer compresses. */
+export function renderForSummary(msgs: readonly TranscriptMessage[]): string {
+  return msgs
+    .map((m) => {
+      const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? '');
+      const calls = Array.isArray(m.tool_calls) && m.tool_calls.length > 0
+        ? ` [called: ${(m.tool_calls as NamedToolCall[]).map((t) => t.function?.name).filter((n): n is string => typeof n === 'string' && n.length > 0).join(', ')}]`
+        : '';
+      return `${m.role}${calls}: ${content}`;
+    })
+    .join('\n\n');
+}
+
+/**
+ * Compress `msgs` into a memory note. Null on any failure or an empty answer, so the
+ * caller falls back (drop-oldest, elision, "nothing to consolidate").
+ */
+export async function summarizeTranscript(
+  complete: SummaryCompletion,
+  msgs: readonly TranscriptMessage[],
+  signal?: AbortSignal,
+): Promise<string | null> {
+  if (msgs.length === 0) return null;
+  try {
+    const out = ((await complete({
+      system: TRANSCRIPT_SUMMARY_PROMPT,
+      user: renderForSummary(msgs),
+      maxTokens: TRANSCRIPT_SUMMARY_MAX_TOKENS,
+      ...(signal ? { signal } : {}),
+    })) ?? '').trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}

package/src/working/transcript.test.ts

@@ -0,0 +1,125 @@
+/**
+ * src/working/transcript.test.ts
+ * The working-transcript window and fold partitioning (moved unchanged from brain-embedded).
+ */
+import {
+  windowed,
+  compactTailStart,
+  compactTailStartForBudget,
+  verbatimStart,
+  assembleCompacted,
+  pinnedDirectiveIndex,
+  COMPACT_TAIL_TURNS,
+} from './transcript.js';
+import type { TranscriptMessage as ChatCompletionMessage } from './transcript.js';
+
+describe('windowed history (must begin with a user turn)', () => {
+  const msg = (role: ChatCompletionMessage['role'], content = 'x'): ChatCompletionMessage => ({ role, content });
+
+  it('keeps a normal short conversation intact', () => {
+    const convo = [msg('user'), msg('assistant'), msg('user'), msg('assistant')];
+    expect(windowed(convo)).toEqual(convo);
+  });
+
+  it('drops a leading orphaned tool result', () => {
+    const convo = [msg('tool'), msg('user'), msg('assistant')];
+    expect(windowed(convo)[0].role).toBe('user');
+  });
+
+  it('drops a leading assistant turn so the payload starts at a user turn (the googleai 400)', () => {
+    // After a long tool-loop slid the user turn out of the last-N slice, the
+    // window would otherwise start on an assistant tool-call turn — which Gemini
+    // rejects with INVALID_ARGUMENT.
+    const convo = [msg('assistant'), msg('tool'), msg('user'), msg('assistant'), msg('tool')];
+    expect(windowed(convo)[0].role).toBe('user');
+  });
+
+  it('anchors to the last user turn when the window has none (tool loop > window)', () => {
+    // 90 assistant/tool messages after a single user turn: the last-80 slice has
+    // no user turn, so we fall back to the most recent user turn in the full
+    // transcript rather than emit a user-less (invalid) request.
+    const convo: ChatCompletionMessage[] = [msg('user', 'go')];
+    for (let i = 0; i < 90; i++) convo.push(msg(i % 2 === 0 ? 'assistant' : 'tool'));
+    const w = windowed(convo);
+    expect(w[0].role).toBe('user');
+    expect(w[0].content).toBe('go');
+  });
+});
+
+describe('auto-compaction partitioning (summarize the middle, never orphan a tool)', () => {
+  const msg = (role: ChatCompletionMessage['role'], content = 'x'): ChatCompletionMessage => ({ role, content });
+
+  it('walks the tail forward off a leading orphaned tool result', () => {
+    // A tail that would start on a `tool` message (its assistant call is in the
+    // summarized middle) must advance past it so nothing is orphaned.
+    const convo = [msg('user'), msg('assistant'), msg('tool'), msg('assistant'), msg('user')];
+    const start = compactTailStart(convo, 3); // last 3 = [tool, assistant, user]
+    expect(convo[start].role).not.toBe('tool');
+  });
+
+  it('assembled output is [system, memo, active directive, ...tail] and never orphans a tool', () => {
+    const convo: ChatCompletionMessage[] = [msg('user', 'task')];
+    for (let i = 0; i < 30; i++) convo.push(msg(i % 2 === 0 ? 'assistant' : 'tool', `s${i}`));
+    const out = assembleCompacted('SYS', convo, 'MEMO', compactTailStart(convo, COMPACT_TAIL_TURNS));
+    expect(out[0]).toEqual({ role: 'system', content: 'SYS' });
+    // Memo first (the compressed history), THEN the active directive verbatim — not the
+    // other way round, so the model reads the directive as the current instruction.
+    expect(out[1]).toEqual({ role: 'assistant', content: 'MEMO' });
+    expect(out[2].role).toBe('user');
+    expect(out[2].content).toBe('task');
+    // The first tail message after the directive is never an orphaned tool result.
+    expect(out[3].role).not.toBe('tool');
+  });
+
+  it('re-injects the MOST RECENT user directive, not the first, when several fell out of the tail', () => {
+    // The opening request, then a superseding instruction, then a long tool loop that
+    // pushes BOTH out of the verbatim tail. The active directive is the latest one.
+    const convo: ChatCompletionMessage[] = [msg('user', 'run a self-diagnostic'), msg('assistant', 'ok')];
+    convo.push(msg('user', 'now create the gap and fix the code'));
+    for (let i = 0; i < 30; i++) convo.push(msg(i % 2 === 0 ? 'assistant' : 'tool', `s${i}`));
+    const idx = pinnedDirectiveIndex(convo, compactTailStart(convo, COMPACT_TAIL_TURNS));
+    expect(convo[idx].content).toBe('now create the gap and fix the code');
+    const out = assembleCompacted('SYS', convo, 'MEMO', COMPACT_TAIL_TURNS);
+    const directive = out[2];
+    expect(directive.role).toBe('user');
+    expect(directive.content).toBe('now create the gap and fix the code');
+    // The stale opening request is NOT re-injected verbatim (it lives only in the memo).
+    expect(out.filter((m) => m.content === 'run a self-diagnostic')).toHaveLength(0);
+  });
+
+  it('keeps EVERY message from the covered end on — nothing falls between the memo and the tail', () => {
+    // The old fold summarised "all but the last eight" on a turn count, so messages that
+    // slid out of the tail between two folds were in neither the memo nor the tail.
+    const convo: ChatCompletionMessage[] = [msg('user', 'task')];
+    for (let i = 0; i < 30; i++) convo.push(msg('assistant', `a${i}`));
+    const out = assembleCompacted('SYS', convo, 'MEMO', 5);
+    // [system, memo, the covered directive 'task', ...convo[5..]]
+    expect(out[2]).toEqual({ role: 'user', content: 'task' });
+    expect(out.slice(3)).toEqual(convo.slice(5));
+  });
+
+  it('walks the verbatim start off tool results whose call the memo folded', () => {
+    const convo = [msg('user'), msg('assistant'), msg('tool'), msg('tool'), msg('assistant')];
+    expect(verbatimStart(convo, 2)).toBe(4);
+    expect(verbatimStart(convo, 99)).toBe(convo.length);
+  });
+
+  it('sizes the compacted tail by tokens, never below the minimum tail', () => {
+    // Small messages: far more than eight fit, so far more than eight are kept verbatim.
+    const small: ChatCompletionMessage[] = [msg('user', 'task')];
+    for (let i = 0; i < 30; i++) small.push(msg('assistant', 'short'));
+    expect(small.length - compactTailStartForBudget(small, 10_000)).toBeGreaterThan(COMPACT_TAIL_TURNS);
+    // Oversized messages: the minimum tail survives however large it is.
+    const big: ChatCompletionMessage[] = [msg('user', 'task')];
+    for (let i = 0; i < 30; i++) big.push(msg('assistant', 'x'.repeat(40_000)));
+    expect(big.length - compactTailStartForBudget(big, 10_000)).toBe(COMPACT_TAIL_TURNS);
+  });
+
+  it('does not re-inject the directive when the latest user turn already lives in the tail', () => {
+    const convo = [msg('user', 'task'), msg('assistant'), msg('user', 'later')];
+    // Latest user turn ('later') is inside the tail → nothing to re-inject.
+    expect(pinnedDirectiveIndex(convo, compactTailStart(convo, COMPACT_TAIL_TURNS))).toBe(-1);
+    const out = assembleCompacted('SYS', convo, 'MEMO', COMPACT_TAIL_TURNS);
+    expect(out.filter((m) => m.content === 'later')).toHaveLength(1);
+  });
+});