@seanhogg/builderforce-memory 2026.10.25 → 2026.10.27

package/src/working/codemapAreas.ts

@@ -0,0 +1,142 @@
+/**
+ * Code-map RECALL — which `codemap:<area>` memories a run should be handed.
+ *
+ * {@link consolidate} writes one map per code area. A map only saves a search when the
+ * next run on that area is GIVEN it, so the read side lives here beside the write side,
+ * and every host (editor, cloud, on-prem) picks maps with the same rules:
+ *
+ *   - {@link areaOfPath} — the area a named file or directory belongs to. A file at the
+ *     repository root belongs to {@link CONSOLIDATED_ROOT_AREA}, the same area
+ *     {@link consolidate} files a root-only run under, so that map is reachable.
+ *   - {@link areasOfPathsIn} — the areas of the repo-relative paths a text names.
+ *   - {@link areasNamedIn} — the stored areas a request names by WORD ("fix the run
+ *     store" names `brain-embedded/src/runStore`), for a request that names no path.
+ *   - {@link consolidatedFactsFor} — the maps whose area overlaps the areas a run is
+ *     about, most specific first.
+ *
+ * Pure: no I/O.
+ */
+
+/** Key prefix every consolidated code map carries. */
+export const CONSOLIDATED_KEY_PREFIX = 'codemap:';
+/** The area of files at the repository root (`codemap:(root)`). */
+export const CONSOLIDATED_ROOT_AREA = '(root)';
+/** Maps a run is handed, at most. */
+export const MAX_RECALLED_MAPS = 6;
+
+/** Too generic to say which area a request is about: nearly every area has one. */
+const GENERIC_SEGMENTS: ReadonlySet<string> = new Set([
+  'src', 'lib', 'libs', 'app', 'apps', 'package', 'packages', 'component', 'components', 'util', 'utils',
+  'test', 'tests', 'index', 'main', 'core', 'common', 'shared', 'source', 'internal', 'client', 'clients',
+  'server', 'docs', 'scripts', 'public', 'assets',
+]);
+/** A word shorter than this matches too much to name an area. */
+const MIN_AREA_WORD = 4;
+/** Areas one request may name by word, at most. */
+const MAX_WORD_AREAS = 8;
+
+/**
+ * The area a repo-relative path belongs to: a file's directory, a directory itself (a
+ * path with no extension), and {@link CONSOLIDATED_ROOT_AREA} for a file at the root.
+ * `''` for an empty path.
+ */
+export function areaOfPath(p: string): string {
+  const norm = p.trim().replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+  if (!norm) return '';
+  if (!/\.[A-Za-z][A-Za-z0-9]{0,7}$/.test(norm)) return norm;
+  const i = norm.lastIndexOf('/');
+  return i > 0 ? norm.slice(0, i) : CONSOLIDATED_ROOT_AREA;
+}
+
+/** The area a `codemap:` key is for, or undefined for any other key. */
+export function consolidatedArea(key: string): string | undefined {
+  return key.startsWith(CONSOLIDATED_KEY_PREFIX) ? key.slice(CONSOLIDATED_KEY_PREFIX.length) : undefined;
+}
+
+/** True when `area` and `dir` are the same directory or one contains the other. */
+function overlaps(area: string, dir: string): boolean {
+  return area === dir || dir.startsWith(`${area}/`) || area.startsWith(`${dir}/`);
+}
+
+/** The `codemap:` facts whose area overlaps a named area, most specific first, capped. */
+export function consolidatedFactsFor<F extends { key: string }>(
+  facts: readonly F[],
+  areas: readonly string[],
+  max: number = MAX_RECALLED_MAPS,
+): F[] {
+  if (areas.length === 0) return [];
+  const scored: Array<{ fact: F; depth: number }> = [];
+  const seen = new Set<string>();
+  for (const fact of facts) {
+    const area = consolidatedArea(fact.key);
+    if (area === undefined || seen.has(fact.key)) continue;
+    if (!areas.some((d) => overlaps(area, d))) continue;
+    seen.add(fact.key);
+    scored.push({ fact, depth: area.split('/').length });
+  }
+  return scored.sort((a, b) => b.depth - a.depth).slice(0, max).map((s) => s.fact);
+}
+
+/** A repo-relative path token: has a `/` or a file extension, and is not absolute. */
+const PATH_TOKEN = /[A-Za-z0-9_.@()\-\\/]+/g;
+/** Paths one text may name, at most. */
+const MAX_PATH_AREAS = 24;
+
+/**
+ * The areas of the repo-relative paths a text names (`api/src/run.ts` → `api/src`,
+ * `package.json` → the root area). Absolute paths are somebody else's machine and are
+ * skipped, as are URLs.
+ */
+export function areasOfPathsIn(text: string): string[] {
+  const out: string[] = [];
+  for (const raw of text.replace(/[a-z][a-z0-9+.-]*:\/\/\S+/gi, ' ').match(PATH_TOKEN) ?? []) {
+    // A drive letter (`C:`) is not part of a token, so `C:/x/y.ts` arrives as `/x/y.ts`
+    // and is skipped as absolute below.
+    const token = raw.replace(/^[(]+|[.)]+$/g, '');
+    if (!token || /^[\\/]/.test(token) || token.split(/[\\/]/).includes('..')) continue;
+    // A bare file name needs a stem of two or more characters, so `e.g` is not a file.
+    const isPath = /[\\/]/.test(token) || /^[^.]{2,}.*\.[A-Za-z][A-Za-z0-9]{0,7}$/.test(token);
+    if (!isPath) continue;
+    const area = areaOfPath(token);
+    if (area && !out.includes(area)) out.push(area);
+    if (out.length >= MAX_PATH_AREAS) break;
+  }
+  return out;
+}
+
+/** `runStore`, `run-store`, `run_store` and `run store` all read `runstore`. */
+function squash(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/** The request's words and adjacent pairs, squashed — `context pack` also reads `contextpack`. */
+function requestTerms(text: string): Set<string> {
+  const words = text
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+  const out = new Set<string>();
+  for (let i = 0; i < words.length; i++) {
+    out.add(words[i]!);
+    if (words[i]!.endsWith('s') && words[i]!.length > MIN_AREA_WORD) out.add(words[i]!.slice(0, -1));
+    if (i + 1 < words.length) out.add(words[i]! + words[i + 1]!);
+  }
+  return out;
+}
+
+/**
+ * The stored areas a request names by word: an area matches when one of its directory
+ * names (generic ones like `src` and short ones aside) is a word, or two adjacent words,
+ * of the request. Deepest areas first, capped.
+ */
+export function areasNamedIn(text: string, areas: readonly string[]): string[] {
+  const terms = requestTerms(text);
+  if (terms.size === 0) return [];
+  const hits = [...new Set(areas)].filter((area) =>
+    area.split('/').some((seg) => {
+      const s = squash(seg);
+      return s.length >= MIN_AREA_WORD && !GENERIC_SEGMENTS.has(s) && terms.has(s);
+    }));
+  return hits.sort((a, b) => b.split('/').length - a.split('/').length).slice(0, MAX_WORD_AREAS);
+}

package/src/working/consolidate.ts

@@ -10,15 +10,21 @@
  *
  * {@link mergeConsolidated} is the WRITE-side rule a keyed store applies, so a small run
  * ADDS to an area's map instead of overwriting the twelve files an earlier one found,
- * and a file this run deleted leaves the map.
+ * and a file this run deleted leaves the map. {@link consolidatedFiles} and
+ * {@link withoutConsolidatedFiles} read the stored format back, so a store can anchor a
+ * map to its files and drop one that changed since without hiding the rest.
  */
 
+import { CONSOLIDATED_KEY_PREFIX, CONSOLIDATED_ROOT_AREA } from './codemapAreas.js';
 import { rankByCount } from './rank.js';
 import type { ConsolidateOptions, ConsolidatedMemory, WorkingMemorySnapshot } from './types.js';
 
-/** Key prefix every consolidated code map carries. */
-export const CONSOLIDATED_KEY_PREFIX = 'codemap:';
-/** Fewer distinct files than this, with nothing changed, is a lookup — not a map worth keeping. */
+/**
+ * Fewer distinct files than this — changed, deleted and read together — is a lookup,
+ * not a map worth keeping. It holds for EVERY run, a run that changed files included: a
+ * one-file fix keyed to its own directory would otherwise write (or, once merged, keep
+ * re-dating) a map that tells the next run nothing a search would not.
+ */
 export const MIN_CONSOLIDATED_FILES = 3;
 const MAX_FILES = 12;
 const MIN_AREA_SEGMENTS = 2;
@@ -77,7 +83,7 @@ function dirSegments(file: string): string[] {
  */
 function areaOf(files: readonly string[]): string {
   const placed = files.map(dirSegments).filter((d) => d.length > 0);
-  if (placed.length === 0) return '(root)';
+  if (placed.length === 0) return CONSOLIDATED_ROOT_AREA;
   const prefixes = (depth: number): [string, number][] =>
     rankByCount(placed.filter((d) => d.length >= depth).map((d) => d.slice(0, depth).join('/')));
   for (let depth = MAX_AREA_SEGMENTS; depth >= MIN_AREA_SEGMENTS; depth--) {
@@ -107,8 +113,8 @@ export function consolidate(snapshot: WorkingMemorySnapshot, opts: ConsolidateOp
   const reads = rankByCount(kept(snapshot.read)).filter(([p]) => !changedSet.has(p) && !deletedSet.has(p));
   const readCounts = new Map(reads);
   const ranked = [...changed, ...reads.map(([p]) => p)];
+  if (ranked.length + deleted.length < (opts.minFiles ?? MIN_CONSOLIDATED_FILES)) return null;
   if (ranked.length === 0 && deleted.length === 0) return null;
-  if (changed.length === 0 && deleted.length === 0 && ranked.length < MIN_CONSOLIDATED_FILES) return null;
 
   const shown = ranked.slice(0, MAX_FILES);
   const area = areaOf(ranked.length > 0 ? ranked : deleted);
@@ -179,3 +185,31 @@ export function mergeConsolidated(key: string, prior: string | null | undefined,
   const more = merged.length - shown.length;
   return [...header, ...shown, ...(more > 0 ? [`(+${more} more file(s) touched)`] : [])].join('\n');
 }
+
+/** The files a stored map lists, in order — never a `(deleted)` line. */
+export function consolidatedFiles(content: string): string[] {
+  return entriesOf(content).filter((e) => e.note !== 'deleted').map((e) => e.path);
+}
+
+/** Paths compare as the store and the filesystem do: slashes normalised, case ignored. */
+function samePathKey(p: string): string {
+  return canonical(p).toLowerCase();
+}
+
+/**
+ * The map with `paths` taken out — for a store whose files changed since the map was
+ * written: the changed file's line goes, the rest of the map stays. `null` when no file
+ * is left to list, so the caller drops the map rather than serving a bare header.
+ */
+export function withoutConsolidatedFiles(content: string, paths: Iterable<string>): string | null {
+  const drop = new Set([...paths].map(samePathKey));
+  let left = 0;
+  const lines = content.split('\n').filter((line) => {
+    const m = ENTRY.exec(line);
+    if (!m) return true;
+    if (drop.has(samePathKey(m[1]!))) return false;
+    left++;
+    return true;
+  });
+  return left > 0 ? lines.join('\n') : null;
+}

package/src/working/consolidationMarker.test.ts

@@ -65,9 +65,19 @@ describe('auto consolidation markers (a persisted fold)', () => {
     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', () => {
+  it('ignores an auto marker whose keepFromId cannot be placed (falls back, never drops)', () => {
     const gone = [row(1, 'a'), row(2, 'note', consolidationMetadata({ keepFromId: 99 })), row(3, 'b')];
-    expect(scopeToConsolidation(gone).map((m) => m.content)).toEqual(['note', 'b']);
+    expect(scopeToConsolidation(gone).map((m) => m.content)).toEqual(['a', 'b']);
+    const after = [row(1, 'a'), row(2, 'note', consolidationMetadata({ keepFromId: 3 })), row(3, 'b')];
+    expect(scopeToConsolidation(after).map((m) => m.content)).toEqual(['a', 'b']);
+  });
+
+  it('falls back to the previous marker when the newest auto marker is unplaceable', () => {
+    const list = [
+      row(1, 'old'), row(2, 'manual', consolidationMetadata()), row(3, 'kept'),
+      row(4, 'auto', consolidationMetadata({ keepFromId: 99 })), row(5, 'new'),
+    ];
+    expect(scopeToConsolidation(list).map((m) => m.content)).toEqual(['manual', 'kept', 'new']);
   });
 
   it('round-trips the auto metadata', () => {

package/src/working/consolidationMarker.ts

@@ -27,7 +27,7 @@ export interface ConsolidationMarkerMeta {
 }
 
 /** The metadata of a manual marker. */
-export const CONSOLIDATION_META: ConsolidationMarkerMeta = { consolidation: true };
+export const CONSOLIDATION_META: Readonly<ConsolidationMarkerMeta> = Object.freeze({ consolidation: true });
 
 /** Serialized metadata for a marker message (ready to persist). Manual when no `auto`. */
 export function consolidationMetadata(auto?: { keepFromId?: number; folded?: number }): string {
@@ -76,15 +76,22 @@ export function lastConsolidationIndex(messages: ReadonlyArray<{ metadata?: stri
  * 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.
+ * when there is no marker.
+ *
+ * An auto marker whose `keepFromId` cannot be placed (the row was deleted, or a merge or
+ * sync re-inserted the history under new ids) is IGNORED — the scope falls back to the
+ * marker before it, or the whole list. Reading it as manual would drop every message
+ * between `keepFromId` and the marker that the note never held; ignoring it only costs a
+ * re-summarize.
  */
 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);
+  const meta = consolidationMarkerOf(marker)!;
+  if (!meta.auto) return messages.slice(idx);
+  const from = meta.keepFromId === undefined ? -1 : messages.findIndex((m) => m.id === meta.keepFromId);
+  if (from < 0 || from > idx) return scopeToConsolidation(messages.filter((m) => m !== marker));
   return [marker, ...messages.slice(from).filter((m) => m !== marker && !isConsolidationMarker(m))];
 }
 

package/src/working/index.ts

@@ -24,26 +24,37 @@
  */
 
 export { WorkingMemory } from './workingMemory.js';
-export { consolidate, mergeConsolidated, consolidatedKey, CONSOLIDATED_KEY_PREFIX, MIN_CONSOLIDATED_FILES } from './consolidate.js';
+export {
+  consolidate,
+  mergeConsolidated,
+  consolidatedKey,
+  consolidatedFiles,
+  withoutConsolidatedFiles,
+  MIN_CONSOLIDATED_FILES,
+} from './consolidate.js';
+export {
+  CONSOLIDATED_KEY_PREFIX,
+  CONSOLIDATED_ROOT_AREA,
+  MAX_RECALLED_MAPS,
+  areaOfPath,
+  areasNamedIn,
+  areasOfPathsIn,
+  consolidatedArea,
+  consolidatedFactsFor,
+} from './codemapAreas.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 { TRANSCRIPT_SUMMARY_PROMPT, TRANSCRIPT_SUMMARY_MAX_TOKENS, TRANSCRIPT_SUMMARY_INPUT_TOKENS, renderForSummary, summaryChunks, summarizeTranscript } from './summary.js';
 export type { SummaryCompletion } from './summary.js';
 export {
   CONSOLIDATION_META,

package/src/working/summary.test.ts

@@ -4,7 +4,7 @@
  * 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 { renderForSummary, summaryChunks, 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', () => {
@@ -49,3 +49,37 @@ describe('buildWorkingTranscript fold report', () => {
     expect(out[1]).toEqual({ role: 'assistant', content: folds[0]!.note });
   });
 });
+
+describe('summarizeTranscript over a transcript longer than one call reads', () => {
+  const long = (n: number): TranscriptMessage[] =>
+    Array.from({ length: n }, (_, i) => ({ role: i % 2 ? 'assistant' : 'user', content: `turn ${i} ${'x'.repeat(400)}` }));
+
+  it('splits into consecutive chunks within the budget, losing nothing', () => {
+    const msgs = long(40);
+    const chunks = summaryChunks(msgs, 1_000);
+    expect(chunks.length).toBeGreaterThan(1);
+    expect(chunks.flat()).toEqual(msgs);
+  });
+
+  it('folds each chunk onto the note so far and returns the last note', async () => {
+    const inputs: string[] = [];
+    let call = 0;
+    const out = await summarizeTranscript(async (req) => { inputs.push(req.user); return `note ${++call}`; }, long(40), undefined, 1_000);
+    expect(call).toBeGreaterThan(1);
+    expect(out).toBe(`note ${call}`);
+    expect(inputs[0]).not.toContain('note ');
+    expect(inputs[1]!.startsWith('assistant: note 1')).toBe(true);
+  });
+
+  it('is null when any chunk fails — never a note that skipped part of the history', async () => {
+    let call = 0;
+    expect(await summarizeTranscript(async () => (++call === 2 ? '' : 'n'), long(40), undefined, 1_000)).toBeNull();
+  });
+
+  it('clips one message larger than the whole budget', async () => {
+    let seen = '';
+    await summarizeTranscript(async (req) => { seen = req.user; return 'n'; }, [{ role: 'user', content: 'y'.repeat(50_000) }], undefined, 1_000);
+    expect(seen.length).toBeLessThan(5_000);
+    expect(seen.endsWith('[…clipped]')).toBe(true);
+  });
+});

package/src/working/summary.ts

@@ -6,7 +6,7 @@
  * the same everywhere.
  */
 
-import type { TranscriptMessage } from './transcript.js';
+import { transcriptTokens, type TranscriptMessage } from './transcript.js';
 
 /** The summarizer's instructions. */
 export const TRANSCRIPT_SUMMARY_PROMPT =
@@ -19,6 +19,14 @@ export const TRANSCRIPT_SUMMARY_PROMPT =
  */
 export const TRANSCRIPT_SUMMARY_MAX_TOKENS = 2_500;
 
+/**
+ * The most transcript one summarizer call reads (~tokens). A longer input — a whole long
+ * chat on "Consolidate", a first fold over a big seeded history — is summarized in
+ * CHUNKS of this size, each folded onto the note so far, so no single call can overrun
+ * a model's window.
+ */
+export const TRANSCRIPT_SUMMARY_INPUT_TOKENS = 48_000;
+
 /** One no-tools, no-reasoning completion — the host's model call. Resolves the text. */
 export type SummaryCompletion = (request: {
   system: string;
@@ -45,24 +53,61 @@ export function renderForSummary(msgs: readonly TranscriptMessage[]): string {
 }
 
 /**
- * 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").
+ * Split a transcript into consecutive chunks of at most `budget` tokens. A single message
+ * larger than the budget is a chunk of its own (its text is clipped when rendered).
+ */
+export function summaryChunks(msgs: readonly TranscriptMessage[], budget = TRANSCRIPT_SUMMARY_INPUT_TOKENS): TranscriptMessage[][] {
+  const chunks: TranscriptMessage[][] = [];
+  let chunk: TranscriptMessage[] = [];
+  let used = 0;
+  for (const m of msgs) {
+    const cost = transcriptTokens([m]);
+    if (chunk.length > 0 && used + cost > budget) {
+      chunks.push(chunk);
+      chunk = [];
+      used = 0;
+    }
+    chunk.push(m);
+    used += cost;
+  }
+  if (chunk.length > 0) chunks.push(chunk);
+  return chunks;
+}
+
+/** ~4 characters a token: the rendered text one call may carry. */
+const clip = (text: string, budget: number) => {
+  const max = budget * 4;
+  return text.length > max ? `${text.slice(0, max)}\n[…clipped]` : text;
+};
+
+/**
+ * Compress `msgs` into a memory note — in one call, or chunk by chunk with each chunk
+ * folded onto the note so far when the transcript is longer than one call may read. 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,
+  budget = TRANSCRIPT_SUMMARY_INPUT_TOKENS,
 ): 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;
+  let note: string | null = null;
+  for (const chunk of summaryChunks(msgs, budget)) {
+    const input: TranscriptMessage[] = note ? [{ role: 'assistant', content: note } as TranscriptMessage, ...chunk] : chunk;
+    try {
+      const out: string = ((await complete({
+        system: TRANSCRIPT_SUMMARY_PROMPT,
+        user: clip(renderForSummary(input), budget),
+        maxTokens: TRANSCRIPT_SUMMARY_MAX_TOKENS,
+        ...(signal ? { signal } : {}),
+      })) ?? '').trim();
+      if (!out) return null;
+      note = out;
+    } catch {
+      return null;
+    }
   }
+  return note;
 }

package/src/working/transcript.ts

@@ -73,47 +73,78 @@ export interface WorkingTranscriptState<M extends TranscriptMessage = Transcript
 }
 
 /**
- * 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.
+ * How far the message window's front moves at a time — a quarter of
+ * {@link HISTORY_WINDOW}. See {@link windowed}.
  */
-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);
+export const HISTORY_WINDOW_DROP_CHUNK = HISTORY_WINDOW / 4;
+
+/**
+ * How far (in tokens) the token window's front moves at a time — a quarter of
+ * {@link HISTORY_TOKEN_BUDGET}, so a drop leaves the window at ~75% of the budget and
+ * the next one waits for ~16k tokens of new work. See {@link windowed}.
+ */
+export const HISTORY_TOKEN_DROP_CHUNK = HISTORY_TOKEN_BUDGET / 4;
+
+/**
+ * Where the message-count window begins: 0 while the transcript fits
+ * {@link HISTORY_WINDOW}, else the first multiple of {@link HISTORY_WINDOW_DROP_CHUNK}
+ * that brings it back under. The cut points are fixed positions in the transcript, so
+ * the front stays put while new messages arrive and jumps a whole chunk when it moves.
+ */
+function messageWindowStart(length: number): number {
+  if (length <= HISTORY_WINDOW) return 0;
+  return Math.ceil((length - HISTORY_WINDOW) / HISTORY_WINDOW_DROP_CHUNK) * HISTORY_WINDOW_DROP_CHUNK;
 }
 
 /**
- * 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.
+ * Where the token window begins: 0 while the transcript fits
+ * {@link HISTORY_TOKEN_BUDGET}, else the first cut point that brings it back under. A
+ * cut point is the message after which the transcript's running total crosses a multiple
+ * of {@link HISTORY_TOKEN_DROP_CHUNK} — counted from the transcript's own start, so a
+ * cut point never moves as the transcript grows at the end.
  */
-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;
+function tokenWindowStart(convo: readonly TranscriptMessage[]): number {
+  const sizes = convo.map(messageTokens);
+  let remaining = sizes.reduce((sum, n) => sum + n, 0);
+  if (remaining <= HISTORY_TOKEN_BUDGET) return 0;
+  let dropped = 0;
+  let nextCut = HISTORY_TOKEN_DROP_CHUNK;
+  for (let i = 0; i < convo.length; i++) {
+    dropped += sizes[i]!;
+    remaining -= sizes[i]!;
+    if (dropped < nextCut) continue;
+    while (dropped >= nextCut) nextCut += HISTORY_TOKEN_DROP_CHUNK;
+    if (remaining <= HISTORY_TOKEN_BUDGET) return i + 1;
   }
-  let trimmed = w.slice(start);
-  while (trimmed.length > 1 && trimmed[0]!.role !== 'user') trimmed = trimmed.slice(1);
-  return trimmed;
+  return convo.length;
+}
+
+/**
+ * Trim the in-memory transcript to the history window — the message-count window
+ * ({@link HISTORY_WINDOW}) and the token budget ({@link HISTORY_TOKEN_BUDGET}) — before
+ * sending it to the model.
+ *
+ * The OLDEST turns go first, in CHUNKS with hysteresis: once over, the front jumps to
+ * the next fixed cut point ({@link HISTORY_WINDOW_DROP_CHUNK} messages /
+ * {@link HISTORY_TOKEN_DROP_CHUNK} tokens), leaving room the following turns fill before
+ * it moves again. Dropping exactly to the limit slid the front by a message or two on
+ * every turn, so the request's prefix changed every turn and no provider prefix cache
+ * could hit past the system prompt.
+ *
+ * The window is then anchored at a user turn: a window starting on an `assistant`
+ * tool-call turn or an orphaned `tool` result (whose owning call fell off the front) is
+ * invalid for strict vendors — Gemini rejects a request whose conversation does not
+ * begin with a user turn (the cascade `[googleai] 400 INVALID_ARGUMENT` after a long
+ * tool loop crossed the window boundary). The most recent user turn is never dropped:
+ * correctness over the size cap, when a tool loop outgrows the window or a single turn
+ * is itself oversized.
+ */
+export function windowed<M extends TranscriptMessage>(convo: M[]): M[] {
+  const lastUser = convo.map((m) => m.role).lastIndexOf('user');
+  if (lastUser < 0) return transcriptTokens(convo) <= HISTORY_TOKEN_BUDGET ? convo.slice() : convo.slice(-1);
+  let start = Math.min(Math.max(messageWindowStart(convo.length), tokenWindowStart(convo)), lastUser);
+  while (convo[start]!.role !== 'user') start += 1;
+  return convo.slice(start);
 }
 
 /**
@@ -134,11 +165,11 @@ export function stillInWorkingContext<M extends TranscriptMessage>(state: Workin
 // ---------------------------------------------------------------------------
 // Auto-compaction — summarize the bulky MIDDLE instead of dropping it.
 //
-// `tokenBounded` keeps the request inside the window by DROPPING the oldest turns. That
+// `windowed` 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.
+// memory. Falls back to `windowed` 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
@@ -284,7 +315,7 @@ export async function buildWorkingTranscript<M extends TranscriptMessage>(
       ? 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}`;
+  const note = `Compressed memory of the earlier part of this conversation:\n${summary}`;
   state.compactMemo = { note, coveredEnd: to };
   onFolded({ droppedMessages: to - from, note, coveredEnd: to });
   return assembleCompacted(systemPrompt, convo, note, to);