cli-setu 0.1.0

package/src/supervisor.js

@@ -0,0 +1,1264 @@
+// QR pairing (unchanged) PLUS Phase 6 full terminal mirroring:
+//   - Device never paired before -> the QR both pairs it AND jumps the
+//     phone straight to watching THIS session (scan.html + auth-server.js's
+//     /device/pair/qr-confirm do both in one round trip).
+//   - Device already paired -> same QR mechanism, but auth-server.js skips
+//     re-pairing and the scan just means "watch this session on the phone."
+//   - EVERY byte the PTY produces is streamed live to Azure whenever a
+//     phone has terminal.html open and focused on this session (Section
+//     11f) - not just detected confirmation prompts. Unfocused, nothing
+//     extra streams; the confirmation-request path is completely
+//     unaffected either way.
+//   - Remote input (typed on the phone) and remote resize both write
+//     straight into this PTY, same as a local keystroke or a dragged
+//     terminal window edge.
+//
+// Run with: node supervisor-qr.js <deviceName> <sessionId> [workingDir] [--cli <name>]
+// e.g.       node supervisor-qr.js Laptop-1 session-A
+//            node supervisor-qr.js Laptop-1 session-B ./session-b
+//            node supervisor-qr.js Laptop-1 session-C ./proj --cli codex
+//
+// --cli defaults to 'claude' (this script's original, only-ever-supported
+// CLI). Any name not in cli-adapters/index.js's KNOWN_ADAPTERS still runs -
+// it just gets the generic PTY-only adapter (mirrored terminal, no
+// structured Confirmations card, no usage tracking) instead of refusing
+// to start. See cli-adapters/README.md for the adapter interface this
+// script now drives instead of hardcoding Claude Code's behavior directly.
+
+const pty = require('node-pty');
+const { Terminal: HeadlessTerminal } = require('@xterm/headless');
+const fs = require('fs');
+const path = require('path');
+const WebSocket = require('ws');
+const { exec, execFile } = require('child_process');
+const { promisify } = require('util');
+const execAsync = promisify(exec);
+// execFile (not exec) for anything that embeds a real filesystem path -
+// exec runs through cmd.exe, string-interpolating a path into a shell
+// command line is a real injection risk if that path ever contained
+// shell metacharacters (an unlikely but not impossible filename the CLI
+// itself created). execFile passes args as a real array, no shell
+// involved, no interpolation - the correct tool whenever a path is
+// data, not part of the command syntax itself.
+const execFileAsync = promisify(execFile);
+const { getAdapter } = require('./cli-adapters');
+
+// Real bug found by testing: this script's own console.log/console.error
+// calls write to the SAME process.stdout the PTY's raw output is echoed
+// to (see ptyProcess.onData below). Claude Code's TUI does full-screen
+// ANSI cursor positioning and assumes exclusive control of the terminal's
+// screen buffer - any plain text interleaved into that stream mid-redraw
+// (e.g. the "Azure decision..." log firing while a menu is on screen)
+// corrupts its cursor-position math, visible as duplicated headers,
+// garbled/overlapping lines, and log text bleeding into the TUI's own
+// chrome. Once the PTY is running, ALL supervisor diagnostics go to a log
+// file instead - stdout is reserved exclusively for the PTY passthrough
+// from that point on.
+const os = require('os');
+const crypto = require('crypto');
+const { readConfig, CONFIG_DIR } = require('./config');
+
+// Real gap in the proof-of-concept this replaces: every run required
+// typing <deviceName> <sessionId> as argv, and diagnostics went to a log
+// file sitting in the install folder. A real global install (`npm install
+// -g cli-setu`) has no single "install folder" a user would think to look
+// in, and every session's log lived in ~/.cli-setu instead - one file per
+// PAIRED DEVICE is still right (see the original comment this replaces:
+// keeps a Claude Code session and a Codex session from interleaving into
+// one indistinguishable file), just relocated to a real per-user config
+// directory instead of wherever npm happened to install the package.
+let LOG_FILE = path.join(CONFIG_DIR, 'supervisor.log');
+function log(...args) {
+  const line = `[${new Date().toISOString()}] ${args.join(' ')}\n`;
+  fs.appendFileSync(LOG_FILE, line);
+}
+
+// Real config, from pairing (src/pair.js, either via bin/setu.js's own
+// bare-`setu` pairing check or the explicit `setu pair` command) - not
+// argv. bin/setu.js already guarantees this exists before requiring this
+// file for a normal `setu` run; this is a defensive fallback for anyone
+// requiring supervisor.js directly, so a null deviceToken fails with a
+// clear message instead of a confusing crash deep in connectToAzure().
+const config = readConfig();
+if (!config || !config.deviceToken) {
+  console.error('[setu] This computer isn\'t paired yet. Run `setu` again, or run `setu pair` directly.');
+  process.exit(1);
+}
+const DEVICE_NAME = config.deviceName;
+
+const AUTH_SERVER = process.env.CLI_SETU_SERVER || 'https://api.clisetu.com';
+
+// --cli still supported, e.g. `setu --cli codex`, for the same reason it
+// existed before: one paired device can run more than one kind of CLI
+// across different sessions/folders. Real product decision (confirmed
+// directly by the PM): bare `setu` with no --cli flag bridges the user's
+// own plain terminal (see cli-adapters/shell.js), not Claude Code by
+// default - the user decides what to run once it's open, same as
+// getAdapter's own default (index.js) - kept in sync here rather than
+// letting this default silently drift from that one.
+const cliFlagIndex = process.argv.indexOf('--cli');
+const CLI_NAME = cliFlagIndex !== -1 ? process.argv[cliFlagIndex + 1] : 'shell';
+
+const WORKING_DIR = process.cwd();
+// Real gap in the PoC this replaces: sessionId was a hand-typed argv, a
+// real user shouldn't need to invent one. Derived from the device name
+// plus the real working directory (not just the folder's basename, which
+// collides the moment two different projects share a folder name like
+// "app" on the same machine) plus a short random suffix so re-running
+// `setu` in the same folder twice at once (e.g. two terminal tabs) never
+// silently shares one session.
+const dirHash = crypto.createHash('sha1').update(WORKING_DIR).digest('hex').slice(0, 8);
+const SESSION_ID = `${os.hostname()}-${dirHash}-${crypto.randomBytes(3).toString('hex')}`;
+
+// Per-device log file (see LOG_FILE's declaration comment above) - keeps
+// two supervisors running under the same paired device (e.g. a Claude
+// Code session and a Codex session) from interleaving into one
+// indistinguishable file.
+LOG_FILE = path.join(CONFIG_DIR, `supervisor.${DEVICE_NAME.replace(/[^a-zA-Z0-9-]/g, '_')}.log`);
+
+const adapter = getAdapter(CLI_NAME);
+console.log(`[supervisor] Using CLI adapter: ${adapter.displayName} (${adapter.id})`);
+log(`Using CLI adapter: ${adapter.displayName} (${adapter.id})`);
+
+// Real bug found by testing: when the spawned adapter is 'shell' (the
+// bare-`setu` default - see cli-adapters/shell.js), the user is expected
+// to freely run `claude` INSIDE that bridged shell whenever they want to.
+// Gating hook registration on "is the spawn-time adapter Claude" (as this
+// used to) meant Claude Code's hooks never got installed into
+// WORKING_DIR's .claude/settings.json at all in that case, so no
+// confirmation ever reached the phone once the user actually typed
+// `claude` - the hook-queue mechanism had nothing writing to it. Fixed by
+// always using Claude's own approvals object (queueFileFor,
+// describePrompt, parseLiveOptions, etc.) for the hook-queue path,
+// regardless of which adapter was spawned - the queue file is only ever
+// written by Claude Code's own hooks in the first place, so there's
+// nothing wrong with always registering them defensively. Harmless if the
+// user never runs `claude` in this session: the hook stays installed but
+// silent, since nothing ever calls it.
+const claudeAdapter = require('./cli-adapters/claude');
+const QUEUE_FILE = claudeAdapter.approvals.queueFileFor(CONFIG_DIR, WORKING_DIR);
+const PROCESSED_FILE = path.join(CONFIG_DIR, `processed-requests.${SESSION_ID}.json`);
+const POLL_INTERVAL_MS = 300;
+
+// Always registered now (see QUEUE_FILE's comment above) - covers both
+// `setu --cli claude` (adapter itself is Claude) and bare `setu` /
+// `setu --cli shell` followed by the user manually running `claude`
+// inside the bridged shell.
+{
+  const { ensureHooksRegistered } = require('./hooks');
+  ensureHooksRegistered(WORKING_DIR);
+}
+
+// Real config, from `setu pair` (src/config.js) - not a per-device-name
+// token file. Pairing is now a separate, one-time command (`setu pair`)
+// that must already have succeeded before this ever runs (checked above,
+// where the process exits early if config.deviceToken is missing) - so
+// unlike the PoC's ensurePaired(), there is no QR-pairing fallback here at
+// all. A session watcher's job is to watch a session, not to also be the
+// pairing flow; keeping them separate is what makes `setu` (bare) not
+// need a QR code/camera every single run.
+let deviceToken = config.deviceToken;
+let deviceId = null;
+let ws = null;
+let azureReady = false;
+const pendingPrompts = new Map();
+
+// Phase 6, Section 7: a rolling raw-byte scrollback so a phone that opens
+// terminal.html AFTER the session has been running for a while gets caught
+// up instantly via session.snapshot, instead of an empty screen. Capped so
+// this can't grow unbounded on a long session.
+const SCROLLBACK_MAX_BYTES = 200_000;
+let scrollback = '';
+function appendScrollback(chunk) {
+  scrollback += chunk;
+  if (scrollback.length > SCROLLBACK_MAX_BYTES) {
+    scrollback = scrollback.slice(scrollback.length - SCROLLBACK_MAX_BYTES);
+  }
+}
+
+let outputSeq = 0;
+
+// Real gap found by testing: this used to also track isFocused, gating
+// whether ptyProcess.onData's bytes were actually streamed live - removed
+// (see that call site's own comment) since it could silently drop real
+// conversation history from what's supposed to be a complete mirror.
+// Still polled regardless, though: deviceId doubles as a lightweight
+// heartbeat (see auth-server.js's /terminal/is-focused) - this call
+// already happens every 3s, so it's the natural place for the Devices
+// tab's "is this laptop actually alive right now" signal, and for
+// /live-sessions' per-session online status, instead of adding a second
+// poller just for those.
+async function pollFocus() {
+  try {
+    await fetch(
+      `${AUTH_SERVER}/terminal/is-focused?sessionId=${encodeURIComponent(SESSION_ID)}${deviceId ? `&deviceId=${encodeURIComponent(deviceId)}` : ''}`
+    );
+  } catch {
+    // Network hiccup - next poll (3s later) tries again; no local state
+    // depends on this succeeding anymore.
+  }
+}
+
+async function connectToAzure() {
+  // cliType lets Devices/Profile show which CLI this paired laptop is
+  // actually running (see auth-server.js's /device/connect handler and
+  // db.js's devices.cli_type column) - sent on every connect (not just
+  // pairing) since the SAME device row can legitimately run a different
+  // CLI across restarts (e.g. re-launched with --cli codex next time).
+  const res = await fetch(`${AUTH_SERVER}/device/connect`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${deviceToken}`, 'Content-Type': 'application/json' },
+    // sessionId here is what lets auth-server.js broadcast session.started
+    // immediately - see its own comment on why a session shouldn't have
+    // to wait for its first approval prompt to become visible on the
+    // phone. folderName (new) is the real product ask: the phone's own
+    // session lists only ever showed the raw sessionId (a hostname+hash+
+    // random string, meaningless to a real user) - just the WORKING_DIR's
+    // own folder name (not the full path - shorter, and doesn't expose
+    // this laptop's real directory structure to the phone/backend) lets
+    // someone actually tell which real project a session belongs to.
+    body: JSON.stringify({ cliType: adapter.id, sessionId: SESSION_ID, folderName: path.basename(WORKING_DIR) }),
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    // A 403 here means a real, durable plan-limit rejection (see
+    // auth-server.js's live-session-limit check) - retrying every 3s
+    // forever would just spam the same rejection, since nothing about
+    // THIS session changes by waiting (the fix is stopping an existing
+    // live session elsewhere, or upgrading, not a transient retry).
+    // Every other failure (network hiccup, a momentarily-down server)
+    // keeps the original retry behavior.
+    if (res.status === 403) {
+      console.error(`\n[supervisor] Connection rejected: ${err.error || 'the server declined this session.'}`);
+      log(`[supervisor] /device/connect rejected (403): ${err.error || 'no reason given'}`);
+      process.exit(1);
+    }
+    log(`[supervisor] /device/connect failed: ${err.error || res.status}`);
+    setTimeout(connectToAzure, 3000);
+    return;
+  }
+  const conn = await res.json();
+  deviceId = conn.deviceId;
+  log(`[supervisor] Connecting to Azure as device:${deviceId} (owner: ${conn.userId})...`);
+
+  ws = new WebSocket(conn.wssUrl);
+
+  ws.on('open', () => {
+    azureReady = true;
+    log('[supervisor] Connected to Azure. Ready to forward permission requests.');
+  });
+
+  ws.on('message', (raw) => {
+    let msg;
+    try {
+      msg = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    if (msg.type === 'confirmation.response') handleAzureDecision(msg);
+    if (msg.type === 'terminal.input' && msg.sessionId === SESSION_ID) {
+      // Section 11f Step 2: typed input from the phone, written to the PTY
+      // exactly like a local keystroke - this is the "arbitrary remote
+      // input" half of the DoD, not just approve/reject.
+      ptyProcess.write(msg.data);
+    }
+    if (msg.type === 'terminal.resize' && msg.sessionId === SESSION_ID) {
+      // Real bug found by testing: this used to call ptyProcess.resize()
+      // with the PHONE's dimensions, reflowing the one real, SHARED PTY to
+      // whatever narrow width the phone's screen happened to be - since a
+      // PTY has exactly one size, that visibly shrank and re-wrapped the
+      // laptop's own terminal the moment a phone connected/attached,
+      // corrupting the laptop-side view too, not just a phone-side
+      // cosmetic issue. Ignoring the phone's resize entirely is the
+      // correct fix: the laptop's real terminal keeps whatever size the
+      // person actually sitting at it set, and the phone's own
+      // xterm.js/WebView is responsible for wrapping/scrolling whatever
+      // width of output it receives to fit its own screen - the same
+      // model every real remote-terminal viewer (Termius, Blink) uses.
+      log(`[supervisor] Ignoring phone resize request (${msg.cols}x${msg.rows}) - the real PTY keeps its own size.`);
+    }
+    if (msg.type === 'session.attach' && msg.sessionId === SESSION_ID) {
+      // Section 7: a phone just opened/reopened the terminal view - hand it
+      // the scrollback immediately instead of leaving it blank until the
+      // next byte happens to be written.
+      sendSnapshot();
+    }
+    if (msg.type === 'git.diff.request' && msg.sessionId === SESSION_ID) {
+      // Roadmap #14 - git diff pane. Entirely independent of the running
+      // CLI adapter (Claude Code, Codex, generic) - this is a plain git
+      // operation against WORKING_DIR, not something any adapter needs to
+      // declare. Fire-and-forget from this handler's point of view; the
+      // real response goes back over its own relay endpoint (see
+      // sendGitDiff below), same pattern as sendSnapshot above.
+      sendGitDiff(msg.requestId);
+    }
+    if (msg.type === 'cross_session.inject' && msg.toSessionId === SESSION_ID) {
+      // Roadmap #3 - cross-session messaging. Note the field checked is
+      // toSessionId, not sessionId - this message genuinely has two
+      // different sessions in it (where it came FROM, where it's going
+      // TO), unlike every other message type in this file which only
+      // ever concerns THIS session.
+      //
+      // auth-server.js has ALREADY decided this is safe to inject
+      // (either nobody was watching, or the watching phone explicitly
+      // tapped Inject on the pending card) - this handler's only job is
+      // writing it in with a visible trace, never silently. A bracketed
+      // system-style line in the scrollback (not literally typed as if
+      // from the keyboard) is what makes an injected message
+      // distinguishable after the fact from something typed locally,
+      // even hours later when nobody remembers a message arrived.
+      const marker = `\r\n\x1b[38;2;155;185;235m[message from ${msg.fromDeviceName || 'another session'} / ${msg.fromSessionId}]\x1b[0m\r\n`;
+      ptyProcess.write(marker + msg.text + '\r');
+      log(`[supervisor] Injected cross-session message ${msg.messageId} from ${msg.fromSessionId}`);
+    }
+    if (msg.type === 'usage.refresh.request' && msg.sessionId === SESSION_ID) {
+      // Real feedback: the old 5-minute auto-timer (below, now removed)
+      // ran /cost in the user's own terminal on a schedule regardless of
+      // whether anyone was even looking at their phone - genuinely
+      // disruptive if someone's actively working locally and /cost's
+      // full-screen usage report suddenly takes over their session. This
+      // is the on-demand replacement: same triggerKeystrokes mechanism
+      // (still a real, visible command - that constraint hasn't changed,
+      // see cli-adapters/claude.js), but only ever fired when a phone
+      // explicitly asks for a fresh number, not on a timer nobody
+      // requested.
+      if (adapter.usage?.triggerKeystrokes && ptyProcess) {
+        ptyProcess.write(adapter.usage.triggerKeystrokes);
+        usageListenUntil = Date.now() + USAGE_LISTEN_WINDOW_MS;
+        log(`[supervisor] On-demand usage refresh requested for ${SESSION_ID}`);
+      }
+    }
+  });
+
+  ws.on('close', () => {
+    azureReady = false;
+    log('[supervisor] Azure connection closed. Reconnecting in 2s...');
+    setTimeout(connectToAzure, 2000);
+  });
+
+  ws.on('error', (err) => log('[supervisor] Azure socket error:', err.message));
+}
+
+async function sendSnapshot() {
+  try {
+    // preservedHistoryText() (see its own comment) is plain text, from
+    // BEFORE the current full-screen TUI took over - prepended ahead of
+    // the real, live raw-byte scrollback (still replayed as actual ANSI,
+    // unchanged), so a phone scrolling up sees the real startup banner/
+    // pre-TUI history too, not just whatever the current alt-screen
+    // buffer still happens to show.
+    const history = await preservedHistoryText();
+    const screen = history ? `${history}\n${scrollback}` : scrollback;
+    await fetch(`${AUTH_SERVER}/relay/terminal-snapshot`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deviceToken}` },
+      // cols/rows: the real PTY's actual geometry, so a phone attaching
+      // can lock its terminal to match instead of guessing its own size -
+      // see auth-server.js's matching comment for why this matters.
+      body: JSON.stringify({ sessionId: SESSION_ID, screen, cols: PTY_COLS, rows: PTY_ROWS }),
+    });
+  } catch (err) {
+    log('[supervisor] Failed to send snapshot:', err.message);
+  }
+}
+
+// Roadmap #14 - git diff pane. Entirely CLI-agnostic: this runs plain git
+// commands against WORKING_DIR regardless of which adapter (Claude Code,
+// Codex, generic) is driving the PTY - no adapter interface changes
+// needed, unlike the command palette (#6) which is genuinely adapter-
+// specific. `git diff` alone only shows changes to ALREADY-TRACKED files -
+// a brand-new file Claude/Codex just created shows up in `git status`
+// but produces no `git diff` output at all, which is exactly the case
+// most worth seeing remotely. `git diff --no-index /dev/null <file>`
+// against each untracked file (Windows git still accepts the POSIX
+// /dev/null form here) gets a real unified diff for those too, rather
+// than just a bare filename with no content shown.
+const GIT_TIMEOUT_MS = 15_000;
+// Web PubSub has a real per-message size ceiling - a genuinely huge diff
+// (a big refactor, an accidentally-modified generated/vendored file)
+// could otherwise silently fail to relay at all. Capping per-file and
+// truncating with a visible marker is safer than an unbounded payload -
+// the phone still sees SOMETHING and knows it's incomplete, rather than
+// the whole request quietly failing.
+const MAX_DIFF_CHARS_PER_FILE = 20_000;
+
+function capDiff(diffText) {
+  if (diffText.length <= MAX_DIFF_CHARS_PER_FILE) return { diff: diffText, truncated: false };
+  return {
+    diff: diffText.slice(0, MAX_DIFF_CHARS_PER_FILE) + '\n\n... (diff truncated - too large to send in full)',
+    truncated: true,
+  };
+}
+
+async function getGitDiff(cwd) {
+  // Not a git repo at all - a real, common, non-error state (the
+  // session's working directory might just never have been a repo) -
+  // distinguished from a real git failure so the phone can show an
+  // honest "not a git repository" message instead of a blank/broken pane.
+  try {
+    await execAsync('git rev-parse --is-inside-work-tree', { cwd, timeout: GIT_TIMEOUT_MS });
+  } catch {
+    return { isGitRepo: false, files: [] };
+  }
+
+  const files = [];
+
+  // --name-only first, then one `git diff` PER FILE - not a single
+  // combined `git diff` call. A combined diff mixes every modified
+  // file's text into one blob, which would make capDiff's per-file
+  // truncation (below) chop arbitrarily mid-file instead of cleanly
+  // per-file, and would collapse the phone's ability to show "which
+  // specific files changed" as a real list rather than one wall of text.
+  const { stdout: nameOnlyOut } = await execAsync('git diff --name-only', { cwd, timeout: GIT_TIMEOUT_MS });
+  const modifiedPaths = nameOnlyOut.split('\n').map((l) => l.trim()).filter(Boolean);
+
+  for (const relPath of modifiedPaths) {
+    try {
+      const { stdout } = await execFileAsync('git', ['diff', '--', relPath], { cwd, timeout: GIT_TIMEOUT_MS, maxBuffer: 10 * 1024 * 1024 });
+      if (stdout) files.push({ status: 'modified', path: relPath, ...capDiff(stdout) });
+    } catch (err) {
+      log(`[supervisor] git diff failed for modified file "${relPath}":`, err.message);
+    }
+  }
+
+  // --porcelain's stable, machine-parseable format - '??' is git's own
+  // marker for untracked. Path may be quoted (e.g. contains a space) -
+  // stripping surrounding quotes is enough for this app's own diff
+  // request, not a full porcelain parser.
+  const { stdout: statusOut } = await execAsync('git status --porcelain', { cwd, timeout: GIT_TIMEOUT_MS });
+  const untrackedPaths = statusOut
+    .split('\n')
+    .filter((line) => line.startsWith('?? '))
+    .map((line) => line.slice(3).trim().replace(/^"|"$/g, ''));
+
+  for (const relPath of untrackedPaths) {
+    try {
+      // --no-index compares two paths outside git's own tracking - the
+      // ONLY way to get a real content diff for a file git has never
+      // seen before. Exits non-zero whenever the files differ (which is
+      // always true here, comparing against nothing) - execFileAsync
+      // treats that as a rejected promise even though stdout still has
+      // the real diff text, so it's read off the caught error instead.
+      // execFile, not exec - relPath is a real filesystem path (from git
+      // status output, ultimately from whatever the CLI wrote to disk),
+      // passed as a real argv entry with no shell involved, not
+      // interpolated into a command string.
+      await execFileAsync('git', ['diff', '--no-index', '--', '/dev/null', relPath], { cwd, timeout: GIT_TIMEOUT_MS, maxBuffer: 5 * 1024 * 1024 });
+    } catch (err) {
+      if (err.stdout) files.push({ status: 'untracked', path: relPath, ...capDiff(err.stdout) });
+    }
+  }
+
+  return { isGitRepo: true, files, hasChanges: modifiedPaths.length > 0 || untrackedPaths.length > 0 };
+}
+
+async function sendGitDiff(requestId) {
+  try {
+    const result = await getGitDiff(WORKING_DIR);
+    await fetch(`${AUTH_SERVER}/relay/git-diff-response`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deviceToken}` },
+      body: JSON.stringify({ sessionId: SESSION_ID, requestId, ...result }),
+    });
+  } catch (err) {
+    log('[supervisor] Failed to compute/send git diff:', err.message);
+    // Best-effort error reporting to the phone - without this, a failed
+    // diff (e.g. git not on PATH) would leave the phone's request hanging
+    // forever with no explanation, rather than a clear error state.
+    fetch(`${AUTH_SERVER}/relay/git-diff-response`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deviceToken}` },
+      body: JSON.stringify({ sessionId: SESSION_ID, requestId, error: err.message }),
+    }).catch(() => {});
+  }
+}
+
+// Real bug #1, found by testing: ptyProcess.onData fires rapidly and
+// synchronously for every PTY chunk, but each streamOutput() call did its
+// own independent, un-awaited fetch(). Nothing guaranteed those HTTP
+// requests RESOLVED in the order they were SENT - a later chunk's request
+// could finish first under normal network jitter, and terminal.html just
+// wrote whatever arrived with no reordering. Symptom: words/lines rendered
+// interleaved, e.g. "Listingserver.js," instead of two separate lines.
+//
+// First fix was one fetch() per chunk, strictly serialized - correct
+// order, but real bug #2: a single Claude Code response can produce MANY
+// small PTY chunks, and awaiting a full HTTP round trip before sending the
+// next one turned a live stream into a slow drip - observed as a ~2
+// minute lag before anything appeared, for output that should stream in
+// under a second.
+//
+// Actual fix: batch. Chunks accumulate in a buffer; a short timer (or the
+// buffer growing large) triggers ONE combined send instead of one send
+// per chunk - still exactly one in-flight request at a time (order
+// preserved by construction, same as before), but far fewer round trips.
+let outputBuffer = '';
+let flushTimer = null;
+let sendInFlight = Promise.resolve();
+const BATCH_WINDOW_MS = 40;
+const BATCH_MAX_BYTES = 8000; // flush early if a burst gets large, rather than waiting the full window
+
+function streamOutput(chunk) {
+  outputBuffer += chunk;
+  if (outputBuffer.length >= BATCH_MAX_BYTES) {
+    scheduleFlush(0);
+  } else if (!flushTimer) {
+    scheduleFlush(BATCH_WINDOW_MS);
+  }
+}
+
+function scheduleFlush(delayMs) {
+  clearTimeout(flushTimer);
+  flushTimer = setTimeout(flushOutputBuffer, delayMs);
+}
+
+function flushOutputBuffer() {
+  flushTimer = null;
+  if (!outputBuffer) return;
+
+  const batch = outputBuffer;
+  outputBuffer = '';
+
+  // Still serialized against any send already in flight, so batches
+  // themselves can never arrive out of order relative to each other.
+  sendInFlight = sendInFlight.then(async () => {
+    try {
+      await fetch(`${AUTH_SERVER}/relay/terminal-output`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deviceToken}` },
+        body: JSON.stringify({ sessionId: SESSION_ID, seq: ++outputSeq, data: batch }),
+      });
+    } catch (err) {
+      // A dropped terminal.output batch isn't fatal the way a dropped
+      // confirmation would be - the next batch (or a fresh session.attach
+      // snapshot) catches the view back up, so just log and move on.
+      log('[supervisor] Failed to stream output batch:', err.message);
+    }
+  });
+}
+
+function handleAzureDecision(msg) {
+  const pending = pendingPrompts.get(msg.promptId);
+  if (!pending) {
+    log(`[supervisor] Got a decision for unknown promptId ${msg.promptId} - already handled or unrecognized, ignoring.`);
+    return;
+  }
+
+  const chosen = pending.options?.[msg.optionIndex];
+  const keystroke = chosen ? chosen.keystroke : '\x1b';
+
+  // Real bug found by testing: "Type something" (the phone's own
+  // keepPending path - see ConfirmationsScreen.js) only opens Claude
+  // Code's freeform input, it isn't a real decision - but this used to
+  // unconditionally delete the promptId from pendingPrompts regardless of
+  // WHICH option was chosen. That meant tapping a REAL option (e.g.
+  // "Empty file") on the same still-visible card right after "Type
+  // something" found nothing left to act on - the keystroke silently
+  // never reached the terminal. Only delete when the actual decision was
+  // a real one, so the same card can still be resolved for real
+  // afterward.
+  if (chosen?.label !== 'Type something') {
+    pendingPrompts.delete(msg.promptId);
+  }
+
+  log(`[supervisor] Azure decision for ${msg.promptId}: "${chosen ? chosen.label : 'unknown'}". Injecting keystroke "${keystroke}"...`);
+  // Real bug found by testing: Claude Code's inline permission menu
+  // (1/2/3, or a bare Esc to reject) selects AND confirms on the single
+  // keypress alone - it's a hotkey menu, not a typed line. Appending '\r'
+  // unconditionally sent a second, separate Enter right after the
+  // selection, which landed in whatever input the UI advanced to next
+  // (the freeform chat box) - visible as a stray "1" typed into chat,
+  // sometimes racing with the terminal's own answer if you'd already
+  // resolved the same prompt locally before the phone's decision arrived.
+  ptyProcess.write(keystroke);
+  fs.appendFileSync(
+    PROCESSED_FILE,
+    JSON.stringify({ ...pending, chosenLabel: chosen?.label, injectedAt: new Date().toISOString() }) + '\n'
+  );
+}
+
+// Real bug found by testing: these used to be hardcoded to 120x30
+// regardless of the user's REAL terminal window size - on any window
+// bigger than that (the normal case for a maximized/large terminal),
+// the PTY was spawned SMALLER than the window showing it, leaving real,
+// visible blank space in the laptop's own terminal below and to the
+// right of the actual PTY content - not a phone-side rendering bug at
+// all, a genuine laptop-side geometry mismatch. process.stdout.columns/
+// rows reflect the REAL terminal's actual current size at the moment
+// `setu` starts (falling back to the old 120x30 only if those aren't
+// available - e.g. output piped to a file, not a real TTY). Still a
+// FIXED size after this point, same reasoning as before (not read back
+// off ptyProcess after spawn, never resized again - see the
+// terminal.resize handler above for why phone-side resize requests are
+// still correctly ignored): just a better, size-aware fixed size instead
+// of an arbitrary guessed one.
+const PTY_COLS = process.stdout.columns || 120;
+const PTY_ROWS = process.stdout.rows || 30;
+
+// Real gap found by testing: Claude Code's full-screen TUI does its own
+// absolute-cursor-positioning redraws, which means the raw scrollback
+// STRING above (appendScrollback) is not a reliable transcript - earlier
+// bytes get visually overwritten by later ones at the byte level (the
+// same reason Claude Code's own startup banner disappeared from the
+// phone's scrollback once real conversation started: the banner's bytes
+// were still THERE in the string, but replaying them through a FRESH
+// xterm instance just re-runs the same overwrites, landing on the same
+// final picture). The real fix: @xterm/headless is xterm.js's own
+// official Node.js package - running a real terminal emulator here,
+// fed the IDENTICAL bytes the real PTY produces, maintains an actual,
+// always-correct RENDERED buffer, not just a raw byte log. Critically,
+// it tracks the NORMAL and ALTERNATE screen buffers separately (see
+// node_modules/@xterm/headless/typings - IBuffer.type) - a full-screen
+// TUI like Claude Code switches to the alternate buffer when it starts
+// (standard terminal behavior every full-screen app relies on), which
+// means whatever was in the NORMAL buffer before that (the real startup
+// banner, or any plain shell output before Claude Code launched) is
+// preserved completely untouched underneath, not overwritten - it's
+// just hidden while the alt buffer is active. Reading the normal buffer
+// independently (see preservedHistoryText below) means no "detect the
+// redraw" logic is needed at all.
+// allowProposedApi: true - buffer.normal/buffer.alternate are marked
+// EXPERIMENTAL in xterm.js's own typings and throw at runtime without
+// this explicit opt-in (confirmed directly: "You must set the
+// allowProposedApi option to true to use proposed API").
+const headlessTerm = new HeadlessTerminal({ cols: PTY_COLS, rows: PTY_ROWS, scrollback: SCROLLBACK_MAX_BYTES, allowProposedApi: true });
+
+// Real bug found by testing: term.write() is ASYNCHRONOUS - reading the
+// buffer immediately after calling it (no callback, no await) reads
+// STALE/EMPTY content, confirmed directly against a real minimal
+// reproduction. ptyProcess.onData can fire many times per second, so
+// awaiting every single write here would be wasteful - instead, chain
+// each write's completion onto the previous one (same pattern this file
+// already uses for sendInFlight's own output batching), and have
+// anything that needs to READ the buffer (preservedHistoryText, called
+// from sendSnapshot) await this chain first, so it's guaranteed caught
+// up by the time anyone actually reads it - without slowing down the hot
+// onData path at all.
+let headlessWriteChain = Promise.resolve();
+function writeToHeadlessTerm(data) {
+  headlessWriteChain = headlessWriteChain.then(
+    () => new Promise((resolve) => headlessTerm.write(data, resolve))
+  );
+}
+async function awaitHeadlessTermCaughtUp() {
+  await headlessWriteChain;
+}
+
+// Renders a buffer's lines back to plain text - translateToString(true)
+// trims trailing whitespace per line, same as how a real terminal looks
+// when you select and copy its text.
+function bufferToText(buffer) {
+  const lines = [];
+  for (let y = 0; y < buffer.length; y++) {
+    const line = buffer.getLine(y);
+    if (line) lines.push(line.translateToString(true));
+  }
+  return lines.join('\n');
+}
+
+// Real product ask: scrolling up on the phone should show EVERYTHING,
+// including content from before the current alt-screen TUI took over.
+// Deliberately only ever returns the PRESERVED NORMAL buffer (the
+// banner/pre-TUI history) as plain text, to be PREPENDED before the
+// existing raw-byte scrollback (see sendSnapshot) - never a replacement
+// for it. The live/current content still replays as real ANSI bytes
+// through the existing mechanism (term.write() of the raw scrollback
+// string), which correctly handles Claude Code's own absolute cursor
+// positioning; converting that part to plain text too would lose
+// coloring and risk misaligning the cursor position live streaming
+// continues from afterward. When the CLI is still on the plain normal
+// buffer (hasn't switched to an alt screen at all - e.g. a plain shell
+// with no full-screen TUI running), buffer.normal IS buffer.active, so
+// this would just duplicate the live scrollback - returns '' in that
+// case since there's nothing EXTRA to prepend.
+async function preservedHistoryText() {
+  // Must wait for every queued write to actually apply first - see
+  // writeToHeadlessTerm's own comment on why reading right after a raw
+  // write would see stale/empty content.
+  await awaitHeadlessTermCaughtUp();
+  if (headlessTerm.buffer.active.type === 'normal') return '';
+  return bufferToText(headlessTerm.buffer.normal);
+}
+
+let processedLines = 0;
+let ptyProcess = null;
+let pollTimer = null;
+let focusTimer = null;
+// No longer an interval (see the on-demand usage.refresh.request handler
+// below) - kept as a variable only so ptyProcess.onExit's cleanup has
+// something harmless to clearInterval() on, in case a future change ever
+// reintroduces a real timer here.
+let usageTimer = null;
+// Only actually parse PTY output for usage data while this is in the
+// future - set a few seconds out each time triggerKeystrokes is sent
+// (see below), cleared back to 0 the moment a match is found or the
+// window lapses. See the onData handler's usage-polling comment for why
+// this window exists at all instead of parsing every chunk forever.
+let usageListenUntil = 0;
+const USAGE_LISTEN_WINDOW_MS = 10_000;
+// Codex-shape usage de-dup (no trigger keystrokes, and no reliable
+// persistent status line to gate a check on - see cli-adapters/codex.js
+// and the onData handler's comment on why every chunk gets checked) -
+// only reports to the Backend when the parsed percentage actually
+// CHANGES, not on every chunk that happens to still show the same
+// still-rendered text.
+let lastReportedCodexContextPct = null;
+// Which onboarding gate (by `reason`) was last auto-answered - null once
+// no gate is currently on-screen. Identity-based, not time-based (see the
+// onData handler's comment for why a timer cooldown re-fired incorrectly
+// in testing) - re-answers only when a DIFFERENT gate appears, or the
+// same one reappears after genuinely clearing.
+let lastOnboardingAnswered = null;
+// De-dupes a Codex approval prompt that's still on-screen (and therefore
+// still matching detectApproval) across many chunks, vs. a genuinely NEW
+// prompt appearing - see cli-adapters/codex.js's detectApproval comment.
+let lastApprovalFingerprint = null;
+
+// Best-effort - a dropped usage report just means Profile/Devices show a
+// slightly stale number until the next successful poll, same "core
+// function survives an enhancement failing" principle used everywhere
+// else in this app (push notifications, profile fetch, etc.).
+async function reportUsage(parsed) {
+  if (!deviceId) return;
+  try {
+    await fetch(`${AUTH_SERVER}/device/usage`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deviceToken}` },
+      body: JSON.stringify({
+        cliType: adapter.id,
+        totalTokens: parsed.totalTokens,
+        inputTokens: parsed.inputTokens,
+        outputTokens: parsed.outputTokens,
+        costUsd: parsed.costUsd,
+        contextUsedPct: parsed.sessionContextUsedPct,
+        weekUsedPct: parsed.weekUsedPct,
+        sessionResetsAt: parsed.sessionResetsAt,
+        weekResetsAt: parsed.weekResetsAt,
+      }),
+    });
+    log(`[supervisor] Reported usage: ${JSON.stringify(parsed)}`);
+  } catch (err) {
+    log('[supervisor] Failed to report usage:', err.message);
+  }
+}
+
+// Laptop battery-low warning - reads Windows' own Win32_Battery WMI
+// class via a PowerShell one-liner (verified live: returns a real
+// EstimatedChargeRemaining percentage on a real laptop; returns NOTHING
+// at all on a desktop with no battery, which is exactly the "just skip
+// this feature there" behavior wanted - no separate desktop-detection
+// logic needed). Not a Node package - node's own APIs have no battery
+// reading at all, and this needs zero new dependencies.
+const BATTERY_LOW_THRESHOLD_PCT = 20;
+const BATTERY_POLL_INTERVAL_MS = 5 * 60_000;
+let batteryTimer = null;
+// Tracks whether the LAST reading was already below the threshold, so
+// the alert fires once per crossing (unplugged and draining past 20%)
+// rather than every single 5-minute poll for as long as the battery
+// stays low - repeating the same "your laptop is low" push every 5
+// minutes while someone's already aware and mid-charge (or just hasn't
+// gotten to a charger yet) would be pure noise, not a useful alert.
+let wasBatteryLow = false;
+
+function checkBatteryOnce() {
+  exec(
+    'powershell -NoProfile -Command "Get-CimInstance -ClassName Win32_Battery | Select-Object -ExpandProperty EstimatedChargeRemaining"',
+    { timeout: 10_000 },
+    (err, stdout) => {
+      if (err) return; // no battery (desktop), PowerShell unavailable, etc. - silently skip, not an error worth logging every 5 minutes
+      const pct = Number(String(stdout).trim());
+      if (!Number.isFinite(pct)) return;
+
+      const isLow = pct < BATTERY_LOW_THRESHOLD_PCT;
+      if (isLow && !wasBatteryLow) {
+        log(`[supervisor] Battery low: ${pct}% - sending alert`);
+        if (deviceId) {
+          fetch(`${AUTH_SERVER}/device/battery-alert`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deviceToken}` },
+            body: JSON.stringify({ batteryPct: pct }),
+          }).catch((fetchErr) => log('[supervisor] Failed to send battery alert:', fetchErr.message));
+        }
+      }
+      wasBatteryLow = isLow;
+    }
+  );
+}
+
+async function pollForRequests() {
+  // No queue file for this adapter (approvals: null - generic CLI or
+  // Codex's plain-PTY mode) means there is nothing to poll: this CLI has
+  // no known mechanism to report a prompt before it happens, so the human
+  // just answers it directly in the mirrored terminal, with no
+  // structured Confirmations card ever generated for it.
+  if (!azureReady || !QUEUE_FILE) return;
+
+  let raw;
+  try {
+    raw = fs.readFileSync(QUEUE_FILE, 'utf8');
+  } catch {
+    return;
+  }
+
+  const lines = raw.split('\n').filter(Boolean);
+  if (lines.length <= processedLines) return;
+
+  const newLines = lines.slice(processedLines);
+  processedLines = lines.length;
+
+  for (const line of newLines) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (event.hook_event_name === 'PostToolUse') {
+      resolveIfPending(event);
+      continue;
+    }
+
+    const options = await resolveRealOptions(event);
+    const text = claudeAdapter.approvals.describePrompt(event);
+    await relayApproval(event, options, text);
+  }
+}
+
+// Real bug found by testing: getDialogOptions' Write/Bash/PowerShell
+// option sets are a hardcoded guess (the hook payload never carries the
+// real menu for those tool types) - it drifted the moment Claude Code
+// added a 4th choice ("switch to auto mode") to its own menu, showing the
+// phone 3 buttons for a real 4-option prompt. adapter.approvals.
+// parseLiveOptions reads the ACTUAL rendered menu from the terminal
+// instead, but PermissionRequest fires BEFORE the prompt is drawn on
+// screen (see this file's own top comment) - so a short retry loop here
+// gives the PTY time to actually render it before ever falling back to
+// the static guess. Skipped entirely for AskUserQuestion, whose real
+// options DO come through the hook payload already (getDialogOptions
+// reads tool_input.questions[0].options directly) - no need to wait on
+// a screen render for a case that's already exact.
+async function resolveRealOptions(event) {
+  if (!claudeAdapter.approvals.parseLiveOptions || event.tool_name === 'AskUserQuestion') {
+    return claudeAdapter.approvals.getDialogOptions(event);
+  }
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const live = claudeAdapter.approvals.parseLiveOptions(scrollback.slice(-3000));
+    if (live) return live;
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  log('[supervisor] Live menu did not render in time - falling back to the static guess for this prompt.');
+  return claudeAdapter.approvals.getDialogOptions(event);
+}
+
+// Real gap found by testing: a prompt answered directly at the laptop's
+// own keyboard (never via the phone) left its card stuck "pending"
+// forever on the phone, since nothing ever told the Backend the tool
+// actually ran. PostToolUse only fires once a tool call actually
+// executes - which can only happen after ITS permission prompt was
+// answered somehow, locally or remotely - so a PostToolUse for the same
+// tool_name + session_id we're still holding pending is real proof that
+// prompt got resolved. Matched on tool_name + session_id rather than
+// exact tool_input equality - Claude Code's PostToolUse payload doesn't
+// echo back tool_input in a byte-identical shape to PermissionRequest's,
+// and two DIFFERENT pending prompts for the exact same tool_name in the
+// exact same session (e.g. two Bash calls in a row) resolve in the order
+// they were opened either way, so ambiguity here is harmless.
+function reportResolvedLocally(promptId, reason) {
+  log(`[supervisor] ${promptId} resolved locally (${reason}) - notifying Backend.`);
+  fetch(`${AUTH_SERVER}/relay/confirmation-resolved-locally`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deviceToken}` },
+    body: JSON.stringify({ sessionId: SESSION_ID, promptId }),
+  }).catch((err) => log('[supervisor] Failed to report local resolution:', err.message));
+}
+
+// Extracts a real identity for one AskUserQuestion prompt - its actual
+// question text, not just "this session asked SOMETHING". Undefined for
+// every other tool_name, which is fine: those never fire two pending
+// prompts back-to-back for the same session the way AskUserQuestion can
+// (see resolveIfPending's own comment).
+function askUserQuestionKey(event) {
+  return event.tool_input?.questions?.[0]?.question;
+}
+
+function resolveIfPending(postToolUseEvent) {
+  // Real bug found by testing: matching on tool_name + session_id alone
+  // resolved whichever pending prompt happened to be found FIRST in the
+  // Map, not necessarily the one that actually just got answered.
+  // AskUserQuestion specifically can have two genuinely different
+  // pending questions in flight for the SAME session at once - rejecting
+  // one often makes Claude Code immediately ask a related follow-up
+  // question before the first prompt's PostToolUse even fires - so this
+  // ambiguity isn't a rare edge case for it, it's a real, observed
+  // sequence. Matching on the actual question text (when available)
+  // instead of just tool_name+session_id resolves the CORRECT one even
+  // when two are pending at once; falls back to the old less-precise
+  // match for every other tool_name, where this ambiguity doesn't arise.
+  const postKey = askUserQuestionKey(postToolUseEvent);
+  for (const [promptId, pending] of pendingPrompts.entries()) {
+    if (pending.session_id !== postToolUseEvent.session_id) continue;
+    if (pending.tool_name !== postToolUseEvent.tool_name) continue;
+    if (postKey && askUserQuestionKey(pending) && askUserQuestionKey(pending) !== postKey) continue;
+    pendingPrompts.delete(promptId);
+    reportResolvedLocally(promptId, `PostToolUse for ${postToolUseEvent.tool_name}`);
+    return;
+  }
+}
+
+// Real gap found by testing: an APPROVED prompt gets a PostToolUse event
+// (resolveIfPending above catches it), but a REJECTED/interrupted one
+// never does - the tool call never ran, so there's no "it ran" signal to
+// observe at all. The one thing that IS still true: Claude Code only ever
+// has ONE open prompt per session at a time, so a genuinely NEW
+// PermissionRequest arriving for a session is real proof any OLDER
+// pending prompt in that same session is no longer live - it was
+// rejected, interrupted, or otherwise handled, by definition, since
+// Claude Code moved on. Called right before relaying the new prompt.
+function resolveStaleForSession(sessionId, reason = 'a newer prompt arrived for the same session') {
+  for (const [promptId, pending] of pendingPrompts.entries()) {
+    if (pending.session_id === sessionId) {
+      pendingPrompts.delete(promptId);
+      reportResolvedLocally(promptId, reason);
+    }
+  }
+}
+
+// Shared by both approval-detection mechanisms (Claude Code's hook-queue
+// polling above, and Codex's PTY-scrape detection below) - same
+// pendingPrompts bookkeeping and /relay/confirmation-request call either
+// way, since from the phone's perspective a confirmation card looks
+// identical regardless of which CLI/detection method produced it.
+async function relayApproval(event, options, text) {
+  // See resolveStaleForSession's own comment - a new prompt for this
+  // session means any older one we're still holding pending is stale.
+  resolveStaleForSession(event.session_id);
+
+  // Real bug found by testing: Date.now() alone collides when two
+  // separate supervisor processes (different laptops/sessions) detect a
+  // prompt in the same millisecond - the phone's seenPromptIds dedup then
+  // treats the second, genuinely different prompt as a duplicate of the
+  // first and drops it, or conflates their responses. DEVICE_NAME makes
+  // the id unique per-process even under a same-millisecond collision.
+  const promptId = `p-${DEVICE_NAME}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  pendingPrompts.set(promptId, { ...event, options });
+
+  log(`[supervisor] Detected approval prompt: ${text}`);
+  log(`[supervisor] Relaying to auth-server as promptId=${promptId}...`);
+
+  try {
+    const res = await fetch(`${AUTH_SERVER}/relay/confirmation-request`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deviceToken}` },
+      body: JSON.stringify({
+        sessionId: SESSION_ID,
+        promptId,
+        text,
+        options: options.map(({ label, style }) => ({ label, style })),
+      }),
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      log('[supervisor] Relay failed:', err.error || res.status);
+    }
+  } catch (err) {
+    log('[supervisor] Failed to reach auth-server:', err.message);
+  }
+
+  // Real gap found by testing: an APPROVED Bash/Write/PowerShell prompt
+  // gets a PostToolUse event (resolveIfPending), but a REJECTED one
+  // doesn't - the tool never ran, so there's nothing to hook. Several
+  // attempts at matching Claude Code's own rejection wording proved
+  // unreliable (see cli-adapters/claude.js's isMenuStillOnScreen
+  // comment). This instead polls whether the SAME menu is still
+  // physically on screen - once it isn't, a decision happened (approved,
+  // rejected, or interrupted, doesn't matter which) and the prompt is
+  // resolved. Skipped for AskUserQuestion, which already resolves
+  // reliably and precisely via PostToolUse's exact question-text match -
+  // this cruder "is ANY proceed-style menu gone" check would be a
+  // downgrade for that tool_name, not an improvement.
+  if (claudeAdapter.approvals.isMenuStillOnScreen && event.tool_name !== 'AskUserQuestion') {
+    watchForMenuDisappearance(promptId);
+  }
+}
+
+// Polls every 500ms for up to 5 minutes (a real user can genuinely take
+// that long to decide) - stops early the moment isMenuStillOnScreen
+// returns false, or the moment this promptId is no longer pending at all
+// (already resolved through the phone, PostToolUse, or a newer prompt -
+// no point continuing to poll something that's already been handled).
+async function watchForMenuDisappearance(promptId) {
+  const deadline = Date.now() + 5 * 60_000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 500));
+    if (!pendingPrompts.has(promptId)) return; // already resolved some other way
+    if (!claudeAdapter.approvals.isMenuStillOnScreen(scrollback.slice(-3000))) {
+      pendingPrompts.delete(promptId);
+      reportResolvedLocally(promptId, 'the on-screen menu is gone - resolved locally (approved, rejected, or interrupted)');
+      return;
+    }
+  }
+}
+
+// Codex-specific entry point (cli-adapters/codex.js's sourceMode:
+// 'pty-scrape') - called from the onData handler once detectApproval
+// finds a NEW (not-yet-seen) prompt in the scrollback window.
+function handleDetectedApproval(detected) {
+  const options = adapter.approvals.getDialogOptions(detected);
+  const text = adapter.approvals.describePrompt(detected);
+  relayApproval(detected, options, text);
+}
+
+// Real gap found by testing: a laptop-side warning used to fire here any
+// time another setu was already running for the same folder - built
+// before the real enforcement below existed, to catch accidental
+// duplicates. Removed: running a 2nd session in the same folder is
+// explicitly an ALLOWED product rule (2 live sessions per device - see
+// auth-server.js's PLAN_LIMITS.maxLiveSessions, now scoped per-device),
+// so warning about it read alarmingly for something that's actually
+// fine, and the real safety net now exists at the backend: /device/
+// connect itself rejects a 3rd session for this device with a clear
+// error message, before it ever gets a usable connection - a stronger,
+// more reliable guarantee than a laptop-side warning a user could miss
+// or click past anyway.
+async function main() {
+  if (QUEUE_FILE) fs.writeFileSync(QUEUE_FILE, '');
+  fs.writeFileSync(PROCESSED_FILE, '');
+
+  console.log(`\n[supervisor] Spawning ${adapter.displayName} in a PTY (device=${DEVICE_NAME}, session=${SESSION_ID}, cwd=${WORKING_DIR})...`);
+
+  ptyProcess = pty.spawn(adapter.spawn.command, adapter.spawn.args(WORKING_DIR), {
+    name: 'xterm-color',
+    cols: PTY_COLS,
+    rows: PTY_ROWS,
+    cwd: WORKING_DIR,
+    env: process.env,
+  });
+
+  ptyProcess.onData((data) => {
+    process.stdout.write(data);
+
+    // Section 4c call ① -> the scrollback (Section 7) is kept regardless
+    // of whether anyone's watching, so a phone attaching later still gets
+    // real history, not just whatever arrives after it connects.
+    appendScrollback(data);
+    // Fed the IDENTICAL bytes as the real PTY, in the same order - see
+    // headlessTerm's own declaration comment for why this (not the raw
+    // scrollback string above) is what makes a genuinely complete
+    // transcript possible. writeToHeadlessTerm (not a direct .write()
+    // call) queues this safely - see its own comment on why reading the
+    // buffer right after a raw write would see stale/empty content.
+    writeToHeadlessTerm(data);
+
+    // Real gap found by testing: gating live streaming on isFocused (only
+    // spend a request if a phone is CURRENTLY looking at this session)
+    // meant anything that happened while the user was on a different tab,
+    // or had the app backgrounded, was never streamed live - only
+    // recoverable later via the one-time scrollback snapshot on next
+    // attach, which truncates past SCROLLBACK_MAX_BYTES and in practice
+    // left real conversation history missing from what should be a
+    // complete mirror. The whole point of this feature is "the phone's
+    // terminal shows the exact same thing scrolling up as the real
+    // laptop terminal does" - a cost optimization that can silently drop
+    // real content contradicts that, so this now always streams
+    // regardless of isFocused (kept only for the Devices tab's online
+    // heartbeat - see pollFocus's own comment).
+    streamOutput(data);
+
+    // Usage polling (see cli-adapters/claude.js) - only ever active for
+    // an adapter that defines usage.parseFromOutput; every other adapter
+    // leaves usageState untouched and Devices/Profile just show nothing
+    // for token usage, same "optional richness" pattern as approvals.
+    //
+    // Real bug found by testing: parsing each raw `data` chunk in
+    // isolation silently failed most of the time - a PTY streams output
+    // in small, arbitrarily-split pieces (this is exactly why
+    // TerminalScreen.js's own out-of-order chunk sequencing exists), and
+    // `/cost`'s multi-line render (the "58% used" text, the "Resets ..."
+    // line right after it) is not guaranteed to land in one chunk. A
+    // regex against a single chunk that happens to end mid-render just
+    // never matches, with no error - it looked like "auto-refresh isn't
+    // working" from the phone side when the real gap was here. Matching
+    // against a trailing window of the already-accumulated scrollback
+    // instead guarantees the full rendered output is visible regardless
+    // of how the PTY happened to chunk it.
+    //
+    // Gated to a short window after triggerKeystrokes was actually sent
+    // (usageListenUntil) rather than running on every chunk for the
+    // entire session - re-running 6 regexes against a 4KB window on
+    // every single byte the CLI ever prints (a long response streams
+    // MANY chunks) would be pure waste outside the brief moment right
+    // after we actually asked for a fresh reading.
+    if (adapter.usage?.parseFromOutput) {
+      if (adapter.usage.triggerKeystrokes) {
+        // Claude Code shape: only worth checking right after we actually
+        // asked for a fresh reading (see usageListenUntil above).
+        if (Date.now() < usageListenUntil) {
+          const recentWindow = scrollback.slice(-4000);
+          const parsed = adapter.usage.parseFromOutput(recentWindow);
+          if (parsed) {
+            reportUsage(parsed);
+            usageListenUntil = 0; // got it - stop checking until the next trigger
+            // Real feedback: /cost's full-screen usage report otherwise
+            // sits visible in the person's own terminal after an
+            // on-demand refresh, showing exactly what just happened
+            // behind the scenes - not something a remote refresh should
+            // leave lying around for whoever's physically at the laptop
+            // to wonder about. Esc is the standard way Claude Code's own
+            // full-screen views (Usage/Config/Status) are dismissed
+            // elsewhere in this CLI - NOT independently re-verified
+            // against this exact /cost screen in this session, so treat
+            // this as the first real test of that assumption, not a
+            // confirmed fact. Same mechanism as the approval
+            // auto-injection above (ptyProcess.write with a real
+            // keystroke), nothing new.
+            ptyProcess.write('\x1b');
+          }
+        }
+      } else {
+        // Codex shape (cli-adapters/codex.js) - real bug found by live
+        // testing: "% context left" is NOT a persistent, always-visible
+        // status line the way the first version of this comment assumed.
+        // It only renders for a brief moment right after a turn finishes,
+        // while the input box is idle-focused ("tab to queue message ...
+        // NN% context left") - gone again as soon as the next prompt is
+        // typed or another turn starts. A 5-minute throttle (copied from
+        // Claude Code's shape, where /cost is manually triggered and its
+        // output persists on screen) missed this window almost every
+        // time in testing - across several real approved turns, usage
+        // was never once recorded, because the 5-minute cooldown was
+        // still active during the one brief moment the text existed.
+        // There's no reliable trigger to key a narrower check off (see
+        // README.md), so the only option that actually works is checking
+        // EVERY chunk - affordable here since this is one small regex,
+        // not Claude Code's six-regex /cost parse.
+        const recentWindow = scrollback.slice(-4000);
+        const parsed = adapter.usage.parseFromOutput(recentWindow);
+        // De-duped by the actual percentage, not a timer - the same
+        // "100% context left" render can appear across several
+        // consecutive chunks before Codex's next redraw changes it,
+        // and reporting on every one of those would spam
+        // /device/usage with identical, redundant POSTs.
+        if (parsed && parsed.sessionContextUsedPct !== lastReportedCodexContextPct) {
+          lastReportedCodexContextPct = parsed.sessionContextUsedPct;
+          reportUsage(parsed);
+        }
+      }
+    }
+
+    // Approval detection for an adapter using PTY-text scraping instead
+    // of a hook queue (see cli-adapters/codex.js's sourceMode) - Claude
+    // Code's approvals flow through pollForRequests/QUEUE_FILE instead;
+    // this branch is a no-op for any adapter without approvals.sourceMode
+    // === 'pty-scrape' (Claude Code, generic, or an adapter with
+    // approvals: null entirely).
+    if (adapter.approvals?.sourceMode === 'pty-scrape' && azureReady) {
+      const recentWindow = scrollback.slice(-4000);
+
+      const onboarding = adapter.approvals.autoAnswerOnboarding(recentWindow);
+      if (onboarding && onboarding.reason !== lastOnboardingAnswered) {
+        // Real bug found by testing: a time-based cooldown (originally
+        // 2s) re-fired repeatedly on the SAME still-on-screen gate,
+        // sometimes minutes apart - the screen can stay rendered in the
+        // scrollback window far longer than any short cooldown, since
+        // it's real elapsed wall-clock time until Codex actually
+        // processes the keystroke and redraws, not a fixed delay.
+        // Tracking WHICH gate (by reason) was last answered instead of a
+        // timer means it's answered exactly once and never re-sent until
+        // a genuinely DIFFERENT gate (or none) appears - each extra
+        // stray keypress risked landing on the real chat input once the
+        // gate actually cleared.
+        lastOnboardingAnswered = onboarding.reason;
+        log(`[supervisor] Auto-answering Codex onboarding gate: ${onboarding.reason}`);
+        ptyProcess.write(onboarding.keystrokes);
+      } else if (!onboarding) {
+        lastOnboardingAnswered = null; // gate cleared - a future recurrence should be answered again
+        const detected = adapter.approvals.detectApproval(recentWindow);
+        if (detected && detected.fingerprint !== lastApprovalFingerprint) {
+          lastApprovalFingerprint = detected.fingerprint;
+          handleDetectedApproval(detected);
+        }
+      }
+    }
+
+    // Real gap found by testing: an APPROVED prompt gets a real
+    // PostToolUse hook event to key off of (resolveIfPending above), but
+    // a REJECTED/interrupted one produces no hook event at all - the tool
+    // call never ran. A PTY-text-scan for Claude Code's own "Interrupted..."
+    // wording was tried here and removed again - real captured terminal
+    // output across several live rejection tests never actually contained
+    // that literal text in a form the regex could reliably match (Claude
+    // Code doesn't render it consistently enough to key off of). Left as
+    // the reliable fallback instead: a rejected prompt clears once ANOTHER
+    // prompt arrives for the same session (resolveStaleForSession, called
+    // from relayApproval below) - not instant, but proven correct across
+    // testing, unlike the PTY-scan attempt.
+  });
+
+  ptyProcess.onExit(({ exitCode }) => {
+    console.log(`\n[supervisor] ${adapter.displayName} exited with code ${exitCode}`);
+    if (pollTimer) clearInterval(pollTimer);
+    if (focusTimer) clearInterval(focusTimer);
+    if (usageTimer) clearInterval(usageTimer);
+    if (batteryTimer) clearInterval(batteryTimer);
+    if (ws) ws.close();
+    process.exit(exitCode || 0);
+  });
+
+  // Real feedback: an automatic timer used to run here (every 5 minutes,
+  // unconditionally) asking the session for a fresh /cost reading -
+  // removed after live testing showed it genuinely disrupting someone
+  // actively working at the laptop, taking over their visible terminal
+  // with a full-screen usage report on a schedule nobody asked for. Usage
+  // now only ever refreshes on an explicit request from the phone (see
+  // this file's 'usage.refresh.request' handler above) - the SAME
+  // triggerKeystrokes mechanism, just fired on demand instead of blind
+  // polling. usageTimer is kept defined (see its own comment above) so
+  // ptyProcess.onExit's cleanup still has a valid, harmless no-op target.
+
+  pollTimer = setInterval(pollForRequests, POLL_INTERVAL_MS);
+  // Real gap found by testing: closing the shell directly (no graceful
+  // Ctrl+C) leaves no explicit "I'm done" signal for the Backend at all
+  // (see this function's onExit handler) - the ONLY way a dead session
+  // ever stops showing live on the phone is this heartbeat simply going
+  // quiet long enough for auth-server.js's own LIVE_SESSION_STALE_MS to
+  // notice. 2000ms (was 3000ms) keeps a comfortable multiple of margin
+  // under that window (now 7000ms) even if a poll or two is delayed,
+  // while detecting a real disconnect meaningfully faster than before.
+  focusTimer = setInterval(pollFocus, 2000);
+  // CLI-agnostic - runs for every adapter (Claude Code, Codex, generic),
+  // since battery is a property of the LAPTOP, not of whatever CLI it
+  // happens to be running.
+  checkBatteryOnce(); // one immediate reading at startup, not just 5 min later
+  batteryTimer = setInterval(checkBatteryOnce, BATTERY_POLL_INTERVAL_MS);
+
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.on('data', (data) => ptyProcess.write(data.toString()));
+
+  // Real gap in the PoC this replaces: there was no way for `setu status`
+  // or `setu stop` (both new - see src/status.js, src/stop.js) to know
+  // whether a session watcher was even running, or on which PID, since
+  // supervisor-qr.js was always started and killed by hand in a visible
+  // terminal. One small PID file per running session (keyed by
+  // SESSION_ID, since one paired device can run several sessions at
+  // once) - written here at startup, removed on every real exit path.
+  const pidFile = path.join(CONFIG_DIR, `session.${SESSION_ID}.pid`);
+  fs.writeFileSync(pidFile, JSON.stringify({ pid: process.pid, deviceName: DEVICE_NAME, sessionId: SESSION_ID, cwd: WORKING_DIR, startedAt: new Date().toISOString() }, null, 2));
+  const removePidFile = () => { try { fs.unlinkSync(pidFile); } catch {} };
+
+  process.on('SIGINT', () => {
+    ptyProcess.kill();
+    if (ws) ws.close();
+    removePidFile();
+    process.exit(0);
+  });
+  process.on('exit', removePidFile);
+
+  connectToAzure();
+}
+
+main().catch((err) => {
+  console.error('[supervisor] fatal:', err.message);
+  process.exit(1);
+});