@idl3/claude-control 0.4.1 → 1.0.1

package/lib/sessions.js

@@ -15,7 +15,7 @@ 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';
 
@@ -35,6 +35,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 +196,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 +207,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 +229,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;
 }
 
@@ -336,12 +359,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 +426,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
@@ -460,12 +510,60 @@ 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 ─────────────────────────────────────────────────────────
+
     const sessions = panes.map((win) => {
       const isClaude = isClaudePane(win);
       const transcript = isClaude ? assignment.get(win.target) ?? null : null;
@@ -527,6 +625,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 +645,9 @@ export class SessionRegistry extends EventEmitter {
       }),
     );
     this._maybeEmit();
+    } finally {
+      this._pollingCtx = false;
+    }
   }
 
   /**
@@ -552,6 +656,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 +671,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 +694,9 @@ export class SessionRegistry extends EventEmitter {
       }),
     );
     this._maybeEmit();
+    } finally {
+      this._pollingThinking = false;
+    }
   }
 
   /**

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/ws-heartbeat.js

@@ -0,0 +1,32 @@
+/**
+ * WebSocket ping/pong heartbeat helpers.
+ *
+ * Extracted from server.js so tests can import pruneDeadClients without
+ * booting the HTTP/WS server.
+ */
+
+/**
+ * Prune dead WebSocket clients using the ping/pong aliveness flag.
+ *
+ * On every heartbeat tick the server calls this with `wss.clients`.  Any
+ * client whose `isAlive` flag is still `false` from the previous sweep is
+ * terminated (firing its existing `close` handler → existing cleanup /
+ * `maybeTeardown`).  Live clients have their flag reset to `false` and
+ * receive a ping; if they respond with a pong the `pong` handler in
+ * server.js sets `isAlive = true` before the next sweep.
+ *
+ * New connections set `isAlive = true` on creation, so they are never
+ * terminated on the very first sweep.
+ *
+ * @param {Iterable<{isAlive:boolean,terminate:()=>void,ping:()=>void}>} clients
+ */
+export function pruneDeadClients(clients) {
+  for (const ws of clients) {
+    if (ws.isAlive === false) {
+      ws.terminate();
+    } else {
+      ws.isAlive = false;
+      ws.ping();
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idl3/claude-control",
-  "version": "0.4.1",
+  "version": "1.0.1",
   "type": "module",
   "description": "Local web UI to watch and drive your Claude Code sessions running in tmux — live transcripts, reply, answer AskUserQuestion, attach files, from a browser or phone.",
   "keywords": [