@idl3/claude-control 0.4.1 → 1.1.0

package/lib/sessions.js

@@ -15,14 +15,17 @@ import { promisify } from 'node:util';
 
 import { parseTuiStatus, prettyModel } from './tui.js';
 import { parsePanePrompt } from './prompt.js';
-import { assignTranscripts, parseEtime } from './match.js';
+import { assignTranscripts, parseEtime, fingerprintScore, shouldRebind } from './match.js';
 import { pinKey } from './pins.js';
 import { readPaneRegistry, gcPaneRegistry } from './pane-registry.js';
+import { matchesProcess as codexMatchesProcess, buildTranscriptIndex as buildCodexIndex } from './codex.js';
 
 const execFile = promisify(_execFile);
 
 // Matches Claude Code's executable basename (e.g. /Users/x/.local/bin/claude).
 const CLAUDE_COMM_RE = /(^|\/)claude$/;
+// Matches Codex CLI executable basename.
+const CODEX_COMM_RE = /(^|\/)codex$/;
 
 // A pane is a Claude Code session when its process title is the Claude version
 // (e.g. "2.1.162") — shells report zsh/bash/etc. A linked transcript also counts.
@@ -35,6 +38,10 @@ const REFRESH_INTERVAL_MS = 4000;
 const CTX_POLL_INTERVAL_MS = 12000; // TUI ctx%/model capture — slower than refresh
 const THINKING_POLL_INTERVAL_MS = 2000; // bottom-5-line capture for the live "thinking" flag
 
+// Self-heal: minimum number of refresh() cycles between consecutive rebinds for
+// the same pane. Prevents rapid-fire flapping when borderline scores oscillate.
+const SELFHEAL_DEBOUNCE_CYCLES = 5;
+
 /**
  * Encode an absolute cwd the way Claude Code names its transcript project
  * directories: every '/' and '.' becomes '-'. This is derived from the cwd the
@@ -192,6 +199,7 @@ async function extractTailRecord(filePath, mtime, birthtime = null) {
     transcriptPending: false,
     pendingToolUseId: null,
     pendingQuestion: null,
+    recentText: null,
   };
 
   // Transcript-derived pending: detect an AskUserQuestion that is open in the
@@ -202,9 +210,12 @@ async function extractTailRecord(filePath, mtime, birthtime = null) {
   base.pendingToolUseId = pending.pendingToolUseId;
   base.pendingQuestion = pending.pendingQuestion;
 
-  // Walk from end collecting the newest cwd/sessionId/timestamp/model/title.
+  // Walk from end collecting the newest cwd/sessionId/timestamp/model/title,
+  // and the most recent assistant message texts for the content-fingerprint tiebreak.
   // ai-title is re-emitted throughout the file so the tail usually carries it;
   // custom-title (a user /rename) is written when renamed, so it appears late.
+  const recentSnippets = [];
+  const MAX_RECENT_SNIPPETS = 3;
   for (let i = lines.length - 1; i >= 0; i--) {
     const line = lines[i].trim();
     if (!line) continue;
@@ -221,10 +232,25 @@ async function extractTailRecord(filePath, mtime, birthtime = null) {
     if (base.aiTitle === null && rec.type === 'ai-title' && rec.aiTitle) base.aiTitle = rec.aiTitle;
     if (base.model === null && rec.type === 'assistant' && typeof rec.message?.model === 'string') base.model = rec.message.model;
     if (base.cwd === null && typeof rec.cwd === 'string' && rec.cwd) base.cwd = rec.cwd;
-    if (base.cwd && base.sessionId && base.model && (base.customTitle || base.aiTitle)) {
+    // Collect recent assistant text for content-fingerprint tiebreak. Walk
+    // text content blocks from the most recent assistant messages backwards.
+    if (recentSnippets.length < MAX_RECENT_SNIPPETS && rec.type === 'assistant') {
+      const content = rec.message?.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block?.type === 'text' && typeof block.text === 'string' && block.text.length > 0) {
+            recentSnippets.push(block.text.slice(0, 500));
+            break; // one text block per message is enough
+          }
+        }
+      }
+    }
+    if (base.cwd && base.sessionId && base.model && (base.customTitle || base.aiTitle) &&
+        recentSnippets.length >= MAX_RECENT_SNIPPETS) {
       break; // everything found
     }
   }
+  if (recentSnippets.length > 0) base.recentText = recentSnippets.join(' ');
   return base;
 }
 
@@ -314,11 +340,12 @@ export async function listRecentTranscripts({ projectsRoot, limit = 60 }) {
 
 export class SessionRegistry extends EventEmitter {
   /**
-   * @param {{ projectsRoot: string, tmux: object, debounceMs?: number }} opts
+   * @param {{ projectsRoot: string, codexSessionsRoot?: string, tmux: object, debounceMs?: number }} opts
    */
