@idl3/claude-control 0.4.1 → 1.1.0

package/lib/match.js

@@ -39,10 +39,11 @@ export function parseEtime(etime) {
 
 /**
  * @typedef {Object} MatchPane
- * @property {string}      target       "session:window.pane"
+ * @property {string}      target        "session:window.pane"
  * @property {string}      windowName
  * @property {string}      cwd
- * @property {number|null} procStartMs  claude process start (ms epoch), or null
+ * @property {number|null} procStartMs   claude process start (ms epoch), or null
+ * @property {string|null} [capturedText] recent visible text captured from the pane
  *
  * @typedef {Object} MatchCandidate
  * @property {string}      transcriptPath
@@ -52,8 +53,69 @@ export function parseEtime(etime) {
  * @property {number|null} lastActivityMs
  * @property {string|null} customTitle
  * @property {string|null} aiTitle
+ * @property {string|null} [recentText]   recent assistant message text from the transcript tail
  */
 
+// Minimum number of word tokens that must overlap for the content-fingerprint
+// tiebreak to fire a decision. Prevents noise from short/common words.
+const FINGERPRINT_MIN_OVERLAP = 3;
+
+// Self-heal thresholds — controls when a matcher-bound pane is re-bound to a
+// better candidate during periodic re-verification (PLE-44). Both must be
+// satisfied before a rebind fires.
+//
+//   SELFHEAL_FLOOR   — the CURRENT binding's score must be below this before
+//                      a rebind is even considered.  A clearly-good binding
+//                      (score ≥ FLOOR) is left alone even if another candidate
+//                      slightly outscores it.
+//
+//   SELFHEAL_MARGIN  — the BEST OTHER candidate's score minus the current score
+//                      must be at least this margin.  Near-ties never flip an
+//                      existing binding.  Must be larger than FINGERPRINT_MIN_OVERLAP
+//                      so the tiebreak signal alone cannot trigger a self-heal.
+export const SELFHEAL_FLOOR  = 2;   // current score must be < this
+export const SELFHEAL_MARGIN = 6;   // bestOther − current must be ≥ this
+
+/**
+ * Decide whether a matcher-bound pane should be re-bound to a different
+ * transcript during the self-heal pass.
+ *
+ * Conservative by design: both the floor AND the margin must be met before a
+ * rebind fires. A near-tie on the current binding must NEVER flip.
+ *
+ * @param {number} currentScore  fingerprintScore of the current binding
+ * @param {number} bestOtherScore fingerprintScore of the best alternative
+ * @returns {boolean}
+ */
+export function shouldRebind(currentScore, bestOtherScore) {
+  return currentScore < SELFHEAL_FLOOR && (bestOtherScore - currentScore) >= SELFHEAL_MARGIN;
+}
+
+/**
+ * Score how well a candidate's transcript text matches a pane's captured text.
+ * Returns the count of distinct word tokens present in both strings (case-folded,
+ * alpha-only, ≥4 chars). Returns 0 when either input is absent or empty.
+ *
+ * @param {string|null|undefined} paneText
+ * @param {string|null|undefined} candidateText
+ * @returns {number}
+ */
+export function fingerprintScore(paneText, candidateText) {
+  if (!paneText || !candidateText) return 0;
+  const tokenise = (s) => {
+    const tokens = new Set();
+    for (const m of s.matchAll(/[a-zA-Z]{4,}/g)) tokens.add(m[0].toLowerCase());
+    return tokens;
+  };
+  const paneTokens = tokenise(paneText);
+  if (paneTokens.size === 0) return 0;
+  let overlap = 0;
+  for (const m of candidateText.matchAll(/[a-zA-Z]{4,}/g)) {
+    if (paneTokens.has(m[0].toLowerCase())) overlap++;
+  }
+  return overlap;
+}
+
 /**
  * Assign transcripts to panes 1:1.
  *
@@ -128,6 +190,12 @@ export function assignTranscripts(panes, candidates, opts = {}) {
   // transcript is born long ago but is the most-recently-active, so it must beat
   // a freshly-BORN but stale sibling whose birth merely coincides with the
   // resume time (the old "start-time grabs the wrong transcript" bug).
+  //
+  // Content-fingerprint tiebreak (PLE-41): when timing signals still cannot
+  // distinguish candidates (procStartMs unknown + activities within RECENCY_TIE_MS),
+  // compare word-token overlap between the pane's captured text and each
+  // candidate's recent transcript text. This is a NO-OP when either side lacks
+  // text data, preserving all existing behavior.
   const prefer = (pane, c, best) => {
     const ca = activity(c);
     const ba = activity(best);
@@ -137,6 +205,14 @@ export function assignTranscripts(panes, candidates, opts = {}) {
       const bd = Math.abs(best.birthtimeMs - pane.procStartMs);
       if (cd !== bd) return cd < bd;
     }
+    // Content-fingerprint tiebreak: only fires when both candidates carry
+    // recentText and the pane has capturedText, AND the scores differ by at
+    // least FINGERPRINT_MIN_OVERLAP (avoids flipping on trivial noise).
+    if (pane.capturedText && c.recentText && best.recentText) {
+      const cs = fingerprintScore(pane.capturedText, c.recentText);
+      const bs = fingerprintScore(pane.capturedText, best.recentText);
+      if (Math.abs(cs - bs) >= FINGERPRINT_MIN_OVERLAP) return cs > bs;
+    }
     return ca > ba;
   };
 

package/lib/mlx.js

@@ -70,6 +70,18 @@ let child = null;
 let childModel = null; // model id the current child was spawned with
 let idleTimer = null;
 
+/**
+ * Test-only helper: inject a fake child process and idle timer so shutdown()
+ * can be exercised without spawning a real Python server.
+ * @param {{ kill: Function, pid: number } | null} fakeChild
+ * @param {NodeJS.Timeout | null} [fakeTimer]
+ */
+export function _setChildForTest(fakeChild, fakeTimer = null) {
+  child = fakeChild;
+  childModel = fakeChild ? 'test-model' : null;
+  idleTimer = fakeTimer;
+}
+
 function bumpIdle() {
   if (idleTimer) clearTimeout(idleTimer);
   idleTimer = setTimeout(() => shutdown(), IDLE_MS);
@@ -169,6 +181,7 @@ function spawnServer(model, port) {
     ['-m', 'mlx_lm.server', '--model', model, '--host', '127.0.0.1', '--port', String(port)],
     { stdio: ['ignore', out, out], env: { ...process.env, HOME: os.homedir() } },
   );
+  child.unref(); // don't let the sidecar pin the event loop; shutdown() is the real reap
   childModel = model;
   child.on('exit', () => { child = null; childModel = null; });
 }

package/lib/pins.js

@@ -12,6 +12,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { writeJsonAtomic } from './json-file.js';
 
 /** Stable pin key for a pane/session: windowId.paneIndex. */
 export function pinKey(windowId, paneIndex) {
@@ -33,9 +34,7 @@ export function loadPins(file) {
 export function savePins(file, pins) {
   const dir = path.dirname(file);
   fs.mkdirSync(dir, { recursive: true });
-  const tmp = `${file}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(pins, null, 2), { mode: 0o600 });
-  fs.renameSync(tmp, file);
+  writeJsonAtomic(file, pins, { mode: 0o600 });
 }
 
 /**

package/lib/push.js

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import webpush from 'web-push';
+import { writeJsonAtomic } from './json-file.js';
 
 const STORE_DIR = path.join(os.homedir(), '.claude-control');
 const VAPID_PATH = path.join(STORE_DIR, 'vapid.json');
@@ -37,7 +38,7 @@ function loadOrCreateKeys() {
   }
   const generated = webpush.generateVAPIDKeys();
   try {
-    fs.writeFileSync(VAPID_PATH, JSON.stringify(generated, null, 2), { mode: 0o600 });
+    writeJsonAtomic(VAPID_PATH, generated, { mode: 0o600 });
   } catch (err) {
     console.error('push: failed to persist VAPID keys:', err?.message || err);
   }
@@ -58,7 +59,7 @@ function loadSubscriptions() {
 function persistSubscriptions() {
   try {
     ensureStoreDir();
-    fs.writeFileSync(SUBS_PATH, JSON.stringify(subscriptions, null, 2), { mode: 0o600 });
+    writeJsonAtomic(SUBS_PATH, subscriptions, { mode: 0o600 });
   } catch (err) {
     console.error('push: failed to persist subscriptions:', err?.message || err);
   }

package/lib/resources.js

@@ -10,57 +10,90 @@
 
 import { EventEmitter } from 'node:events';
 import os from 'node:os';
-import { execSync } from 'node:child_process';
+import { execSync, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+// ── Pure parsers (no exec — exported for unit testing) ───────────────────────
+
+/**
+ * Parse `vm_stat` stdout into reclaimable bytes, or null on parse failure.
+ *
+ * Treats free + inactive + speculative + purgeable + file-backed pages as
+ * available (matches Activity Monitor / memory_pressure). Returns null if the
+ * output is structurally unparseable.
+ *
+ * @param {string} out — raw stdout from `vm_stat`
+ * @returns {number|null}
+ */
+export function parseVmStat(out) {
+  const pageSize = Number((out.match(/page size of (\d+) bytes/) || [])[1]) || 4096;
+  const pages = (label) => {
+    const m = out.match(new RegExp(`${label}:\\s+(\\d+)\\.`));
+    return m ? Number(m[1]) : 0;
+  };
+  const available =
+    pages('Pages free') +
+    pages('Pages inactive') +
+    pages('Pages speculative') +
+    pages('Pages purgeable') +
+    pages('File-backed pages');
+  // If every field is zero and there's no page-size line, treat as bad output.
+  if (available === 0 && !out.includes('Pages free')) return null;
+  return available * pageSize;
+}
 
 /**
- * Reclaimable ("available") free memory in bytes.
+ * Parse `pmset -g batt` stdout into a power-status object, or null on failure.
+ *
+ * `low` is a UI hint: ≤20% and not charging.
+ * ponytail: macOS-only via pmset; add upower/sysfs parsing if Linux is ever needed.
  *
- * `os.freemem()` on macOS counts only truly-free pages — inactive, cached
- * (file-backed), speculative and purgeable memory are all reclaimable but
- * excluded, so memUsedPct computed from it pins near ~98% even when the
- * machine is nowhere near pressure. On darwin we parse `vm_stat` and treat
- * free + inactive + speculative + purgeable + file-backed as available
- * (matching what `memory_pressure` / Activity Monitor report). Returns null
- * on non-darwin or any parse/exec failure so the caller falls back to
- * `os.freemem()`.
+ * @param {string} out — raw stdout from `pmset -g batt`
+ * @returns {{ hasBattery: boolean, percent?: number|null, charging?: boolean, low?: boolean }|null}
  */
-function reclaimableFreeBytes() {
+export function parsePmset(out) {
+  const onAc = /AC Power/.test(out);
+  if (!/InternalBattery/.test(out)) return { hasBattery: false, charging: onAc };
+  const percent = Number((out.match(/(\d+)%/) || [])[1]);
+  const charging = onAc || /\bcharging\b/.test(out) || /\bcharged\b/.test(out);
+  const pct = Number.isFinite(percent) ? percent : null;
+  return { hasBattery: true, percent: pct, charging, low: pct != null && pct <= 20 && !charging };
+}
+
+// ── Async exec wrappers (timer-path only) ────────────────────────────────────
+
+/**
+ * Reclaimable ("available") free memory in bytes, fetched asynchronously.
+ *
+ * Returns null on non-darwin or any exec/parse failure so the caller falls
+ * back to `os.freemem()`.
+ *
+ * @returns {Promise<number|null>}
+ */
+async function reclaimableFreeBytes() {
   if (process.platform !== 'darwin') return null;
   try {
-    const out = execSync('vm_stat', { encoding: 'utf8', timeout: 1000 });
-    const pageSize = Number((out.match(/page size of (\d+) bytes/) || [])[1]) || 4096;
-    const pages = (label) => {
-      const m = out.match(new RegExp(`${label}:\\s+(\\d+)\\.`));
-      return m ? Number(m[1]) : 0;
-    };
-    const available =
-      pages('Pages free') +
-      pages('Pages inactive') +
-      pages('Pages speculative') +
-      pages('Pages purgeable') +
-      pages('File-backed pages');
-    return available * pageSize;
+    const { stdout } = await execFileAsync('vm_stat', [], { encoding: 'utf8', timeout: 1000 });
+    return parseVmStat(stdout);
   } catch {
     return null;
   }
 }
 
 /**
- * Battery / power status via `pmset -g batt` (darwin only). Returns null on
- * other platforms or any failure (UI then hides the battery chip). `low` is a
- * UI hint: ≤20% and not charging.
- * ponytail: macOS-only via pmset; add upower/sysfs parsing if Linux is ever needed.
+ * Battery / power status via `pmset -g batt` (darwin only), fetched asynchronously.
+ *
+ * Returns null on other platforms or any failure (UI then hides the battery chip).
+ *
+ * @returns {Promise<{ hasBattery: boolean, percent?: number|null, charging?: boolean, low?: boolean }|null>}
  */
-function powerStatus() {
+async function powerStatus() {
   if (process.platform !== 'darwin') return null;
   try {
-    const out = execSync('pmset -g batt', { encoding: 'utf8', timeout: 1000 });
-    const onAc = /AC Power/.test(out);
-    if (!/InternalBattery/.test(out)) return { hasBattery: false, charging: onAc };
-    const percent = Number((out.match(/(\d+)%/) || [])[1]);
-    const charging = onAc || /\bcharging\b/.test(out) || /\bcharged\b/.test(out);
-    const pct = Number.isFinite(percent) ? percent : null;
-    return { hasBattery: true, percent: pct, charging, low: pct != null && pct <= 20 && !charging };
+    const { stdout } = await execFileAsync('pmset', ['-g', 'batt'], { encoding: 'utf8', timeout: 1000 });
+    return parsePmset(stdout);
   } catch {
     return null;
   }
@@ -83,9 +116,17 @@ export class ResourceMonitor extends EventEmitter {
 
     // Power is sampled less often than cpu/mem (pmset is a subprocess): refresh
     // every 5th tick (~15s). Cache between refreshes.
-    this._power = powerStatus();
+    // Starts as null; first real value arrives on the first tick.
+    this._power = null;
     this._powerTick = 0;
 
+    // Reclaimable free-memory bytes: cached by the async tick. Starts as null
+    // so the first snapshot falls back to os.freemem() (same as non-darwin).
+    this._reclaimable = null;
+
+    // In-flight guard: prevents a slow tick from overlapping the next interval.
+    this._ticking = false;
+
     // Compute an initial snapshot so snapshot() works before start().
     this._latest = this._compute();
   }
@@ -112,19 +153,35 @@ export class ResourceMonitor extends EventEmitter {
 
   // ---- internals -------------------------------------------------------------
 
-  _tick() {
-    if (++this._powerTick % 5 === 0) this._power = powerStatus();
-    const snap = this._compute();
-    this._latest = snap;
-    this.emit('sample', snap);
-
-    if (snap.overLimit && !this._overLimit) {
-      // Rising edge only.
-      this._overLimit = true;
-      this.emit('overlimit', snap);
-    } else if (!snap.overLimit) {
-      // Reset so we can emit again if it crosses again later.
-      this._overLimit = false;
+  async _tick() {
+    // Re-entrancy guard: if a previous tick is still awaiting subprocess results,
+    // skip this interval entirely rather than running two ticks in parallel.
+    if (this._ticking) return;
+    this._ticking = true;
+    try {
+      // Refresh power every 5th tick (~15s). Awaiting here is safe — the guard
+      // above prevents any overlap with the next scheduled interval.
+      if (++this._powerTick % 5 === 0) {
+        this._power = await powerStatus();
+      }
+
+      // Refresh reclaimable memory bytes every tick (vm_stat is fast, ~5ms).
+      this._reclaimable = await reclaimableFreeBytes();
+
+      const snap = this._compute();
+      this._latest = snap;
+      this.emit('sample', snap);
+
+      if (snap.overLimit && !this._overLimit) {
+        // Rising edge only.
+        this._overLimit = true;
+        this.emit('overlimit', snap);
+      } else if (!snap.overLimit) {
+        // Reset so we can emit again if it crosses again later.
+        this._overLimit = false;
+      }
+    } finally {
+      this._ticking = false;
     }
   }
 
@@ -150,8 +207,8 @@ export class ResourceMonitor extends EventEmitter {
     const loadavg = /** @type {[number, number, number]} */ (os.loadavg());
     const cpuCount = os.cpus().length;
     const totalMB = Math.round(os.totalmem() / 1048576);
-    const reclaimable = reclaimableFreeBytes();
-    const freeMB = Math.round((reclaimable != null ? reclaimable : os.freemem()) / 1048576);
+    // Use the async-cached reclaimable value; falls back to os.freemem() when null.
+    const freeMB = Math.round((this._reclaimable != null ? this._reclaimable : os.freemem()) / 1048576);
     const memUsedPct = Math.round(((totalMB - freeMB) / totalMB) * 100 * 10) / 10;
 
     return {
@@ -167,6 +224,9 @@ export class ResourceMonitor extends EventEmitter {
 /**
  * Snapshot of the busiest processes via `ps`, newest BSD/macOS + Linux compatible
  * flags. Returns up to `limit` rows sorted by CPU%. Best-effort: [] on failure.
+ *
+ * NOTE: This is request-driven (called per HTTP request), not timer-driven, so
+ * it intentionally stays synchronous. Do not convert to async.
  */
 export function listProcesses(limit = 40) {
   try {