@idl3/claude-control 0.1.2 → 0.1.3

package/lib/match.js

@@ -0,0 +1,136 @@
+/**
+ * lib/match.js — deterministic pane↔transcript assignment.
+ *
+ * Why this exists: multiple Claude sessions can run in the SAME directory (e.g.
+ * two panes both in ~/Projects). Claude Code names a transcript's project
+ * directory after the cwd, so directory alone cannot tell two same-cwd sessions
+ * apart. The previous "newest transcript in the dir → the active window" rule
+ * therefore mis-routed: a reply typed into one pane surfaced under another.
+ *
+ * This module assigns at most ONE transcript to each pane, 1:1, using layered
+ * signals (strongest first). It is pure and deterministic so the cross-send case
+ * is unit-testable.
+ */
+
+import { isCwdConsistent } from './sessions.js';
+
+const DEFAULT_START_SLACK_MS = 5 * 60_000; // proc-start vs transcript-birth tolerance
+
+/**
+ * @param {string|null} etime  macOS `ps -o etime` value: "[[dd-]hh:]mm:ss"
+ * @returns {number|null} elapsed seconds, or null if unparseable
+ */
+export function parseEtime(etime) {
+  const s = String(etime || '').trim();
+  if (!s) return null;
+  // optional "dd-" prefix, then hh:mm:ss or mm:ss
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(s);
+  if (!m) return null;
+  const days = Number(m[1] || 0);
+  const hours = Number(m[2] || 0);
+  const mins = Number(m[3] || 0);
+  const secs = Number(m[4] || 0);
+  return ((days * 24 + hours) * 60 + mins) * 60 + secs;
+}
+
+/**
+ * @typedef {Object} MatchPane
+ * @property {string}      target       "session:window.pane"
+ * @property {string}      windowName
+ * @property {string}      cwd
+ * @property {number|null} procStartMs  claude process start (ms epoch), or null
+ *
+ * @typedef {Object} MatchCandidate
+ * @property {string}      transcriptPath
+ * @property {string|null} cwd            cwd recorded inside the transcript
+ * @property {number|null} birthtimeMs
+ * @property {number|null} mtimeMs
+ * @property {number|null} lastActivityMs
+ * @property {string|null} customTitle
+ * @property {string|null} aiTitle
+ */
+
+/**
+ * Assign transcripts to panes 1:1.
+ *
+ * Layered passes (each claims candidates so no transcript is used twice):
+ *   1. Title match — a pane's tmux window name uniquely equals a candidate's
+ *      customTitle (set by /rename) or aiTitle, cwd-consistent. Strongest:
+ *      survives restarts and is independent of timing.
+ *   2. Start-time match — candidate birthtime closest to the pane's claude
+ *      process start (cwd-consistent). A claude proc creates its transcript at
+ *      launch, so this binds same-cwd siblings that started at different times.
+ *   3. Recency — most-recently-active remaining cwd-consistent candidate.
+ *
+ * Panes are processed in a stable (target-sorted) order so results are
+ * deterministic regardless of tmux listing order.
+ *
+ * @param {MatchPane[]} panes
+ * @param {MatchCandidate[]} candidates
+ * @param {{ startSlackMs?: number }} [opts]
+ * @returns {Map<string, MatchCandidate>} target -> candidate
+ */
+export function assignTranscripts(panes, candidates, opts = {}) {
+  const startSlackMs = opts.startSlackMs ?? DEFAULT_START_SLACK_MS;
+  const result = new Map();
+  const claimed = new Set();
+  const ordered = [...panes].sort((a, b) => a.target.localeCompare(b.target));
+
+  const available = (pane) =>
+    candidates.filter(
+      (c) =>
+        !claimed.has(c.transcriptPath) && isCwdConsistent(c.cwd, pane.cwd),
+    );
+
+  const claim = (pane, cand) => {
+    result.set(pane.target, cand);
+    claimed.add(cand.transcriptPath);
+  };
+
+  // Pass 1 — unique title match.
+  for (const pane of ordered) {
+    if (result.has(pane.target)) continue;
+    const name = String(pane.windowName || '').trim();
+    if (!name) continue;
+    const hits = available(pane).filter(
+      (c) => c.customTitle === name || c.aiTitle === name,
+    );
+    if (hits.length === 1) claim(pane, hits[0]);
+  }
+
+  // Pass 2 — nearest start-time ↔ birthtime.
+  for (const pane of ordered) {
+    if (result.has(pane.target)) continue;
+    if (pane.procStartMs == null) continue;
+    let best = null;
+    let bestDelta = Infinity;
+    for (const c of available(pane)) {
+      if (c.birthtimeMs == null) continue;
+      const delta = Math.abs(c.birthtimeMs - pane.procStartMs);
+      // Prefer transcripts born around/after the proc started; reject ones born
+      // long before the proc (those belong to an earlier session in this dir).
+      if (c.birthtimeMs < pane.procStartMs - startSlackMs) continue;
+      if (
+        delta < bestDelta ||
+        (delta === bestDelta &&
+          (c.lastActivityMs ?? 0) > (best?.lastActivityMs ?? 0))
+      ) {
+        best = c;
+        bestDelta = delta;
+      }
+    }
+    if (best) claim(pane, best);
+  }
+
+  // Pass 3 — most-recently-active remaining candidate.
+  for (const pane of ordered) {
+    if (result.has(pane.target)) continue;
+    let best = null;
+    for (const c of available(pane)) {
+      if (!best || (c.lastActivityMs ?? 0) > (best.lastActivityMs ?? 0)) best = c;
+    }
+    if (best) claim(pane, best);
+  }
+
+  return result;
+}