-  constructor({ projectsRoot, tmux, debounceMs = 1000 } = {}) {
+  constructor({ projectsRoot, codexSessionsRoot, tmux, debounceMs = 1000 } = {}) {
     super();
     this._projectsRoot = projectsRoot;
+    this._codexSessionsRoot = codexSessionsRoot;
     this._tmux = tmux;
     this._debounceMs = debounceMs;
 
@@ -336,12 +363,28 @@ export class SessionRegistry extends EventEmitter {
     this._thinkingMap = new Map();
     /** @type {Map<string, {pending:boolean, question:string|null}>} target -> pane-derived prompt */
     this._panePromptMap = new Map();
+    /** @type {Map<string, string>} target -> most-recent captured pane text (for fingerprint tiebreak) */
+    this._paneTextCache = new Map();
+    /** @type {number} monotonically-incrementing refresh() cycle counter */
+    this._refreshCycle = 0;
+    /** @type {Map<string, number>} target -> refresh cycle on which it was last self-healed */
+    this._healLastCycle = new Map();
     /** @type {ReturnType<setInterval>|null} */
     this._interval = null;
     /** @type {ReturnType<setInterval>|null} */
     this._ctxInterval = null;
     /** @type {ReturnType<setInterval>|null} */
     this._thinkingInterval = null;
+
+    // Re-entrancy guards: skip a tick if the previous one is still in flight.
+    // Each flag is owned exclusively by its worker; reset in finally() so a
+    // rejected shellout cannot wedge the flag permanently.
+    /** @type {boolean} */
+    this._refreshing = false;
+    /** @type {boolean} */
+    this._pollingCtx = false;
+    /** @type {boolean} */
+    this._pollingThinking = false;
   }
 
   // -------------------------------------------------------------------------
@@ -387,6 +430,17 @@ export class SessionRegistry extends EventEmitter {
    * @returns {Promise<Session[]>}
    */
   async refresh() {
+    if (this._refreshing) return;
+    this._refreshing = true;
+    try {
+      return await this._doRefresh();
+    } finally {
+      this._refreshing = false;
+    }
+  }
+
+  /** @private — the actual refresh body; called only when not already in flight. */
+  async _doRefresh() {
     const allPanes = await this._listWindows();
 
     // Grouped tmux sessions (e.g. a `_mobile` mirror of session `0`) expose the
@@ -401,14 +455,21 @@ export class SessionRegistry extends EventEmitter {
       return true;
     });
 
-    // Classify every pane by its process subtree (a `claude` descendant) and get
-    // its claude start time in one ps snapshot. Falls back to the cmd heuristic
+    // Classify every pane by its process subtree (a `claude` or `codex` descendant)
+    // and get its start time in one ps snapshot. Falls back to the cmd heuristic
     // only when ps is unavailable.
     const paneProc = await this._buildPaneProc(panes);
     const isClaudePane = (p) => {
       const info = paneProc.get(p.target);
       return info ? info.isClaude : isClaudeCmd(p.cmd);
     };
+    const paneKind = (p) => {
+      const info = paneProc.get(p.target);
+      if (info?.kind) return info.kind;
+      if (isClaudeCmd(p.cmd)) return 'claude';
+      if (codexMatchesProcess(p.cmd)) return 'codex';
+      return 'terminal';
+    };
     const claudePanes = panes.filter(isClaudePane);
 
     // The exact pane→transcript map authored by the SessionStart hook. This is
@@ -460,15 +521,108 @@ export class SessionRegistry extends EventEmitter {
         cwd: p.cwd,
         projectDir: encodeCwd(p.cwd), // scope candidates to this pane's own slug dir
         procStartMs: paneProc.get(p.target)?.startMs ?? null,
+        // Cached from the last _pollThinking() run — used by the content-fingerprint
+        // tiebreak when timing signals cannot distinguish same-cwd candidates.
+        capturedText: this._paneTextCache.get(p.target) ?? null,
       })),
       candidates,
     );
     for (const [target, rec] of pinnedByTarget) assignment.set(target, rec);
     for (const [target, rec] of hookByTarget) assignment.set(target, rec);
 
