@idl3/claude-control 0.2.0 → 0.3.0

package/README.md

@@ -18,11 +18,16 @@ 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):**
 
-- **Voice → text** — `brew install ffmpeg whisper-cpp` and drop a model at `~/.claude-control/models/ggml-base.en.bin`. The mic in the composer records audio and transcribes it locally.
+- **Voice → text** — run `claude-control setup` once: it installs `ffmpeg` + `whisper.cpp` (Homebrew) and downloads a ggml model to `~/.claude-control/models/`. The mic in the composer then records audio and transcribes it locally (no API key). *(Manual equivalent: `brew install ffmpeg whisper-cpp` and drop a model at `~/.claude-control/models/ggml-base.en.bin`.)*
 - **Prompt enhancer (✨)** — defaults to a **local MLX model** on Apple Silicon. One-time setup:
   ```bash
   python3 -m venv ~/.claude-control/mlx-venv
@@ -96,16 +101,59 @@ matching transcript under `~/.claude/projects/`.
 
 ---
 
-## Updating
+## Updating & restarting
+
+How you update depends on **how you installed** — pick your row. Check your
+current version any time with `claude-control --version`.
+
+> **`npm install` does NOT pull the git repo.** The npm package ships the app
+> *prebuilt* (the `web/dist` bundle is included), so there's no source tree to
+> `git pull` and nothing to build. Update by reinstalling the package.
+
+### Installed globally (`npm install -g`)
+
+```bash
+npm install -g @idl3/claude-control@latest   # fetch the new version
+# then restart the server (see "Restarting" below)
+```
+
+The in-app **update banner / “Update now”** button is for **source checkouts
+only** (it runs `git pull`); on an npm install it has no repo to update, so use
+the command above instead.
+
+### Run via `npx` (no install)
+
+```bash
+npx @idl3/claude-control@latest               # always fetches the latest
+```
+
+`npx` re-resolves the package each run, so you're already on the newest version
+every time you start it — just restart the process.
+
+### From source (git checkout)
+
+```bash
+git pull && npm install && npm run build       # then restart
+```
+
+…or click **Update now** in the app: the server pulls from `origin`, reinstalls,
+rebuilds `web/dist`, and restarts itself in place; the page reconnects
+automatically.
+
+### Restarting the server
+
+- **Foreground** (you ran `claude-control` / `npm start` in a terminal): press
+  `Ctrl-C`, then run it again. The web UI reconnects on its own.
+- **launchd service** (you ran `claude-control install-service`):
+  ```bash
+  launchctl kickstart -k gui/$(id -u)/com.ernest.claude-control
+  ```
+  or `claude-control uninstall-service && claude-control install-service`.
 
-claude-control compares your checkout against its git upstream (`origin`) and
-shows an **update banner** when new commits are available. Click **Update now**
-— the server pulls, reinstalls, rebuilds the web bundle, and restarts itself in
-place; the page reconnects automatically. (Equivalent manual update: `git pull
-&& npm install && npm run build`, then restart.)
+Restarting is safe — sessions live in tmux, so nothing is lost; each browser
+re-prompts for the token once (if one is set).
 
-Version numbers follow npm semver (bump `package.json` per release); this is
-**v0.1.0**.
+Version numbers follow npm semver (`claude-control --version`).
 
 ---
 

package/lib/match.js

@@ -15,6 +15,10 @@
 import { isCwdConsistent } from './sessions.js';
 
 const DEFAULT_START_SLACK_MS = 5 * 60_000; // proc-start vs transcript-birth tolerance
+// Two candidates active within this window count as a recency "tie", so the
+// start-time ↔ birthtime signal breaks it (concurrent sessions in one cwd).
+// Beyond it, the more-recently-active transcript always wins (resume-safe).
+const RECENCY_TIE_MS = 2 * 60_000;
 
 /**
  * @param {string|null} etime  macOS `ps -o etime` value: "[[dd-]hh:]mm:ss"
@@ -115,45 +119,33 @@ export function assignTranscripts(panes, candidates, opts = {}) {
   // sessions.js BEFORE this matcher runs; assignTranscripts is the fallback for
   // panes with no hook record, using only deterministic timing signals below.
 
-  // Pass 1 — 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;
-      }
+  const activity = (c) => c.lastActivityMs ?? c.mtime ?? c.birthtimeMs ?? 0;
+
+  // Choose between two candidates for a pane: RECENCY is primary (the actively-
+  // written transcript wins), and start-time ↔ birthtime only breaks ties when
+  // two candidates were active at nearly the same time (genuinely concurrent
+  // sessions in one cwd). This is what fixes resumed sessions: a resumed
+  // 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).
+  const prefer = (pane, c, best) => {
+    const ca = activity(c);
+    const ba = activity(best);
+    if (Math.abs(ca - ba) > RECENCY_TIE_MS) return ca > ba;
+    if (pane.procStartMs != null && c.birthtimeMs != null && best.birthtimeMs != null) {
+      const cd = Math.abs(c.birthtimeMs - pane.procStartMs);
+      const bd = Math.abs(best.birthtimeMs - pane.procStartMs);
+      if (cd !== bd) return cd < bd;
     }
-    if (best) claim(pane, best);
-  }
+    return ca > ba;
+  };
 
-  // Pass 2 — most-recently-active remaining candidate.
-  // Gate: when the pane's process start time is known, only consider candidates
-  // whose last known activity (lastActivityMs, falling back to file mtime or
-  // birthtime) is at or after the pane started (minus startSlackMs). A transcript
-  // that was never touched after the pane launched cannot belong to it — that is
-  // the "fresh pane inherits old transcript" bug. When procStartMs is unknown,
-  // skip the gate so we don't regress panes with missing timing data.
-  // NOTE: --resume is safe: Claude appends a record to the old transcript on
-  // resume, bumping its mtime/lastActivityMs above the pane's start time.
   for (const pane of ordered) {
     if (result.has(pane.target)) continue;
     let best = null;
     for (const c of available(pane)) {
       if (!temporallyPlausible(pane, c)) continue;
-      if (!best || (c.lastActivityMs ?? 0) > (best.lastActivityMs ?? 0)) best = c;
+      if (!best || prefer(pane, c, best)) best = c;
     }
     if (best) claim(pane, best);
   }

package/lib/optimize.js

@@ -176,6 +176,9 @@ function wordCount(s) {
 }
 
 const QUESTION_BOILERPLATE = /\b(specify|please provide|could you clarify|clarif(y|ication)|let me know)\b/i;
+// The model sometimes echoes/optimises buildLlmPrompt itself — these phrases are
+// the optimiser's own meta-instructions and must never appear in a rewrite.
+const PROMPT_LEAK = /(treat the draft|content to rewrite|not as instructions to follow|return strict json|rewritten prompt|prompt optimiser|examples of the bar|```draft|"optimized"|"rationale")/i;
 const LIST_LINE = /^\s*(\d+[).]|[-*])\s+/gm;
 const STOPWORDS = new Set([
   'the', 'a', 'an', 'to', 'of', 'and', 'or', 'for', 'in', 'on', 'with', 'is',
@@ -221,6 +224,7 @@ function isInterrogative(s) {
  *  - instruction-to-question: an imperative draft turned interrogative
  *  - added-list:            ≥2 list lines the draft didn't have
  *  - intent-drift:          <50% of the draft's content tokens survive
+ *  - prompt-leak:           the model echoed buildLlmPrompt's own instructions
  *  - empty:                 blank result
  *
  * @param {string} draft
@@ -260,6 +264,7 @@ export function evaluateRewrite(draft, optimized) {
   if (isImperative(draft) && isInterrogative(opt)) violations.push('instruction-to-question');
   if (!draftHasList && optListLines >= 2) violations.push('added-list');
   if (dTokens.length >= 4 && survived < 0.5) violations.push('intent-drift');
+  if (PROMPT_LEAK.test(opt) && !PROMPT_LEAK.test(draft)) violations.push('prompt-leak');
 
   return { ok: violations.length === 0, violations, metrics };
 }
@@ -283,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
         }

package/lib/shell.js

@@ -30,8 +30,16 @@ const NAMED_KEYS = [
   'Up', 'Down', 'Left', 'Right', 'Home', 'End', 'PPage', 'NPage',
   'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12',
 ];
+// Navigation keys with every Ctrl/Meta/Shift modifier combination, so a hardware
+// keyboard (e.g. iPad Magic Keyboard) can send Opt+Arrow word-jumps, Shift+Arrow
+// selection, etc. Prefix order is C-,M-,S- (matches the frontend navToken).
+const NAV_KEYS = ['Up', 'Down', 'Left', 'Right', 'Home', 'End', 'PPage', 'NPage'];
+const NAV_PREFIXES = ['', 'C-', 'M-', 'S-', 'C-M-', 'C-S-', 'M-S-', 'C-M-S-'];
+const NAV_COMBOS = NAV_KEYS.flatMap((k) => NAV_PREFIXES.map((p) => p + k));
+
 export const SHELL_KEYS = new Set([
   ...NAMED_KEYS,
+  ...NAV_COMBOS, // Up/Down/.../NPage with C-/M-/S- combinations
   ...ALPHA.map((c) => `C-${c}`), // C-a .. C-z
   ...ALPHA.map((c) => `M-${c}`), // M-a .. M-z (Option/Meta)
 ]);