package/lib/pins.js

@@ -0,0 +1,61 @@
+/**
+ * lib/pins.js — manual transcript pins.
+ *
+ * Escape hatch for sessions whose transcript can't be auto-matched (path drift,
+ * window-name ≠ session-title, no live fd). A pin explicitly binds a pane to a
+ * transcript file and takes top priority over the heuristic matcher.
+ *
+ * Pins are keyed by `windowId.paneIndex` (e.g. "@5.1") — STABLE across tmux
+ * window renumbering, unlike the session:window.pane target which shifts.
+ * Persisted as JSON: { "@5.1": "/abs/path/to/transcript.jsonl", ... }.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Stable pin key for a pane/session: windowId.paneIndex. */
+export function pinKey(windowId, paneIndex) {
+  return `${windowId}.${paneIndex ?? 0}`;
+}
+
+/** Load the pins map from disk. Never throws — returns {} on any problem. */
+export function loadPins(file) {
+  try {
+    const obj = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (obj && typeof obj === 'object' && !Array.isArray(obj)) return obj;
+  } catch {
+    /* missing / malformed → empty */
+  }
+  return {};
+}
+
+/** Persist the pins map atomically (best-effort). */
+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);
+}
+
+/**
+ * Validate a candidate transcript path for pinning: must be a string ending in
+ * .jsonl, resolve to inside projectsRoot, and exist. Returns the resolved path
+ * or null. Guards the pin API against arbitrary filesystem reads.
+ */
+export function validateTranscriptPath(raw, projectsRoot) {
+  if (typeof raw !== 'string' || !raw.endsWith('.jsonl')) return null;
+  let full;
+  try {
+    full = path.resolve(raw);
+  } catch {
+    return null;
+  }
+  if (!full.startsWith(projectsRoot + path.sep)) return null;
+  try {
+    if (!fs.statSync(full).isFile()) return null;
+  } catch {
+    return null;
+  }
+  return full;
+}

package/lib/prompt.js

@@ -0,0 +1,73 @@
+// lib/prompt.js — detect a Claude Code TUI selection prompt from a pane capture.
+//
+// Permission prompts ("Do you want to proceed?  1. Yes / 2. Yes, don't ask /
+// 3. No"), trust prompts, and similar numbered menus live ONLY in the live TUI —
+// they are never written to the transcript JSONL. The cockpit is transcript-
+// driven, so without this it shows a pending tool-call and looks stuck. We poll
+// the pane, parse the prompt here, and surface it as an actionable modal.
+
+// Strip ANSI/OSC escape sequences (capture-pane is taken with -e).
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07|\x1b[()][AB0]/g;
+
+function stripAnsi(s) {
+  return String(s).replace(ANSI_RE, '');
+}
+
+const OPTION_RE = /^\s*[❯›>*]?\s*(\d)[.)]\s+(.+?)\s*$/;
+const PROMPT_HINT_RE = /(do you want|want to proceed|proceed\?|trust|allow this|continue\?)/i;
+const MAX_LABEL = 80;
+
+/**
+ * Parse a Claude Code numbered selection prompt out of a pane capture.
+ *
+ * @param {string} capture  raw `capture-pane -p -e` text
+ * @returns {{ question: string, options: {key:string,label:string,selected:boolean}[] }|null}
+ */
+export function parsePanePrompt(capture) {
+  const lines = stripAnsi(capture).split('\n').map((l) => l.replace(/\s+$/, ''));
+
+  // Find the LAST contiguous run of numbered options (the active prompt is at the
+  // bottom of the pane). Walk from the end.
+  let end = -1;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (OPTION_RE.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  if (end < 0) return null;
+
+  // Expand upward over the contiguous numbered block.
+  let start = end;
+  while (start - 1 >= 0 && OPTION_RE.test(lines[start - 1])) start -= 1;
+
+  const options = [];
+  for (let i = start; i <= end; i++) {
+    const m = OPTION_RE.exec(lines[i]);
+    if (!m) continue;
+    let label = m[2].trim();
+    if (label.length > MAX_LABEL) label = label.slice(0, MAX_LABEL - 1) + '…';
+    const selected = /^[\s]*[❯›>*]/.test(lines[i]);
+    options.push({ key: m[1], label, selected });
+  }
+  // Need ≥2 options numbered consecutively from 1 to look like a real menu.
+  if (options.length < 2) return null;
+  if (options[0].key !== '1') return null;
+
+  // Question = nearest non-empty line above the options block (e.g. "Do you want
+  // to proceed?"). Require a prompt-like hint to avoid matching random lists.
+  let question = '';
+  for (let i = start - 1; i >= 0 && i >= start - 4; i--) {
+    const t = lines[i].trim();
+    if (t) {
+      question = t;
+      break;
+    }
+  }
+  if (!PROMPT_HINT_RE.test(question) && !PROMPT_HINT_RE.test(lines.join(' '))) {
+    return null;
+  }
+
+  return { question: question || 'Do you want to proceed?', options };
+}