+    // ── Self-heal pass (PLE-44) ───────────────────────────────────────────────
+    // Re-verify each MATCHER-bound pane (not pinned, not registry-hooked) against
+    // all candidates to catch drift that wasn't caught at initial binding time.
+    // Registry-pinned panes are authoritative and are NEVER re-evaluated here.
+    this._refreshCycle++;
+    for (const p of autoPanes) {
+      const target = p.target;
+      const currentRec = assignment.get(target);
+      if (!currentRec) continue; // unmatched — nothing to heal
+
+      // Debounce: skip panes re-bound too recently to avoid flapping.
+      const lastHeal = this._healLastCycle.get(target) ?? -Infinity;
+      if (this._refreshCycle - lastHeal < SELFHEAL_DEBOUNCE_CYCLES) continue;
+
+      const paneText = this._paneTextCache.get(target) ?? null;
+      if (!paneText) continue; // no captured text yet — cannot score
+
+      const currentScore = fingerprintScore(paneText, currentRec.recentText ?? null);
+
+      // Find the best OTHER candidate in the same pool.
+      let bestOtherRec = null;
+      let bestOtherScore = 0;
+      for (const c of candidates) {
+        if (c.transcriptPath === currentRec.transcriptPath) continue;
+        const s = fingerprintScore(paneText, c.recentText ?? null);
+        if (s > bestOtherScore) {
+          bestOtherScore = s;
+          bestOtherRec = c;
+        }
+      }
+
+      if (!bestOtherRec) continue; // no alternative — nothing to heal to
+      if (!shouldRebind(currentScore, bestOtherScore)) continue;
+
+      // Re-bind.
+      const oldPath = currentRec.transcriptPath;
+      assignment.set(target, bestOtherRec);
+      this._healLastCycle.set(target, this._refreshCycle);
+      console.log(
+        `[pane-selfheal] re-bound ${target}: ${oldPath} (score ${currentScore}) → ` +
+        `${bestOtherRec.transcriptPath} (score ${bestOtherScore})`,
+      );
+    }
+    // ── End self-heal ─────────────────────────────────────────────────────────
+
+    // ── Codex pane → transcript matching ────────────────────────────────────
+    // Discover Codex session transcripts and match them to Codex panes.
+    // The Claude assignment above is computed first and left untouched;
+    // codex results are merged in after.
+    const codexPanes = panes.filter((p) => paneKind(p) === 'codex');
+    if (codexPanes.length > 0) {
+      const codexIndex = await buildCodexIndex({ codexSessionsRoot: this._codexSessionsRoot });
+      const codexCandidates = [];
+      for (const rec of codexIndex.byCwd.values()) {
+        codexCandidates.push({
+          transcriptPath: rec.transcriptPath,
+          cwd: rec.cwd,
+          projectDir: null, // triggers isCwdConsistent scope fallback in match.js
+          birthtimeMs: rec.mtime,
+          mtimeMs: rec.mtime,
+          lastActivityMs: rec.mtime,
+          customTitle: rec.customTitle,
+          aiTitle: rec.aiTitle,
+          recentText: null,
+          // Pass through for later session assembly
+          sessionId: rec.sessionId,
+          lastActivity: rec.lastActivity,
+          model: rec.model,
+          transcriptPending: rec.transcriptPending,
+          pendingToolUseId: rec.pendingToolUseId,
+          pendingQuestion: rec.pendingQuestion,
+          agentType: rec.agentType,
+          mtime: rec.mtime,
+        });
+      }
+      const codexPaneInputs = codexPanes.map((p) => ({
+        target: p.target,
+        windowName: p.windowName,
+        cwd: p.cwd,
+        projectDir: null,
+        procStartMs: paneProc.get(p.target)?.startMs ?? null,
+        capturedText: this._paneTextCache.get(p.target) ?? null,
+      }));
+      const codexAssignment = assignTranscripts(codexPaneInputs, codexCandidates);
+      for (const [t, rec] of codexAssignment) assignment.set(t, rec);
+    }
+    // ── End Codex matching ───────────────────────────────────────────────────
+
     const sessions = panes.map((win) => {
       const isClaude = isClaudePane(win);
-      const transcript = isClaude ? assignment.get(win.target) ?? null : null;
+      const kind = paneKind(win);
+      const hasTranscript = kind === 'claude' || kind === 'codex';
+      const transcript = hasTranscript ? assignment.get(win.target) ?? null : null;
       const isPinned = pinnedByTarget.has(win.target);
       const id = win.target;
       // Pending = subscribed-tailer pending (live modal) OR transcript-derived
@@ -505,7 +659,7 @@ export class SessionRegistry extends EventEmitter {
         pendingQuestion: transcript?.pendingQuestion ?? panePrompt?.question ?? null,
         cmd: win.cmd,
         isClaude,
-        kind: isClaude ? 'claude' : 'terminal',
+        kind,
         ccShell: !!win.ccShell, // a composer >_ sister shell pane
 
         model: ctx.model || prettyModel(transcript?.model) || null,
@@ -527,6 +681,9 @@ export class SessionRegistry extends EventEmitter {
    * cheap but we keep it off the hot path per the resource doctrine.
    */
   async _pollCtx() {
+    if (this._pollingCtx) return;
+    this._pollingCtx = true;
+    try {
     const sessions = this._sessions;
     await Promise.all(
       sessions.map(async (s) => {
@@ -544,6 +701,9 @@ export class SessionRegistry extends EventEmitter {
       }),
     );
     this._maybeEmit();
+    } finally {
+      this._pollingCtx = false;
+    }
   }
 
   /**
@@ -552,6 +712,9 @@ export class SessionRegistry extends EventEmitter {
    * model/ctx values are left to the slower _pollCtx(). Best-effort.
    */
   async _pollThinking() {
+    if (this._pollingThinking) return;
+    this._pollingThinking = true;
+    try {
     const sessions = this._sessions;
     await Promise.all(
       sessions.map(async (s) => {
@@ -564,6 +727,9 @@ export class SessionRegistry extends EventEmitter {
           const cap = await this._tmux.capturePane(s.target, 26);
           const { thinking } = parseTuiStatus(cap);
           this._thinkingMap.set(s.target, thinking);
+          // Cache raw capture text for the content-fingerprint tiebreak in
+          // the next refresh() — cheap: already captured here.
+          this._paneTextCache.set(s.target, cap);
           s.thinking = thinking;
 
           // Pane-derived question detection (Claude panes only): an on-screen
@@ -584,6 +750,9 @@ export class SessionRegistry extends EventEmitter {
       }),
     );
     this._maybeEmit();
+    } finally {
+      this._pollingThinking = false;
+    }
   }
 
   /**
@@ -741,7 +910,7 @@ export class SessionRegistry extends EventEmitter {
     }
 
     const now = Date.now();
-    // BFS from the pane shell pid for a `claude` descendant; return its start.
+    // BFS from the pane shell pid for a `claude` or `codex` descendant; return its start.
     const findClaude = (rootPid) => {
       const queue = [rootPid];
       const seen = new Set();
@@ -752,15 +921,19 @@ export class SessionRegistry extends EventEmitter {
         const meta = info.get(pid);
         if (meta && CLAUDE_COMM_RE.test(meta.comm)) {
           const sec = parseEtime(meta.etime);
-          return { isClaude: true, startMs: sec == null ? null : now - sec * 1000 };
+          return { isClaude: true, isCodex: false, kind: 'claude', startMs: sec == null ? null : now - sec * 1000 };
+        }
+        if (meta && CODEX_COMM_RE.test(meta.comm)) {
+          const sec = parseEtime(meta.etime);
+          return { isClaude: false, isCodex: true, kind: 'codex', startMs: sec == null ? null : now - sec * 1000 };
         }
         for (const c of children.get(pid) ?? []) queue.push(c);
       }
-      return { isClaude: false, startMs: null };
+      return { isClaude: false, isCodex: false, kind: null, startMs: null };
     };
 
     for (const p of allPanes) {
-      out.set(p.target, p.panePid ? findClaude(p.panePid) : { isClaude: false, startMs: null });
+      out.set(p.target, p.panePid ? findClaude(p.panePid) : { isClaude: false, isCodex: false, kind: null, startMs: null });
     }
     return out;
   }

package/lib/shell.js

@@ -105,5 +105,7 @@ export async function shellKey(sessionTarget, cwd, key) {
 export async function shellCapture(sessionTarget, cwd, lines = 200) {
   const target = await ensureSessionShell(sessionTarget, cwd);
   const n = Math.max(1, Math.min(10000, Number(lines) || 200));
-  return tmux.capturePane(target, n, true);
+  // escapes=true (keep ANSI colors), join=true (rejoin soft-wrapped lines so
+  // URLs split across narrow pane columns are reconstructed as single <a> tags).
+  return tmux.capturePane(target, n, true, true);
 }

package/lib/subagents.js

@@ -26,12 +26,13 @@ import { TranscriptTailer } from './transcript.js';
 const META_RE = /^agent-(.+)\.meta\.json$/;
 // A sub-agent whose transcript hasn't grown in this long is treated as finished,
 // even if we never saw the parent's tool_result (e.g. it predates the parent's
-// bounded message buffer). Live sub-agents append whenever the LLM produces a
-// token or tool result, but long inference calls (extended thinking, slow tools)
-// can pause writes for several minutes. 600 s (10 min) covers realistic worst-case
-// LLM pauses while still expiring stale-but-finished agents whose tool_result
-// predates the bounded parent buffer. doneByParent always wins when available.
-const RUNNING_WINDOW_MS = 600_000;
+// bounded message buffer). Live sub-agents append every few seconds (each token
+// or tool result updates the file), so a quiet file past ACTIVE_WINDOW_MS (20 s)
+// is almost certainly done. 45 s is generous enough to absorb a brief inference
+// pause without mis-classifying a still-running agent, while clearing finished
+// agents ~13× faster than the previous 600 s fallback.
+// doneByParent always wins when available (authoritative, instant).
+const RUNNING_WINDOW_MS = 45_000;
 // A file written within this window is treated as actively-running, overriding a
 // (possibly premature, e.g. background-launch-ack) doneByParent flag.
 const ACTIVE_WINDOW_MS = 20_000;

package/lib/tmux.js

@@ -325,9 +325,19 @@ export function shellQuoteName(name) {
  * session is created first and used.
  *
  * @param {{ cwd: string, name?: string }} opts
+ * @param {{ _run?: Function, _listPanes?: Function }} [_injected]
+ *   Test-only injection seam. Production callers omit this argument entirely.
+ *   - `_run(args)` replaces the internal `runTmux` call (records argv, returns
+ *     canned `{ stdout, stderr }` without shelling out).
+ *   - `_listPanes()` replaces the `listWindows` call used to detect an existing
+ *     server session (returns a canned pane array).
  * @returns {Promise<string>} target "session:windowIndex"
  */
-export async function createWindow({ cwd, name } = {}) {
+export async function createWindow({ cwd, name } = {}, { _run, _listPanes } = {}) {
+  // Allow tests to inject a stub runner; production path uses the real runTmux.
+  const runner = _run ?? runTmux;
+  const lister = _listPanes ?? listWindows;
+
   if (typeof cwd !== 'string' || !cwd) {
     throw new Error('createWindow: cwd is required');
   }
@@ -347,7 +357,7 @@ export async function createWindow({ cwd, name } = {}) {
   // callers may pass raw user text. An empty result means "let tmux auto-name".
   const safeName = sanitizeName(name);
 
-  const windows = await listWindows();
+  const windows = await lister();
 
   // No tmux server/session yet — bootstrap a detached session in the cwd. The
   // session's first window IS our target window, so no extra new-window needed.
@@ -355,10 +365,10 @@ export async function createWindow({ cwd, name } = {}) {
     const sessionName = 'claude-control';
     const args = ['new-session', '-d', '-s', sessionName, '-c', cwd];
     if (safeName) args.push('-n', safeName);
-    await runTmux(args);
+    await runner(args);
     // The fresh session opens at window index 0 (tmux's base-index may differ,
     // but the first list entry is authoritative).
-    const after = await listWindows();
+    const after = await lister();
     const win = after.find((w) => w.sessionName === sessionName);
     const target = win ? win.target : `${sessionName}:0`;
     if (!isValidTarget(target)) {
@@ -378,7 +388,7 @@ export async function createWindow({ cwd, name } = {}) {
     '-c', cwd,
   ];
   if (safeName) args.push('-n', safeName);
-  const { stdout } = await runTmux(args);
+  const { stdout } = await runner(args);
   const target = stdout.trim();
   if (!isValidTarget(target)) {
     throw new Error(`createWindow: produced invalid target: ${JSON.stringify(target)}`);
@@ -551,19 +561,28 @@ export async function sendRawKeysSequenced(target, keys, delayMs = 160) {
 /**
  * Capture the visible content of a tmux pane.
  * `-e` preserves ANSI escape sequences (server may strip before forwarding).
+ * `-J` joins soft-wrapped lines so a URL split across pane columns is
+ * reconstructed into a single logical line.
  *
  * @param {string} target
  * @param {number} [lines=40]  How many history lines above the visible area to include.
+ * @param {boolean} [escapes=false]  Pass `-e` to keep ANSI/SGR sequences.
+ * @param {boolean} [join=false]     Pass `-J` to rejoin soft-wrapped lines.
+ * @param {{ _run?: Function }} [_injected]  Test-only seam; omit in production.
  * @returns {Promise<string>}
  */
-export async function capturePane(target, lines = 40, escapes = false) {
+export async function capturePane(target, lines = 40, escapes = false, join = false, { _run } = {}) {
   assertTarget(target);
+  const runner = _run ?? runTmux;
   const args = ['capture-pane', '-t', target, '-p'];
   // `-e` keeps ANSI/SGR sequences so the client can render terminal colors. Off
   // by default: LivePane / AskModal render plain text (escapes would show as
   // garbage). The composer terminal view opts in to get a themed, colored pane.
   if (escapes) args.push('-e');
+  // `-J` rejoins soft-wrapped lines into logical lines so that a URL split
+  // across narrow pane columns is reconstructed before the client linkifies it.
+  if (join) args.push('-J');
   args.push('-S', `-${lines}`); // start N lines above the visible area
-  const { stdout } = await runTmux(args);
+  const { stdout } = await runner(args);
   return stdout;
 }

package/lib/transcribe.js

@@ -54,16 +54,13 @@ export function resolveWhisperBin() {
 }
 
 /**
- * Resolve the ggml model: WHISPER_MODEL env → preferred names in the models
- * dir → any `ggml-*.bin` there.
- * @returns {string | null}
+ * Pure model-preference resolver: given a list of filenames present on disk,
+ * return the preferred one (multilingual before .en). Exposed for testing.
+ *
+ * @param {string[]} files - basenames available (e.g. from fs.readdirSync)
+ * @returns {string | null} preferred basename, or null
  */
-export function resolveWhisperModel() {
-  const e = process.env.WHISPER_MODEL;
-  if (e && e.trim() && fs.existsSync(e.trim())) return e.trim();
-  // Prefer multilingual models (no `.en`) when present: a `.en` model can ONLY
-  // do English, so if the user dropped in a multilingual ggml they want the mix
-  // (English + Chinese + Singlish/…). English-only models are the fallback.
+export function resolveModelFromFiles(files) {
   const prefs = [
     'ggml-medium.bin',
     'ggml-small.bin',
@@ -73,16 +70,30 @@ export function resolveWhisperModel() {
     'ggml-tiny.en.bin',
   ];
   for (const m of prefs) {
-    const p = path.join(MODELS_DIR, m);
-    if (fs.existsSync(p)) return p;
+    if (files.includes(m)) return m;
   }
+  return files.find((n) => /^ggml-.*\.bin$/.test(n)) ?? null;
+}
+
+/**
+ * Resolve the ggml model: WHISPER_MODEL env → preferred names in the models
+ * dir → any `ggml-*.bin` there.
+ * @returns {string | null}
+ */
+export function resolveWhisperModel() {
+  const e = process.env.WHISPER_MODEL;
+  if (e && e.trim() && fs.existsSync(e.trim())) return e.trim();
+  // Prefer multilingual models (no `.en`) when present: a `.en` model can ONLY
+  // do English, so if the user dropped in a multilingual ggml they want the mix
+  // (English + Chinese + Singlish/…). English-only models are the fallback.
+  let files = [];
   try {
-    const found = fs.readdirSync(MODELS_DIR).find((n) => /^ggml-.*\.bin$/.test(n));
-    if (found) return path.join(MODELS_DIR, found);
+    files = fs.readdirSync(MODELS_DIR);
   } catch {
     /* dir missing */
   }
-  return null;
+  const found = resolveModelFromFiles(files);
+  return found ? path.join(MODELS_DIR, found) : null;
 }
 
 /**
@@ -124,6 +135,22 @@ function run(bin, args) {
   });
 }
 
+/**
+ * Derive the whisper-cli language flags from the resolved model path and call
+ * options. Pure function — no I/O. Exposed for testing.
+ *
+ * @param {string} modelPath  - resolved model file path (used for its basename)
+ * @param {{ lang?: string }} [opts]
+ * @param {NodeJS.ProcessEnv} [env]  - defaults to process.env
+ * @returns {{ effLang: string, translate: boolean }}
+ */
+export function buildWhisperFlags(modelPath, { lang } = {}, env = process.env) {
+  const englishOnly = /\.en\.bin$/i.test(path.basename(modelPath));
+  const effLang = lang || env.WHISPER_LANG || (englishOnly ? 'en' : 'auto');
+  const translate = !englishOnly; // → always-English output
+  return { effLang, translate };
+}
+
 /**
  * Transcribe an audio file (any ffmpeg-readable format) to text — always in
  * English. A multilingual model uses Whisper's TRANSLATE task, so Chinese,
@@ -131,13 +158,19 @@ function run(bin, args) {
  * models are already English; nothing to translate.
  *
  * @param {string} inputPath - path to the recorded audio file.
- * @param {{ lang?: string }} [opts]
+ * @param {{ lang?: string, _resolvers?: object, _run?: Function }} [opts]
  * @returns {Promise<string>}
  */
-export async function transcribe(inputPath, { lang } = {}) {
-  const ffmpeg = resolveFfmpeg();
-  const whisper = resolveWhisperBin();
-  const model = resolveWhisperModel();
+export async function transcribe(inputPath, { lang, _resolvers, _run } = {}) {
+  const resolvers = _resolvers ?? {};
+  const ffmpegFn  = resolvers.resolveFfmpeg      ?? resolveFfmpeg;
+  const whisperFn = resolvers.resolveWhisperBin  ?? resolveWhisperBin;
+  const modelFn   = resolvers.resolveWhisperModel ?? resolveWhisperModel;
+  const runFn     = _run ?? run;
+
+  const ffmpeg = ffmpegFn();
+  const whisper = whisperFn();
+  const model = modelFn();
   if (!ffmpeg) throw new Error('ffmpeg not found (brew install ffmpeg)');
   if (!whisper) throw new Error('whisper-cli not found (brew install whisper-cpp)');
   if (!model) throw new Error(`no whisper model found in ${MODELS_DIR}`);
@@ -145,22 +178,20 @@ export async function transcribe(inputPath, { lang } = {}) {
   // `.en` models do English only; multilingual models auto-detect the source then
   // translate it to English. Source language is overridable (lang / WHISPER_LANG)
   // for the rare case you want to pin detection; output stays English.
-  const englishOnly = /\.en\.bin$/i.test(path.basename(model));
-  const effLang = lang || process.env.WHISPER_LANG || (englishOnly ? 'en' : 'auto');
-  const translate = !englishOnly; // → always-English output
+  const { effLang, translate } = buildWhisperFlags(model, { lang });
 
   const wav = path.join(
     os.tmpdir(),
     `cc-stt-${Date.now()}-${process.pid}.wav`,
   );
   try {
-    await run(ffmpeg, [
+    await runFn(ffmpeg, [
       '-nostdin', '-y',
       '-i', inputPath,
       '-ar', '16000', '-ac', '1', '-c:a', 'pcm_s16le',
       '-f', 'wav', wav,
     ]);
-    const { stdout } = await run(whisper, [
+    const { stdout } = await runFn(whisper, [
       '-m', model, '-f', wav, '-np', '-nt', '-l', effLang,
       ...(translate ? ['--translate'] : []),
     ]);

package/lib/transcript.js

@@ -194,13 +194,14 @@ export function parseRecord(line) {
 export class TranscriptTailer extends EventEmitter {
   /**
    * @param {string} filePath
-   * @param {{ maxBuffer?: number, debounceMs?: number }} options
+   * @param {{ maxBuffer?: number, debounceMs?: number, parser?: Function }} options
    */
-  constructor(filePath, { maxBuffer = DEFAULT_MAX_BUFFER, debounceMs = 150 } = {}) {
+  constructor(filePath, { maxBuffer = DEFAULT_MAX_BUFFER, debounceMs = 150, parser = parseRecord } = {}) {
     super();
     this._filePath = filePath;
     this._maxBuffer = maxBuffer;
     this._debounceMs = debounceMs;
+    this._parse = parser;
 
     /** @type {import('./transcript.js').NormalizedMessage[]} */
     this._messages = [];
@@ -340,7 +341,7 @@ export class TranscriptTailer extends EventEmitter {
 
     const parsed = [];
     for (const line of lines) {
-      const msg = parseRecord(line);
+      const msg = this._parse(line);
       if (msg) {
         parsed.push(msg);
         this._trackPending(msg);
@@ -413,7 +414,7 @@ export class TranscriptTailer extends EventEmitter {
 
       const newMsgs = [];
       for (const line of complete) {
-        const msg = parseRecord(line);
+        const msg = this._parse(line);
         if (msg) {
           newMsgs.push(msg);
           this._trackPending(msg);