create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/lib/background-llm.js

@@ -14,18 +14,60 @@ const MODEL_TIER_ENV = {
   quality: 'WALLE_MODEL_QUALITY',
 };
 
-function defaultClientModule() {
-  return require(path.resolve(__dirname, '..', '..', 'wall-e', 'llm', 'client'));
+// The starred default provider/model live in Wall-E's brain (set from the AI
+// Providers page) and are served by GET /api/wall-e/status. CTM's process env
+// (WALLE_PROVIDER/WALLE_MODEL from the launchd plist) goes stale the moment the
+// user re-stars a provider, so background calls must ask Wall-E first and only
+// fall back to env when Wall-E is unreachable. Cached briefly to keep the
+// per-call overhead at one HTTP roundtrip per TTL, with a shorter negative TTL
+// so a Wall-E restart doesn't pin us to env for long.
+const WALLE_DEFAULTS_TTL_MS = 30000;
+const WALLE_DEFAULTS_NEGATIVE_TTL_MS = 5000;
+let _walleDefaultsCache = null; // { at, value: {provider, model} | null }
+
+function _resetWalleDefaultsCache() {
+  _walleDefaultsCache = null;
 }
 
-function defaultBrain() {
+async function fetchWalleStatusDefaults(env) {
+  const port = Number(env?.WALLE_PORT) || 3457;
+  const response = await fetch(`http://127.0.0.1:${port}/api/wall-e/status`, {
+    signal: AbortSignal.timeout(1500),
+  });
+  if (!response.ok) throw new Error(`Wall-E status returned ${response.status}`);
+  const json = await response.json();
+  return json?.data || json || {};
+}
+
+async function getWalleDefaultSelection(options = {}) {
+  const env = options.env || process.env;
+  if (String(env.CTM_BACKGROUND_LLM_WALLE_DEFAULTS || '').trim() === '0') return null;
+  const now = Date.now();
+  if (_walleDefaultsCache) {
+    const ttl = _walleDefaultsCache.value ? WALLE_DEFAULTS_TTL_MS : WALLE_DEFAULTS_NEGATIVE_TTL_MS;
+    if (now - _walleDefaultsCache.at < ttl) return _walleDefaultsCache.value;
+  }
+  let value = null;
   try {
-    const brain = require(path.resolve(__dirname, '..', '..', 'wall-e', 'brain'));
-    try { brain.getDb(); } catch { brain.initDb(); }
-    return brain;
+    const fetchStatus = options.fetchWalleStatus || fetchWalleStatusDefaults;
+    const status = await fetchStatus(env);
+    const provider = sanitizeSetupProviderType(status?.walle_provider || '');
+    if (provider) {
+      value = { provider, model: typeof status?.walle_model === 'string' ? status.walle_model : '' };
+    }
   } catch {
-    return null;
+    value = null;
   }
+  _walleDefaultsCache = { at: now, value };
+  return value;
+}
+
+function defaultClientModule() {
+  return require(path.resolve(__dirname, '..', '..', 'wall-e', 'llm', 'client'));
+}
+
+function defaultBrain() {
+  return null;
 }
 
 function getBrainKv(brain, key) {
@@ -112,10 +154,14 @@ function resolveBackgroundLlmSelection(options = {}) {
       || 'anthropic'
   ) || 'anthropic';
   const runtime = providerRuntimeState({ brain, env, provider });
+  // options.defaultModel is the starred default model from Wall-E status — the
+  // live value of the brain's walle_model KV, so it slots in at that priority,
+  // ahead of the potentially stale env.WALLE_MODEL.
   const requestedModel = options.model
     || selectTierModel(options.modelTier, provider, { brain, env, clientModule })
     || getBrainKv(brain, 'walle_model_' + provider)
     || getBrainKv(brain, 'walle_model')
+    || options.defaultModel
     || env.WALLE_MODEL
     || '';
   const model = clientModule.resolveCompatibleModel
@@ -182,15 +228,50 @@ function extractBackgroundLlmText(response) {
   return '';
 }
 
+// Failure classes (wall-e/llm/provider-error.js) that mean "this provider can't
+// serve background work right now" — worth one hop to the local fallback. This
+// deliberately includes quota_exceeded and provider_rejected (a depleted
+// account, e.g. DeepSeek "402 Insufficient Balance", classifies as the former;
+// other 4xx rejections as the latter) — background work is best-effort, so any
+// provider-side refusal is better served locally than dropped.
+const FALLBACK_ELIGIBLE_CLASSES = new Set([
+  'quota_exceeded', 'auth_error', 'rate_limited', 'provider_unavailable',
+  'network', 'timeout', 'provider_rejected',
+]);
+
+function classifyBackgroundLlmError(err, options = {}) {
+  if (err?.reason === 'no_provider_credentials') return 'auth_error';
+  try {
+    const classify = options.classifyError
+      || require(path.resolve(__dirname, '..', '..', 'wall-e', 'llm', 'provider-error')).classifyProviderError;
+    return classify(err)?.type || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function backgroundLlmFallbackProvider(env) {
+  const raw = String(env?.CTM_BACKGROUND_LLM_FALLBACK_PROVIDER ?? 'ollama').trim().toLowerCase();
+  if (!raw || raw === '0' || raw === 'none' || raw === 'off') return '';
+  return sanitizeSetupProviderType(raw);
+}
+
+let _lastFallbackLogAt = 0;
+
 async function callBackgroundLlm(prompt, options = {}) {
   const clientModule = options.clientModule || defaultClientModule();
-  const selection = resolveBackgroundLlmSelection({ ...options, clientModule });
-  const createClient = options.createClient || clientModule.createClient;
-  const client = createClient(selection.clientType, selection.config);
-  const timeoutMs = options.timeoutMs || 60000;
-  const signal = options.signal || AbortSignal.timeout(timeoutMs);
+  const env = options.env || process.env;
 
-  try {
+  // Respect the starred default from the AI Providers page (Wall-E brain) over
+  // the process env, which only reflects the launchd plist at boot.
+  let walleDefaults = null;
+  if (!options.provider) walleDefaults = await getWalleDefaultSelection(options);
+
+  const attempt = async (selection) => {
+    const createClient = options.createClient || clientModule.createClient;
+    const client = createClient(selection.clientType, selection.config);
+    const timeoutMs = options.timeoutMs || 60000;
+    const signal = options.signal || AbortSignal.timeout(timeoutMs);
     const response = await client.chat({
       model: selection.model || undefined,
       system: options.system,
@@ -209,17 +290,63 @@ async function callBackgroundLlm(prompt, options = {}) {
       requestedModel: selection.requestedModel,
       modelAdjusted: selection.modelAdjusted,
     };
+  };
+
+  const resolveOptions = {
+    ...options,
+    clientModule,
+    provider: options.provider || walleDefaults?.provider || undefined,
+    defaultModel: options.defaultModel
+      || (walleDefaults?.provider && !options.provider ? walleDefaults.model : ''),
+  };
+
+  let selection = null;
+  let primaryError = null;
+  try {
+    selection = resolveBackgroundLlmSelection(resolveOptions);
+    return await attempt(selection);
   } catch (err) {
-    err.provider = err.provider || selection.provider;
-    err.model = err.model || selection.model || selection.requestedModel || '';
-    err.clientType = err.clientType || selection.clientType;
-    throw err;
+    primaryError = err;
+  }
+
+  const failedProvider = selection?.provider || primaryError.provider || resolveOptions.provider || '';
+  primaryError.provider = primaryError.provider || failedProvider;
+  primaryError.model = primaryError.model || selection?.model || selection?.requestedModel || '';
+  primaryError.clientType = primaryError.clientType || selection?.clientType || '';
+
+  // One hop to the local fallback provider (free, no surprise spend) when the
+  // configured provider can't serve — never on caller-initiated aborts.
+  const fallbackProvider = backgroundLlmFallbackProvider(env);
+  const callerAborted = !!(options.signal && options.signal.aborted);
+  if (!fallbackProvider || fallbackProvider === failedProvider || callerAborted) throw primaryError;
+  const errorClass = classifyBackgroundLlmError(primaryError, options);
+  if (!FALLBACK_ELIGIBLE_CLASSES.has(errorClass)) throw primaryError;
+
+  try {
+    const fallbackSelection = resolveBackgroundLlmSelection({
+      ...resolveOptions,
+      provider: fallbackProvider,
+      model: undefined, // primary's model hints don't apply to the fallback
+      defaultModel: walleDefaults?.provider === fallbackProvider ? walleDefaults.model : '',
+    });
+    const result = await attempt(fallbackSelection);
+    const now = Date.now();
+    if (now - _lastFallbackLogAt > 60000) {
+      _lastFallbackLogAt = now;
+      console.warn(`[background-llm] ${failedProvider} failed (${errorClass}: ${String(primaryError.message || '').slice(0, 120)}); served by fallback provider ${fallbackProvider}`);
+    }
+    return { ...result, fallbackFrom: failedProvider, fallbackReason: errorClass };
+  } catch (fallbackErr) {
+    primaryError.fallbackError = String(fallbackErr?.message || fallbackErr || '');
+    throw primaryError;
   }
 }
 
 module.exports = {
   callBackgroundLlm,
   extractBackgroundLlmText,
+  getWalleDefaultSelection,
   providerRuntimeState,
   resolveBackgroundLlmSelection,
+  _resetWalleDefaultsCache,
 };

package/template/claude-task-manager/lib/branch-inventory.js

@@ -0,0 +1,212 @@
+'use strict';
+
+// Branch + worktree inventory: classify every local branch and worktree against
+// the set of refs that any CTM session ever touched (live sessions, startup_tasks,
+// agent_sessions). A ref is "orphaned" when NO session — live or in the DB — ever
+// referenced it. Cleanup safety is conservative: only merged orphans are auto-safe.
+//
+// `classifyInventory` is PURE (no git, no DB) so it is fully unit-testable; the
+// caller supplies git facts (branches/worktrees/mergedSet) and the linked-ref set.
+// `gatherGitFacts` is the thin async git layer.
+
+function normalizeBranch(value) {
+  return String(value || '').trim().replace(/^refs\/heads\//, '');
+}
+
+function isMainBranch(ref) {
+  const b = normalizeBranch(ref);
+  return b === 'main' || b === 'master';
+}
+
+// CTM-internal refs that should never be swept by the bulk "Clean orphaned (safe)"
+// action even when merged + session-less: auto-snapshot/sync branches CTM creates
+// (`ctm/pre-sync/*`) and underscore-prefixed bookkeeping refs (`_refs/...`,
+// `_remote_main`). They still classify as orphaned (visible) — just not auto-safe.
+function isInternalRef(ref) {
+  const b = normalizeBranch(ref);
+  if (!b) return false;
+  return b.startsWith('_') || b.startsWith('ctm/pre-sync/');
+}
+
+// Normalize a path for set membership compares. Callers should pass realpath-
+// resolved paths when possible; this only strips trailing separators.
+function normalizePathKey(p) {
+  const s = String(p || '').trim();
+  if (!s) return '';
+  return s.replace(/[\\/]+$/, '');
+}
+
+function ageDaysFrom(iso, now) {
+  if (!iso) return null;
+  const t = new Date(iso).getTime();
+  if (!Number.isFinite(t)) return null;
+  return Math.max(0, Math.floor((now - t) / 86400000));
+}
+
+/**
+ * @param {object} input
+ * @param {Array<{ref,head,committerDate}>} input.branches  all local branches
+ * @param {Array<object>} input.worktrees                   rich worktrees (live)
+ * @param {Set<string>} input.mergedSet                     branch names merged into main
+ * @param {object} input.linked  { branches:[{ref,source,sessionId,label,status}],
+ *                                  worktreePaths:[{path,source,sessionId,label,status}] }
+ * @param {Set<string>} input.liveBranches        branch names used by live sessions now
+ * @param {Set<string>} input.liveWorktreePaths   worktree paths used by live sessions now
+ * @param {number} input.now                       ms epoch (caller-supplied; deterministic)
+ */
+function classifyInventory(input = {}) {
+  const {
+    branches = [],
+    worktrees = [],
+    mergedSet = new Set(),
+    linked = {},
+    liveBranches = new Set(),
+    liveWorktreePaths = new Set(),
+    now = 0,
+  } = input;
+
+  // Index the linked-ref set.
+  const linkedBranch = new Map(); // ref -> {source, sessionId, label, status}
+  for (const b of (linked.branches || [])) {
+    const ref = normalizeBranch(b.ref);
+    if (ref && !linkedBranch.has(ref)) linkedBranch.set(ref, b);
+  }
+  const linkedWtByPath = new Map();
+  for (const w of (linked.worktreePaths || [])) {
+    const key = normalizePathKey(w.path);
+    if (key && !linkedWtByPath.has(key)) linkedWtByPath.set(key, w);
+  }
+  const liveBranchSet = new Set([...liveBranches].map(normalizeBranch).filter(Boolean));
+  const liveWtSet = new Set([...liveWorktreePaths].map(normalizePathKey).filter(Boolean));
+
+  // Live worktree truth: branch -> worktree.
+  const wtByBranch = new Map();
+  for (const wt of worktrees) {
+    const ref = normalizeBranch(wt && wt.branch);
+    if (ref) wtByBranch.set(ref, wt);
+  }
+
+  function linkInfoForBranch(ref, wtPathKey) {
+    const hasLive = liveBranchSet.has(ref) || (!!wtPathKey && liveWtSet.has(wtPathKey));
+    const rec = linkedBranch.get(ref)
+      || (wtPathKey ? linkedWtByPath.get(wtPathKey) : null)
+      || null;
+    const isLinked = hasLive || !!rec;
+    let source = '';
+    if (hasLive) source = 'live_session';
+    else if (rec) source = rec.source || 'session';
+    return {
+      linked: isLinked,
+      hasLiveSession: hasLive,
+      linkedSource: source,
+      sessionId: rec ? (rec.sessionId || '') : '',
+      sessionLabel: rec ? (rec.label || '') : '',
+    };
+  }
+
+  // ---- Classify worktrees (decorate, don't replace existing rich fields) ----
+  const classifiedWorktrees = worktrees.map(wt => {
+    const ref = normalizeBranch(wt && wt.branch);
+    const wtPathKey = normalizePathKey(wt && wt.path);
+    const info = linkInfoForBranch(ref, wtPathKey);
+    const isMain = !!(wt && (wt.isMain === true || isMainBranch(ref)));
+    const merged = ref ? mergedSet.has(ref) : false;
+    const isGhost = !!(wt && wt.isGhost);
+    const isOrphan = !isMain && !info.linked && !isGhost;
+    const dirty = Number((wt && wt.dirtyFiles) || 0);
+    const internal = isInternalRef(ref);
+    return {
+      ...wt,
+      orphan: isOrphan,
+      orphanMerged: merged,
+      internal,
+      linked: info.linked,
+      hasLiveSession: info.hasLiveSession,
+      linkedSource: info.linkedSource,
+      orphanSessionId: info.sessionId,
+      orphanSessionLabel: info.sessionLabel,
+      safeToClean: isOrphan && merged && dirty === 0 && !internal,
+    };
+  });
+
+  // ---- Classify branches (all local branches, incl. those with worktrees) ----
+  const classifiedBranches = branches.map(b => {
+    const ref = normalizeBranch(b.ref);
+    const wt = wtByBranch.get(ref) || null;
+    const wtPathKey = wt ? normalizePathKey(wt.path) : '';
+    const info = linkInfoForBranch(ref, wtPathKey);
+    const isMain = isMainBranch(ref);
+    const merged = mergedSet.has(ref);
+    const hasWorktree = !!wt;
+    const isOrphan = !isMain && !info.linked;
+    const internal = isInternalRef(ref);
+    return {
+      ref,
+      head: b.head || '',
+      ageDays: ageDaysFrom(b.committerDate, now),
+      committerDate: b.committerDate || '',
+      hasWorktree,
+      worktreePath: wt ? wt.path : '',
+      merged,
+      isMain,
+      internal,
+      linked: info.linked,
+      hasLiveSession: info.hasLiveSession,
+      linkedSource: info.linkedSource,
+      sessionId: info.sessionId,
+      sessionLabel: info.sessionLabel,
+      isOrphan,
+      // Bare-branch deletion is auto-safe only when merged + orphaned + no
+      // worktree, and not a CTM-internal snapshot/bookkeeping ref.
+      safeToClean: isOrphan && merged && !hasWorktree && !internal,
+    };
+  });
+
+  const orphanWorktreeRefs = new Set(
+    classifiedWorktrees.filter(w => w.orphan && w.branch).map(w => normalizeBranch(w.branch))
+  );
+  const counts = {
+    totalBranches: classifiedBranches.length,
+    bareBranches: classifiedBranches.filter(b => !b.hasWorktree && !b.isMain).length,
+    orphanBranches: classifiedBranches.filter(b => b.isOrphan).length,
+    safeBranches: classifiedBranches.filter(b => b.safeToClean).length,
+    orphanWorktrees: classifiedWorktrees.filter(w => w.orphan).length,
+    safeWorktrees: classifiedWorktrees.filter(w => w.safeToClean).length,
+  };
+  // orphanTotal counts distinct refs (a branch + its worktree are one thing).
+  counts.orphanTotal = counts.orphanWorktrees
+    + classifiedBranches.filter(b => b.isOrphan && !orphanWorktreeRefs.has(b.ref)).length;
+  counts.safeTotal = counts.safeBranches + counts.safeWorktrees;
+
+  return { branches: classifiedBranches, worktrees: classifiedWorktrees, counts };
+}
+
+/**
+ * Gather raw git facts needed for classification. `git` is git-utils' `git(cwd,args)`.
+ * Returns { branches:[{ref,head,committerDate}], mergedSet:Set }.
+ */
+async function gatherGitFacts(cwd, git, mainBranch = 'main') {
+  const SEP = String.fromCharCode(31); // unit separator (iso8601 dates contain spaces)
+  const fmt = `%(refname:short)${SEP}%(objectname:short)${SEP}%(committerdate:iso8601)`;
+  const [refsOut, mergedOut] = await Promise.all([
+    git(cwd, ['for-each-ref', `--format=${fmt}`, 'refs/heads']).catch(() => ''),
+    git(cwd, ['branch', '--merged', mainBranch, '--format=%(refname:short)']).catch(() => ''),
+  ]);
+  const branches = String(refsOut || '').split('\n').filter(Boolean).map(line => {
+    const [ref, head, committerDate] = line.split(SEP);
+    return { ref: normalizeBranch(ref), head: head || '', committerDate: committerDate || '' };
+  });
+  const mergedSet = new Set(
+    String(mergedOut || '').split('\n').map(s => normalizeBranch(s)).filter(Boolean)
+  );
+  return { branches, mergedSet };
+}
+
+module.exports = {
+  classifyInventory,
+  gatherGitFacts,
+  normalizeBranch,
+  isMainBranch,
+  isInternalRef,
+  normalizePathKey,
+};

package/template/claude-task-manager/lib/claude-desktop-sessions.js

@@ -245,10 +245,22 @@ function readCacheConversations(appDir) {
     try { stat = fs.statSync(filePath); } catch { continue; }
     if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_CACHE_FILE_SIZE) continue;
 
+    // Probe only the 4096-byte HEAD first: the Electron HTTP cache holds hundreds of files
+    // and almost none are chat conversations. Reading every file IN FULL just to test the
+    // head was ~15s of synchronous readFileSync at boot (named by the fs-census:
+    // readFileSync@claude-desktop-sessions.js — 408 full reads). Read the head via one
+    // bounded readSync, and only fall back to a full read when the marker actually matches.
     let buf;
-    try { buf = fs.readFileSync(filePath); } catch { continue; }
-    const head = buf.subarray(0, Math.min(buf.length, 4096)).toString('latin1');
-    if (!/chat_conversations/i.test(head)) continue;
+    let fd = -1;
+    try {
+      fd = fs.openSync(filePath, 'r');
+      const headLen = Math.min(stat.size, 4096);
+      const headBuf = Buffer.allocUnsafe(headLen);
+      const n = fs.readSync(fd, headBuf, 0, headLen, 0); // only inspect the bytes actually read
+      if (!/chat_conversations/i.test(headBuf.subarray(0, n).toString('latin1'))) { fs.closeSync(fd); continue; }
+      buf = fs.readFileSync(filePath); // marker present → now read the whole file
+    } catch { if (fd >= 0) { try { fs.closeSync(fd); } catch {} } continue; }
+    try { fs.closeSync(fd); } catch {}
 
     const json = extractJsonFromCacheBuffer(buf);
     if (!json) continue;

package/template/claude-task-manager/lib/coalesce-sync-frames.js

@@ -0,0 +1,151 @@
+'use strict';
+// Safe coalescing of obsolete synchronized TUI frames.
+//
+// A synchronized frame is the byte span from `\x1b[?2026h` (begin synchronized
+// update) to the matching `\x1b[?2026l` (end synchronized update). Within a
+// single output batch a TUI may emit many such frames.
+//
+// THE ONLY SAFE COALESCING RULE (provably correct, no information loss):
+//   A synchronized frame that BEGINS with a full-screen erase (`\x1b[2J`,
+//   optionally accompanied by `\x1b[3J` scrollback-erase and/or a cursor-home
+//   `\x1b[H` / `\x1b[1;1H`) WIPES the entire screen. Therefore every COMPLETE
+//   synchronized frame that PRECEDES the LAST such full-clear frame in the
+//   batch is fully superseded and can be dropped without information loss.
+//
+// Partial-update frames (no leading full clear) are NEVER dropped unless a
+// LATER full-clear supersedes them. This preserves the picker-clear /
+// styling-restore / prompt-repair behavior that "latest frame wins" would
+// destroy. Frames AFTER the last full-clear are always preserved (they paint
+// on top of the cleared screen).
+//
+// Parsing is index-scan based (no catastrophic-backtracking regex) so huge
+// batches with hundreds of frames stay cheap.
+
+const SYNC_ON = '\x1b[?2026h';
+const SYNC_OFF = '\x1b[?2026l';
+
+// Matches a leading full-screen erase region: any ordering/combination of
+// cursor-home + `\x1b[2J` (+ optional `\x1b[3J`), with optional surrounding
+// home moves. We require at least one `\x1b[2J`. Bounded, linear-time regex
+// anchored at start of the post-SYNC_ON content.
+const CURSOR_HOME_RE = /^(?:\x1b\[H|\x1b\[1;1H)/;
+const ERASE_DISPLAY_2J_RE = /^\x1b\[2J/;
+const ERASE_SCROLLBACK_3J_RE = /^\x1b\[3J/;
+
+// Returns true if `content` (the bytes immediately following `\x1b[?2026h`)
+// begins with a full-screen clear, tolerating leading/interleaved cursor-home
+// and scrollback-erase sequences around the mandatory `\x1b[2J`.
+function beginsWithFullScreenClear(content) {
+  let i = 0;
+  let saw2J = false;
+  // Consume any leading run of cursor-home / 2J / 3J sequences. We only treat
+  // the frame as a full clear if a `\x1b[2J` appears in that leading run.
+  // Allowing 3J/home before or after 2J covers `\x1b[2J\x1b[3J\x1b[H`,
+  // `\x1b[3J\x1b[2J`, `\x1b[H\x1b[2J`, etc.
+  for (;;) {
+    const rest = content.slice(i);
+    let m;
+    if ((m = ERASE_DISPLAY_2J_RE.exec(rest))) {
+      saw2J = true;
+      i += m[0].length;
+      continue;
+    }
+    if ((m = ERASE_SCROLLBACK_3J_RE.exec(rest))) {
+      i += m[0].length;
+      continue;
+    }
+    if ((m = CURSOR_HOME_RE.exec(rest))) {
+      i += m[0].length;
+      continue;
+    }
+    break;
+  }
+  return saw2J;
+}
+
+// Tokenize `batch` into ordered segments. Each segment is one of:
+//   { type: 'frame', text, fullClear }    — a COMPLETE synchronized frame
+//   { type: 'raw', text }                 — inter-frame bytes, OR a trailing
+//                                           INCOMPLETE frame (SYNC_ON with no
+//                                           following SYNC_OFF)
+function tokenize(batch) {
+  const segments = [];
+  let pos = 0;
+  const len = batch.length;
+  while (pos < len) {
+    const onIdx = batch.indexOf(SYNC_ON, pos);
+    if (onIdx === -1) {
+      // No more frames — remaining bytes are raw.
+      segments.push({ type: 'raw', text: batch.slice(pos) });
+      break;
+    }
+    // Raw bytes before this frame's SYNC_ON.
+    if (onIdx > pos) {
+      segments.push({ type: 'raw', text: batch.slice(pos, onIdx) });
+    }
+    const contentStart = onIdx + SYNC_ON.length;
+    const offIdx = batch.indexOf(SYNC_OFF, contentStart);
+    if (offIdx === -1) {
+      // Trailing INCOMPLETE frame — keep as raw, never drop.
+      segments.push({ type: 'raw', text: batch.slice(onIdx) });
+      break;
+    }
+    const frameEnd = offIdx + SYNC_OFF.length;
+    const content = batch.slice(contentStart, offIdx);
+    segments.push({
+      type: 'frame',
+      text: batch.slice(onIdx, frameEnd),
+      fullClear: beginsWithFullScreenClear(content),
+    });
+    pos = frameEnd;
+  }
+  return segments;
+}
+
+// Coalesce obsolete synchronized frames in `batch`.
+// Returns a (possibly shorter) string. Never throws; returns the original
+// batch unchanged when there is nothing safe to drop.
+function coalesceSyncFrames(batch) {
+  const input = String(batch == null ? '' : batch);
+  if (!input) return input;
+  // Cheap bail-out: need at least two SYNC_ON markers AND a full clear marker
+  // for any coalescing to be possible.
+  if (input.indexOf('\x1b[2J') === -1) return input;
+
+  const segments = tokenize(input);
+
+  // Find index of the LAST complete frame that begins with a full-screen clear.
+  let lastFullClearIdx = -1;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (seg.type === 'frame' && seg.fullClear) lastFullClearIdx = i;
+  }
+  if (lastFullClearIdx === -1) return input; // no full-clear frame → unchanged.
+
+  // Are there any COMPLETE frames before the full-clear frame to drop?
+  let droppable = 0;
+  for (let i = 0; i < lastFullClearIdx; i++) {
+    if (segments[i].type === 'frame') droppable++;
+  }
+  if (droppable === 0) return input; // nothing superseded → unchanged.
+
+  // Rebuild: drop COMPLETE frames before the last full-clear frame. Keep
+  // everything else (raw segments, the full-clear frame, and all segments
+  // after it) in place.
+  let out = '';
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (i < lastFullClearIdx && seg.type === 'frame') continue; // superseded
+    out += seg.text;
+  }
+  return out;
+}
+
+module.exports = {
+  coalesceSyncFrames,
+  // exported for unit testing of the internals
+  _tokenize: tokenize,
+  _beginsWithFullScreenClear: beginsWithFullScreenClear,
+  SYNC_ON,
+  SYNC_OFF,
+};