@idl3/claude-control 0.2.1 → 0.3.0

package/README.md

@@ -18,6 +18,11 @@ talks to tmux. Bind is localhost-only by default.
 npm install -g @idl3/claude-control     # or run once: npx @idl3/claude-control
 ```
 
+> **`claude-control: command not found`?** Use `-g` — a plain/local `npm install`
+> only drops the binary in `./node_modules/.bin/` (not on `PATH`). If it's still
+> missing after `-g`, your npm global bin dir isn't on `PATH`: run `npm prefix -g`
+> and add `<that>/bin` to your shell `PATH`, or just use `npx @idl3/claude-control`.
+
 **Prerequisites:** Node ≥20 and **tmux** on your `PATH` (`brew install tmux` · `sudo apt install tmux`). Optional: **ttyd** for the in-browser raw terminal (`brew install ttyd` · `sudo apt install ttyd`) — set `CLAUDE_CONTROL_TTYD` to override its path. The web UI ships prebuilt — no build step on install.
 
 **Optional local AI (no API key):**

package/lib/optimize.js

@@ -288,17 +288,32 @@ export function isRunawayRewrite(draft, optimized) {
  */
 function coerceLlmParsed(parsed) {
   if (!parsed || typeof parsed !== 'object') return null;
-  const optimized = typeof parsed.optimized === 'string' ? parsed.optimized.trim() : '';
+  const optimized = typeof parsed.optimized === 'string' ? decodeLeakedEscapes(parsed.optimized).trim() : '';
   if (!optimized) return null;
   const rationale = Array.isArray(parsed.rationale)
-    ? parsed.rationale.filter((x) => typeof x === 'string')
+    ? parsed.rationale.filter((x) => typeof x === 'string').map(decodeLeakedEscapes)
     : [];
   const changes = Array.isArray(parsed.changes)
-    ? parsed.changes.filter((x) => typeof x === 'string')
+    ? parsed.changes.filter((x) => typeof x === 'string').map(decodeLeakedEscapes)
     : [];
   return { optimized, rationale, changes };
 }
 
+/**
+ * Decode literal `\uXXXX` escapes the model sometimes double-escapes into the
+ * JSON string (e.g. an apostrophe becomes the LITERAL text "’" instead of
+ * ’). Without this, those backslash-u sequences get typed verbatim into the
+ * composer/tmux. Only touches `\uXXXX` (and `\\`) — leaves other text intact.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function decodeLeakedEscapes(s) {
+  return String(s)
+    .replace(/\\\\/g, '\\') // collapse double-escaped backslashes first
+    .replace(/\\u([0-9a-fA-F]{4})/g, (_, h) => String.fromCharCode(parseInt(h, 16)));
+}
+
 /**
  * Tolerant JSON parse: try direct parse; on failure extract first balanced
  * `{...}` block and try again.

package/lib/prompt.js

@@ -16,12 +16,15 @@ function stripAnsi(s) {
 
 // A numbered option line, optionally preceded by the TUI cursor (❯/›).
 const OPTION_RE = /^\s*([❯›]?)\s*(\d)[.)]\s+(.+?)\s*$/;
+// A checkbox marker at the START of an option label, e.g. "[ ] Label" or "[x] Label".
+// Matches the bracket content: space = unchecked; x/✓/✗ = checked.
+const CHECKBOX_RE = /^\[([✓x✗ ])\]\s*(.*)/;
 // The footer real Claude Code prompts render under the options.
 const ESC_HINT_RE = /\besc\b[^\n]*(cancel|interrupt|exit|reject|keep|quit)|ctrl\+[a-z]\b/i;
 // How many lines from the bottom to consider — the active prompt always renders
 // at the bottom of the pane, so a numbered list higher up (assistant prose) is
 // out of scope.
-const BOTTOM_REGION = 18;
+const BOTTOM_REGION = 26;
 const MAX_LABEL = 80;
 
 /**
@@ -41,36 +44,57 @@ export function parsePanePrompt(capture) {
   const offset = Math.max(0, all.length - BOTTOM_REGION);
   const lines = all.slice(offset);
 
-  // Last contiguous run of numbered options within the bottom region.
-  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;
-
-  let start = end;
-  while (start - 1 >= 0 && OPTION_RE.test(lines[start - 1])) start -= 1;
-
-  const options = [];
-  let hasCursor = false;
-  for (let i = start; i <= end; i++) {
+  // Collect every numbered-option line in the bottom region. The AskUserQuestion
+  // picker renders each option as a header line PLUS a wrapped description line,
+  // so options are NOT contiguous — we must look past the description lines and
+  // stitch together a 1,2,3… sequence by key, not by adjacency.
+  const matches = [];
+  for (let i = 0; i < lines.length; i++) {
     const m = OPTION_RE.exec(lines[i]);
     if (!m) continue;
-    const cursor = m[1] === '❯' || m[1] === '›';
-    if (cursor) hasCursor = true;
     let label = m[3].trim();
+    // Detect and strip a checkbox marker from the label.
+    let checked = undefined;
+    const cbMatch = CHECKBOX_RE.exec(label);
+    if (cbMatch) {
+      checked = cbMatch[1] !== ' '; // space = unchecked; x/✓/✗ = checked
+      label = cbMatch[2].trim();
+    }
     if (label.length > MAX_LABEL) label = label.slice(0, MAX_LABEL - 1) + '…';
-    options.push({ key: m[2], label, selected: cursor });
+    matches.push({ line: i, key: m[2], label, cursor: m[1] === '❯' || m[1] === '›', checked });
   }
-  // Need ≥2 options numbered consecutively from 1 to look like a menu.
-  if (options.length < 2 || options[0].key !== '1') return null;
+  if (matches.length < 2) return null;
 
-  // "Esc to cancel / ctrl+e" footer within a few lines below the block.
+  // Group into runs of consecutive ascending keys (1,2,3… OR 3,4,5… — the menu's
+  // first options can scroll off the top of the capture, so we must NOT require
+  // it to start at 1). Description lines between options don't break a run since
+  // we key off the NUMBERS, not line adjacency. Pick the bottom-most run — the
+  // active picker always renders at the bottom of the pane.
+  const runs = [];
+  let cur = [];
+  for (const m of matches) {
+    const prevKey = cur.length ? Number(cur[cur.length - 1].key) : null;
+    if (prevKey !== null && Number(m.key) === prevKey + 1) {
+      cur.push(m);
+    } else if (prevKey !== null && Number(m.key) === prevKey) {
+      // duplicate key (re-render artifact) — ignore
+    } else {
+      if (cur.length) runs.push(cur);
+      cur = [m];
+    }
+  }
+  if (cur.length) runs.push(cur);
+  const options = [...runs].reverse().find((r) => r.length >= 2);
+  // Need ≥2 consecutively-numbered options to look like a menu.
+  if (!options) return null;
+
+  const firstLine = options[0].line;
+  const lastLine = options[options.length - 1].line;
+  const hasCursor = options.some((o) => o.cursor);
+
+  // "Esc to cancel / ctrl+e" footer within a few lines below the last option.
   let hasEsc = false;
-  for (let i = end + 1; i <= Math.min(lines.length - 1, end + 3); i++) {
+  for (let i = lastLine + 1; i <= Math.min(lines.length - 1, lastLine + 3); i++) {
     if (ESC_HINT_RE.test(lines[i])) {
       hasEsc = true;
       break;
@@ -80,15 +104,25 @@ export function parsePanePrompt(capture) {
   // Require a genuine interactive-prompt signal — not just numbered prose.
   if (!hasCursor && !hasEsc) return null;
 
-  // Question = nearest non-empty line above the options block.
-  let question = '';
-  for (let i = start - 1; i >= 0 && i >= start - 4; i--) {
+  // Question = the contiguous non-empty block immediately above the options (the
+  // prompt can wrap onto several lines), joined into one string.
+  const qLines = [];
+  for (let i = firstLine - 1; i >= 0 && i >= firstLine - 4; i--) {
     const t = lines[i].trim();
-    if (t) {
-      question = t;
-      break;
-    }
+    if (!t) break;
+    qLines.unshift(t);
   }
+  const question = qLines.join(' ').slice(0, 240);
 
-  return { question: question || 'Make a selection', options };
+  const hasCheckboxes = options.some((o) => o.checked !== undefined);
+  return {
+    question: question || 'Make a selection',
+    ...(hasCheckboxes ? { multiSelect: true } : {}),
+    options: options.map((o) => ({
+      key: o.key,
+      label: o.label,
+      selected: o.cursor,
+      ...(o.checked !== undefined ? { checked: o.checked } : {}),
+    })),
+  };
 }

package/lib/resources.js

@@ -45,6 +45,27 @@ function reclaimableFreeBytes() {
   }
 }
 
+/**
+ * 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.
+ */
+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 };
+  } catch {
+    return null;
+  }
+}
+
 export class ResourceMonitor extends EventEmitter {
   /**
    * @param {{ intervalMs?: number, rssLimitMB?: number }} opts
@@ -60,6 +81,11 @@ export class ResourceMonitor extends EventEmitter {
     this._prevCpu = process.cpuUsage();
     this._prevWall = Date.now();
 
+    // Power is sampled less often than cpu/mem (pmset is a subprocess): refresh
+    // every 5th tick (~15s). Cache between refreshes.
+    this._power = powerStatus();
+    this._powerTick = 0;
+
     // Compute an initial snapshot so snapshot() works before start().
     this._latest = this._compute();
   }
@@ -87,6 +113,7 @@ 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);
@@ -131,7 +158,55 @@ export class ResourceMonitor extends EventEmitter {
       ts: Date.now(),
       self: { cpuPct, rssMB, heapMB },
       system: { loadavg, cpuCount, totalMB, freeMB, memUsedPct },
+      power: this._power,
       overLimit: rssMB > this._rssLimitMB,
     };
   }
 }
+
+/**
+ * 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.
+ */
+export function listProcesses(limit = 40) {
+  try {
+    // -A all procs; -o explicit columns; comm=command name, args truncated by us.
+    const out = execSync('ps -Ao pid,ppid,%cpu,%mem,rss,comm', {
+      encoding: 'utf8',
+      timeout: 2000,
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    const rows = out.trim().split('\n').slice(1).map((line) => {
+      const m = line.trim().match(/^(\d+)\s+(\d+)\s+([\d.]+)\s+([\d.]+)\s+(\d+)\s+(.+)$/);
+      if (!m) return null;
+      return {
+        pid: Number(m[1]),
+        ppid: Number(m[2]),
+        cpu: Number(m[3]),
+        mem: Number(m[4]),
+        rssMB: Math.round(Number(m[5]) / 1024),
+        command: m[6],
+      };
+    }).filter(Boolean);
+    rows.sort((a, b) => b.cpu - a.cpu);
+    return rows.slice(0, limit);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Send a signal to a pid. Validates the pid is a positive integer and refuses
+ * pid 1 and the server's own pid. Returns {ok} / {ok:false,error}.
+ */
+export function killProcess(pid, signal = 'SIGTERM') {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 1) return { ok: false, error: 'invalid pid' };
+  if (n === process.pid) return { ok: false, error: 'refusing to kill the control server' };
+  try {
+    process.kill(n, signal);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: String(err?.message || err) };
+  }
+}

package/lib/sessions.js

@@ -14,6 +14,7 @@ import { execFile as _execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
 import { parseTuiStatus, prettyModel } from './tui.js';
+import { parsePanePrompt } from './prompt.js';
 import { assignTranscripts, parseEtime } from './match.js';
 import { pinKey } from './pins.js';
 import { readPaneRegistry, gcPaneRegistry } from './pane-registry.js';
@@ -333,6 +334,8 @@ export class SessionRegistry extends EventEmitter {
     this._ctxMap = new Map();
     /** @type {Map<string, boolean>} target -> actively-generating flag */
     this._thinkingMap = new Map();
+    /** @type {Map<string, {pending:boolean, question:string|null}>} target -> pane-derived prompt */
+    this._panePromptMap = new Map();
     /** @type {ReturnType<setInterval>|null} */
     this._interval = null;
     /** @type {ReturnType<setInterval>|null} */
@@ -469,9 +472,13 @@ export class SessionRegistry extends EventEmitter {
       const isPinned = pinnedByTarget.has(win.target);
       const id = win.target;
       // Pending = subscribed-tailer pending (live modal) OR transcript-derived
-      // pending (works for ANY session, even unsubscribed ones, for push).
+      // pending OR pane-derived prompt (a numbered picker on screen — catches
+      // questions even when the transcript isn't matched). Works for ANY session.
+      const panePrompt = isClaude ? this._panePromptMap.get(id) : null;
       const pending =
-        (this._pendingMap.get(id) ?? false) || !!transcript?.transcriptPending;
+        (this._pendingMap.get(id) ?? false) ||
+        !!transcript?.transcriptPending ||
+        !!panePrompt?.pending;
       const title = transcript?.customTitle || transcript?.aiTitle || null;
       const ctx = isClaude ? this._ctxMap.get(win.target) || {} : {};
 
@@ -494,7 +501,7 @@ export class SessionRegistry extends EventEmitter {
         pinned: isPinned,
         lastActivity: transcript?.lastActivity ?? null,
         pending,
-        pendingQuestion: transcript?.pendingQuestion ?? null,
+        pendingQuestion: transcript?.pendingQuestion ?? panePrompt?.question ?? null,
         cmd: win.cmd,
         isClaude,
         kind: isClaude ? 'claude' : 'terminal',
@@ -549,11 +556,27 @@ export class SessionRegistry extends EventEmitter {
       sessions.map(async (s) => {
         if (!this._tmux.isValidTarget(s.target)) return;
         try {
-          const cap = await this._tmux.capturePane(s.target, 5);
+          // Capture enough of the bottom to catch BOTH the working line ("esc to
+          // interrupt", which can sit several rows above the input box) AND a TUI
+          // question picker (parsePanePrompt scans ~18 bottom rows). One capture
+          // feeds both — keeping activity detection robust without extra execs.
+          const cap = await this._tmux.capturePane(s.target, 26);
           const { thinking } = parseTuiStatus(cap);
           this._thinkingMap.set(s.target, thinking);
-          // Merge into the live session object without a full rebuild.
           s.thinking = thinking;
+
+          // Pane-derived question detection (Claude panes only): an on-screen
+          // numbered picker means a question is waiting — even if the transcript
+          // isn't matched. This is why some sessions wrongly read as "sleeping".
+          if (s.kind === 'claude') {
+            const prompt = parsePanePrompt(cap);
+            const rec = { pending: !!prompt, question: prompt?.question ?? null };
+            this._panePromptMap.set(s.target, rec);
+            const merged =
+              (this._pendingMap.get(s.target) ?? false) || rec.pending || s.pending;
+            s.pending = merged;
+            if (rec.pending && !s.pendingQuestion) s.pendingQuestion = rec.question;
+          }
         } catch {
           // pane gone / capture failed — leave previous value
         }