@promptctl/cc-candybar 1.149.5 → 1.151.0

package/dist/cc-extra/PROVENANCE

@@ -0,0 +1,2 @@
+cc-extra ec94ee89583246d1b7ef577c71500a2151980ad5
+Copied by scripts/vendor-cc-extra.mjs; do not edit these files here.

package/dist/cc-extra/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "commonjs"
+}

package/dist/cc-extra/src/attach-registrar.js

@@ -0,0 +1,65 @@
+// attach-registrar.js — the registrar a stock Bun session gets over its inspector, and the source text
+// that installs it there.
+//
+// The hosted session builds its registrar in bun-host.mjs, in the same process as the graph it
+// splices. An attached session is a different process — a stock binary this launcher can only reach by
+// evaluating source in it — so the registrar crosses as TEXT: `installRegistrar` below, serialized
+// with Function.prototype.toString, and statusline-push.js's own file, wrapped as a module. Nothing is
+// re-spelled for the trip: the subscription logic that runs in the attached process is the same file
+// the hosted one requires. [LAW:one-source-of-truth]
+//
+// Because it crosses as text, `installRegistrar` may use NOTHING from this module's scope: every
+// value it needs is a parameter, and the suite evaluates the serialized form in an empty context to
+// hold it to that.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Runs INSIDE the attached process. `statusLinePush` is statusline-push.js's exports; `io` is the
+// process's own fs and net, and `env` its environment.
+function installRegistrar({ registrar, logPath }, statusLinePush, io, env, pid, uid) {
+  // [LAW:no-silent-failure] exception: this log is the only channel out of the user's session, and it
+  // is written from the push's socket handlers inside the app — a write it cannot make (a full disk)
+  // must cost the line, never throw into the app and take the session down with it.
+  const report = (line) => { try { io.fs.appendFileSync(logPath, `${new Date().toISOString()} ${pid} ${line}\n`); } catch {} };
+  const push = statusLinePush.createStatusLinePush({
+    connect: (socketPath) => io.net.createConnection(socketPath),
+    socketPath: statusLinePush.daemonSocketPath(env, uid),
+    report,
+  });
+  // The deps objects already wrapped. A breakpoint action runs on EVERY command run, and the wrap must
+  // happen once per controller: wrapping twice would run the command through two subscriptions.
+  const wrapped = new WeakSet();
+  globalThis[registrar] = {
+    // Called from the breakpoint on every command run, in the controller's frame. Answers what it did,
+    // so the launcher can log the first hit and any that fail.
+    attachStatusLine(controller, deps, emit) {
+      if (wrapped.has(deps)) return 'held';
+      wrapped.add(deps);
+      const run = deps.execute;
+      deps.execute = (payload, ...rest) => push.statusLine(controller, payload, emit, () => run.call(deps, payload, ...rest));
+      report('statusline-push attached to a status line controller');
+      return 'attached';
+    },
+  };
+  report('registrar installed');
+}
+
+// statusline-push.js as an expression that evaluates to its exports: a CommonJS module body run
+// inside a function that hands it `module` and `exports`. It requires nothing, which is what lets it
+// cross as text.
+const moduleExpression = (source) => `(() => { const module = { exports: {} }; ((module, exports) => {\n${source}\n})(module, module.exports); return module.exports; })()`;
+
+// The one expression the launcher evaluates in the attached process, at entry, before release. Strict
+// from its first line, because this file's own 'use strict' does not cross as text: an assignment that
+// does not take — `deps.execute` frozen in some release — throws and is reported as a failed hit, never
+// logged as 'attached'.
+function registrarSource({ registrar, logPath }) {
+  const statusLinePush = fs.readFileSync(path.join(__dirname, 'statusline-push.js'), 'utf8');
+  return `'use strict'; (${installRegistrar.toString()})(${JSON.stringify({ registrar, logPath })}, ${moduleExpression(statusLinePush)}, ` +
+    `{ fs: process.getBuiltinModule('node:fs'), net: process.getBuiltinModule('node:net') }, process.env, process.pid, process.getuid())`;
+}
+
+module.exports = { installRegistrar, registrarSource };

package/dist/cc-extra/src/boot-channel.js

@@ -0,0 +1,63 @@
+// boot-channel.js — the line protocol bun-host.mjs reports on and launch.js reads.
+//
+// The host says only what it can see and never decides; the launcher forms the verdict. The four
+// things a host can observe are here, in one place, because a protocol with a writer and a reader
+// that each carry their own idea of it has two ideas of it. [LAW:one-source-of-truth]
+//
+//   started            — control has passed to the hosted app. Before this nothing the user asked
+//                        for has run, so a failure is always safe to replace; after it, the app owns
+//                        whatever it did and re-running would repeat it. Reported rather than
+//                        inferred from whether stdout happened to see a byte.
+//   painted            — the hosted graph first wrote to the terminal. Not proof of a working
+//                        session — a pre-flight notice counts — but a session that never paints at
+//                        all is the hang the whole check exists to catch.
+//   absent-api <name>  — a Bun member the graph asked for that the surface does not have. Sent as
+//                        each is seen, not collected at the end, because the failure worth
+//                        diagnosing is the one where this process never reaches an end.
+//   anything else      — a named refusal, carried out as the reason.
+//
+// [LAW:no-silent-failure] every degrade leaves here, named.
+
+'use strict';
+
+// The descriptor the host writes on is chosen by the launcher and passed in this variable. It is
+// part of the protocol, not of either end: a host reading one name and a launcher writing another
+// leaves the host reporting onto an inherited stderr, where the verdicts corrupt the TUI's own
+// rendering and the launcher sees a silent channel. [LAW:one-source-of-truth]
+const BOOT_FD_ENV = 'CC_EXTRA_BOOT_FD';
+
+const RECORD_SEPARATOR = '\n';
+const STARTED = 'started';
+const PAINTED = 'painted';
+const ABSENT_API = 'absent-api ';
+
+// A newline inside a message would arrive as several records, so a reason carrying one — an error
+// with a multi-line message, say — would be read as a refusal followed by garbage.
+const oneRecord = (line) => String(line).replace(/[\r\n]+/g, ' ');
+
+// `write` is a parameter so this is testable with no descriptor, and so the host can decide where
+// the channel points. [LAW:effects-at-boundaries]
+function createBootChannel({ write }) {
+  let reported = false;
+  const absent = new Set();
+  const send = (line) => write(oneRecord(line) + RECORD_SEPARATOR);
+  return {
+    // The one-per-process VERDICT. Later observations still go out — a graph that painted and then
+    // threw has spent its verdict, and the message it died with is the useful part.
+    report(verdict) { if (reported) return; reported = true; send(verdict); },
+    send,
+    started() { send(STARTED); },
+    absentApi(name) { if (absent.has(name)) return; absent.add(name); send(ABSENT_API + name); },
+  };
+}
+
+// The reader's half. Returns what this line means, so the launcher never re-derives the protocol.
+function readReport(line) {
+  if (line === STARTED) return { kind: 'started' };
+  if (line === PAINTED) return { kind: 'painted' };
+  if (line.startsWith(ABSENT_API)) return { kind: 'absent-api', name: line.slice(ABSENT_API.length) };
+  if (line) return { kind: 'refusal', reason: line };
+  return { kind: 'blank' };
+}
+
+module.exports = { BOOT_FD_ENV, RECORD_SEPARATOR, STARTED, PAINTED, ABSENT_API, oneRecord, createBootChannel, readReport };

package/dist/cc-extra/src/bun-attach.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+// bun-attach.js — run the shipped claude binary under Bun, exactly as shipped, and apply every seam
+// that has a breakpoint form through the inspector Bun opens for it.
+//
+// WHY THIS EXISTS BESIDE launch.js. The hosted session (launch.js -> bun-host.mjs) splices the app's
+// source as node links it, which reaches every seam but replaces Bun with a surface assembled here.
+// This launcher keeps Bun and the binary untouched and reaches the app the one way a stock Bun process
+// can be reached: JavaScriptCore's inspector, over a unix socket, with breakpoints that evaluate a
+// seam's action in the frame they stop in and carry on without pausing. It reaches only the seams
+// whose effect a breakpoint can produce (`attach` in seams.js); a gate that must RETURN something else,
+// like propose-goal, needs the splice.
+//
+// WHY THE DEBUGGER ATTACHES AT ENTRY. JSC gives debug hooks only to code compiled while a debugger is
+// attached, and Bun does not recompile on attach: a breakpoint set in a session that booted without
+// one resolves and never fires (MEASURED on 2.1.299, three app functions called through breakpoints,
+// zero pauses). So the binary is started held at entry (`?wait=1`), the debugger is enabled, the
+// registrar is installed and the breakpoints are set — all before a line of the app has run — and
+// only then is it released. The breakpoints are set BY URL before their chunk exists; JSC binds each
+// one as its chunk parses (MEASURED: `breakpointResolved` at the predicted line and column).
+// [LAW:no-ambient-temporal-coupling] the order is this sequence's, and two waits in it are on a clock,
+// each with one owner: the socket's appearance, which has a deadline, and the question asked of the
+// released process (WHY IT STAYS CONNECTED), which is asked once, at ASK_AFTER_MS.
+//
+// WHY A UNIX SOCKET. The inspector runs arbitrary code in the session. On TCP it is reachable by every
+// process on the machine; a socket in a directory only this user can enter is reachable by this user.
+//
+// WHY IT STAYS CONNECTED. A breakpoint fires only while a client is connected: disconnect, and the
+// status line's breakpoint stopped firing (MEASURED on 2.1.299: 2 hits before, still 2 after six status
+// line reruns; connected, 2 became 8). What outlives a disconnect is only the wrapper an earlier hit
+// installed, on the one controller that hit reached — a controller the app builds later would never be
+// wrapped (MEASURED: a live session wrapped a second controller 18s in). So for a TUI the launcher stays
+// connected for the life of the session, and a connected debugger does not keep it from exiting
+// (MEASURED: `/exit` ended it, exit 0). The run it lets go is a one-shot: the inspector holds a process
+// that ends by draining its loop (`--version`) for as long as it is connected, and that process gives
+// no sign it is done (MEASURED: `beforeExit` never fires while it is held). Which of the two a run is,
+// the process is ASKED, ASK_AFTER_MS after release: a TUI has stdin in raw mode by then.
+//
+// FAILURE. Every step before release happens while the binary is held at entry, where nothing the user
+// asked for has run, so a failure there is answered by killing the held process and exiting non-zero,
+// with one line on stderr saying why — before any TUI exists to draw over it. Never with a stock
+// session: one would look like the attached session that failed, so whoever asked for the attach could
+// not tell it never happened. [LAW:no-silent-failure] After release
+// the session is the user's: nothing this launcher sees is a reason to end it, and what goes wrong is
+// written to the log and named on stderr once the session is over. [LAW:no-silent-failure]
+
+'use strict';
+
+const childProcess = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { readGraphFromFile } = require('./bun-graph.js');
+const { SEAMS, REGISTRAR } = require('./seams.js');
+const { resolveBreakpoints } = require('./seam-plan.js');
+const { registrarSource } = require('./attach-registrar.js');
+const { connect } = require('./ws-unix.js');
+const { createInspectorSession } = require('./inspector-session.js');
+const { superviseSignals, hasControllingTerminal, attachedToTerminal, rendersTui, exitStatus } = require('./launch.js');
+
+// Measured ~20ms from spawn to the socket on 2.1.299. Generous, because missing it costs the
+// session and waiting costs only a slower start.
+const SOCKET_DEADLINE_MS = 5000;
+
+// Whether a TUI is up. A TUI puts stdin in raw mode as it mounts — a trust dialog before the prompt
+// included — and a one-shot never does (MEASURED on 2.1.299: raw 127-131ms after release, every run;
+// `--version` not raw, exiting as soon as it was let go — the asking does not hold it).
+const TUI_IS_UP = 'process.stdin.isTTY === true && process.stdin.isRaw === true';
+
+// When after release the process is asked TUI_IS_UP: about fifteen times the measured time to raw
+// mode, and the wait an interactive one-shot like `--version` pays before it is let go. A TUI that
+// mounts slower than this is taken for a one-shot and runs without the push; the log says which.
+const ASK_AFTER_MS = 2000;
+const SOCKET_NAME = 'inspector.sock';
+
+// Per user, never the shared temp dir: on Linux that is /tmp, where another user could plant the log
+// name first, as a file to read the session's lines from or a link to append them through.
+const LOG_DIR = path.join(process.env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state'), 'cc-extra');
+const LOG_PATH = path.join(LOG_DIR, 'attach.log');
+
+// What the binary is started with: its inspector on the socket, holding at entry until released.
+const inspectedEnv = (env, socketPath) => ({ ...env, BUN_INSPECT: `ws+unix://${socketPath}?wait=1` });
+
+// The inspector calls that make a held process an attached one, in the order they must run: the
+// debugger is enabled before any app code compiles, the registrar exists before any breakpoint can
+// call it, and release comes last. BUN_INSPECT is taken out of the process's environment before a
+// line of the app runs: every Bun process the session starts — the Bash tool's `bun`, a hook, a nested
+// claude — would inherit it and fail to start its own inspector on the socket this one holds
+// (MEASURED: `Failed to start inspector`, exit 1; deleted at entry, the same child ran clean). Each breakpoint's action is a PROBE, which evaluates it as an
+// evaluate action would and also sends the result back, so the launcher sees each hit's answer —
+// including a throw, which an evaluate action would swallow. [LAW:no-silent-failure]
+// [LAW:effects-at-boundaries] a description, so the suite checks the order with no process.
+function attachCalls(points, registrarExpression) {
+  return [
+    ['Debugger.enable', {}],
+    // JSC's debugger starts with breakpoints deactivated; its own frontend activates them on connect.
+    ['Debugger.setBreakpointsActive', { active: true }],
+    ['Runtime.evaluate', { expression: 'delete process.env.BUN_INSPECT', returnByValue: true }],
+    ['Runtime.evaluate', { expression: registrarExpression, returnByValue: true }],
+    ...points.map((p, i) => ['Debugger.setBreakpointByUrl', {
+      url: p.url, lineNumber: p.lineNumber, columnNumber: p.columnNumber,
+      options: { autoContinue: true, actions: [{ id: i + 1, type: 'probe', data: p.action }] },
+    }]),
+    ['Inspector.initialized', {}],
+  ];
+}
+
+// What one probe sample means: the registrar's answer ('attached' the first time a controller is
+// reached, 'held' after), or a failure naming what came back instead.
+function readSample(payload) {
+  if (payload.type === 'string' && (payload.value === 'attached' || payload.value === 'held')) return { ok: true, value: payload.value };
+  return { ok: false, detail: payload.description || JSON.stringify(payload.value) };
+}
+
+// How often the wait looks for the socket. A look is one stat; the socket appears ~20ms after spawn.
+const SOCKET_LOOK_MS = 10;
+
+// Resolves once `name` exists in `dir`, rejects at the deadline or when `exited` settles first. It
+// LOOKS on a clock rather than watching the directory: on macOS fs.watch does not report every bind
+// of a unix socket (MEASURED on 2.1.289: 18 of 20 binds unseen, the socket there when the deadline
+// fired), and a missed one cost the attach. [LAW:no-ambient-temporal-coupling] the clock has one
+// owner, this wait, and one end, the deadline.
+function socketAppears(dir, name, deadlineMs, exited) {
+  return new Promise((resolve, reject) => {
+    const done = (settle) => { clearTimeout(timer); clearInterval(looking); settle(); };
+    const check = () => { if (fs.existsSync(path.join(dir, name))) done(resolve); };
+    const timer = setTimeout(() => done(() => reject(new Error(`no inspector socket within ${deadlineMs}ms`))), deadlineMs);
+    const looking = setInterval(check, SOCKET_LOOK_MS);
+    exited.then((ending) => done(() => reject(new Error(`claude ${describeEnding(ending)} before opening its inspector`))));
+    check();
+  });
+}
+
+const describeEnding = ({ code, signal, error }) => (error ? `could not start: ${error}` : `exited ${signal || code}`);
+
+// What the released run is, asked of it `askAfterMs` after release: `{ runs: 'tui' }`, `{ runs:
+// 'one-shot' }`, `{ runs: 'closed' }` when the inspector went away first (the run ended, or the
+// connection did), or `{ runs: 'unanswered', why }` when the question itself failed. A close resolves
+// before the rejection it causes reaches here, so a rejection that does is the question failing.
+// `session` is anything with the session's `send` and `on`; `delay(ms, fn)` is a cancellable timer. A
+// pure seam, so the suite drives it with neither an inspector nor a clock. [LAW:effects-at-boundaries]
+function askWhatRuns(session, askAfterMs, delay) {
+  return new Promise((resolve) => {
+    const answered = (r) => (r.wasThrown
+      ? { runs: 'unanswered', why: r.result.description ?? JSON.stringify(r.result.value) }
+      : { runs: r.result.value === true ? 'tui' : 'one-shot' });
+    const cancel = delay(askAfterMs, () => session.send('Runtime.evaluate', { expression: TUI_IS_UP, returnByValue: true })
+      .then((r) => resolve(answered(r)), (e) => resolve({ runs: 'unanswered', why: e.message })));
+    session.on('close', () => { cancel(); resolve({ runs: 'closed' }); });
+  });
+}
+
+// Run `binary` with the user's terminal and signals, resolving to how it ended: `{ code, signal }`, or
+// `{ code: 70, signal: null, error }` when it could not be started at all. `interrupted()` says whether
+// the user signalled an end to the session, as launch.js's verdict reads it.
+function runChild(binary, args, env) {
+  const child = childProcess.spawn(binary, args, { stdio: 'inherit', env });
+  let interrupted = false;
+  const stopSupervising = superviseSignals(child, {
+    sharesTerminalGroup: hasControllingTerminal(),
+    onSignal: () => { interrupted = true; },
+    on: (signal, handler) => process.on(signal, handler),
+    off: (signal, handler) => process.off(signal, handler),
+  });
+  const exited = new Promise((resolve) => {
+    child.on('error', (e) => resolve({ code: 70, signal: null, error: e.message }));
+    child.on('exit', (code, signal) => resolve({ code, signal }));
+  }).then((ending) => { stopSupervising(); return ending; });
+  return { child, exited, interrupted: () => interrupted };
+}
+
+// An attach that cannot happen: said, and nothing started in its place.
+function refuse(why, { stderr }) {
+  stderr(`cc-extra: not attached — ${why}; claude was not started (log: ${LOG_PATH})`);
+  return 1;
+}
+
+async function runStock(binary, args, why, { stderr }) {
+  stderr(`cc-extra: not attaching — ${why}; running stock claude`);
+  const { exited } = runChild(binary, args, process.env);
+  const ending = await exited;
+  if (ending.error) stderr(`cc-extra: claude ${describeEnding(ending)}`);
+  return exitStatus(ending.code, ending.signal);
+}
+
+async function attachAndRun(binary, args, io = {}) {
+  const stderr = io.stderr || ((line) => process.stderr.write(line + '\n'));
+  // [LAW:no-silent-failure] a line the log cannot take is counted and named when the session ends, and
+  // never changes what the launcher does: thrown, it could leave a held binary held.
+  let unlogged = 0;
+  const log = (line) => {
+    try {
+      fs.mkdirSync(LOG_DIR, { recursive: true, mode: 0o700 });
+      fs.appendFileSync(LOG_PATH, `${new Date().toISOString()} ${process.pid} launcher: ${line}\n`);
+    } catch { unlogged++; }
+  };
+
+  // Only a TUI has a status line to drive. A headless, piped or print-mode run (`-p`, at a terminal or
+  // not) is a one-shot that would pay the wait below for nothing and wants to stay exactly as fast as
+  // it shipped. [LAW:one-source-of-truth] whether a run renders a TUI is launch.js's one parse of it; an
+  // interactive `--version` still reads as a TUI there, and is let go at ASK_AFTER_MS.
+  if (!rendersTui(args, io.terminal ?? attachedToTerminal())) return runStock(binary, args, 'not a TUI: no status line to drive', { stderr });
+
+  const graph = readGraphFromFile(binary);
+  const plan = graph.ok ? resolveBreakpoints(new Map(graph.modules.map((m) => [m.name, m])), SEAMS) : graph;
+  if (!plan.ok) return refuse(`${plan.reason}${plan.seam ? ` (seam ${plan.seam})` : ''}${plan.detail ? `: ${plan.detail}` : ''}`, { stderr });
+
+  // Before the spawn, so the log's directory exists for the registrar's first line.
+  log(`attaching ${binary}`);
+  // mkdtemp makes the directory 0700: only this user can reach the socket inside it.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-extra-attach-'));
+  const socketPath = path.join(dir, SOCKET_NAME);
+  const calls = attachCalls(plan.points, registrarSource({ registrar: REGISTRAR, logPath: LOG_PATH }));
+  const release = calls.at(-1);
+  const { child, exited, interrupted } = runChild(binary, args, inspectedEnv(process.env, socketPath));
+
+  // What went wrong after release, said once the session is over rather than over the TUI. A set: a
+  // failure that repeats on every status line run is one trouble, not one per second of the session.
+  const troubles = new Set();
+  const bound = new Set();
+  let session;
+  try {
+    await socketAppears(dir, SOCKET_NAME, SOCKET_DEADLINE_MS, exited);
+    session = createInspectorSession(await connect(socketPath));
+    const seamOf = new Map(plan.points.map((p, i) => [i + 1, p.seam]));
+    session.on('Debugger.breakpointResolved', ({ breakpointId, location }) => {
+      bound.add(breakpointId);
+      log(`breakpoint ${breakpointId} bound at ${location.lineNumber}:${location.columnNumber}`);
+    });
+    session.on('Debugger.didSampleProbe', ({ sample }) => {
+      const read = readSample(sample.payload);
+      if (read.ok && read.value === 'held') return;
+      const line = read.ok ? `${seamOf.get(sample.probeId)}: ${read.value}` : `${seamOf.get(sample.probeId)} failed in the session: ${read.detail}`;
+      if (read.ok) { log(line); return; }
+      if (!troubles.has(line)) log(line);
+      troubles.add(line);
+    });
+    session.on('fault', (why) => { troubles.add(`the inspector session broke, so the seams stopped: ${why}`); });
+    session.on('close', (why) => { log(`inspector closed: ${why}`); });
+    for (const [method, params] of calls.slice(0, -1)) {
+      const result = await session.send(method, params);
+      if (result && result.wasThrown) throw new Error(`${method} threw: ${result.result.description ?? JSON.stringify(result.result.value)}`);
+    }
+  } catch (e) {
+    // Still held at entry: nothing the user asked for has run, so replacing it repeats nothing — unless
+    // the user is what ended it. A Ctrl+C while held kills the child and fails the attach with it, and
+    // answering that with a stock session starts the one the user just stopped.
+    if (session) session.close();
+    child.kill('SIGKILL');
+    log(`attach failed: ${e.message}`);
+    const ending = await exited;
+    fs.rmSync(dir, { recursive: true, force: true });
+    if (interrupted()) return exitStatus(ending.code, ending.signal);
+    return refuse(`attach failed: ${e.message}`, { stderr });
+  }
+
+  // Release. A failure here leaves the process's state unknown — it may already be running the user's
+  // command — so it is never answered with a second session; it is reported when this one ends.
+  await session.send(...release).catch((e) => troubles.add(`release failed: ${e.message}`));
+  log(`released ${binary} with ${plan.points.map((p) => p.seam).join(', ')}`);
+
+  // Only a run that answered 'tui' keeps the launcher connected for the session (see WHY IT STAYS
+  // CONNECTED). Anything else is let go, because staying is what holds a one-shot, and a question that
+  // could not be answered is said why.
+  const { runs, why } = await askWhatRuns(session, ASK_AFTER_MS, (ms, fn) => { const t = setTimeout(fn, ms); return () => clearTimeout(t); });
+  log(`after release: ${runs}${why ? ` (${why})` : ''}`);
+  if (runs !== 'tui') session.close();
+  if (runs === 'unanswered') troubles.add(`could not ask the session whether it is a TUI, so it ran without the push: ${why}`);
+
+  const { code, signal } = await exited;
+  // Our end of the connection is ours to close, rather than waiting on the peer's to.
+  session.close();
+  // A breakpoint set by a URL the release no longer parses its chunk under binds nowhere, and nothing
+  // else would say so: the push is simply absent.
+  if (runs === 'tui' && bound.size < plan.points.length) troubles.add(`${plan.points.length - bound.size} of ${plan.points.length} breakpoint(s) never bound in this session, so their seams never ran`);
+  fs.rmSync(dir, { recursive: true, force: true });
+  if (unlogged) troubles.add(`${unlogged} line(s) could not be written to the log`);
+  for (const line of troubles) stderr(`cc-extra: ${line} (log: ${LOG_PATH})`);
+  return exitStatus(code, signal);
+}
+
+module.exports = { SOCKET_DEADLINE_MS, ASK_AFTER_MS, TUI_IS_UP, LOG_PATH, inspectedEnv, attachCalls, readSample, socketAppears, askWhatRuns, attachAndRun };
+
+if (require.main === module) (async function main() {
+  const [binary, ...args] = process.argv.slice(2);
+  if (!binary) {
+    process.stderr.write('usage: bun-attach.js <installed-claude-binary> [claude args...]\n');
+    process.exit(2);
+  }
+  process.exitCode = await attachAndRun(binary, args);
+})();

package/dist/cc-extra/src/bun-graph.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// bun-graph.js — read the module graph Bun embeds in a compiled standalone executable, in memory,
+// from the INSTALLED binary. The host (bun-host.mjs) runs those modules under node; this file's only
+// job is producing the graph, or proving it cannot.
+//
+// WHY THIS EXISTS AT ALL. Claude Code ships as a Bun-compiled standalone Mach-O with its JavaScript
+// embedded. Keeping a copy of that JavaScript in the repo would be [LAW:one-source-of-truth] violated
+// on a weekly release cadence: the copy is a second map of the installed binary, and it starts lying
+// the next time the user updates. The installed binary is the single source; this file is a visibly
+// derived read of it, and nothing is written to disk.
+//
+// WHY THE CONTAINER'S OWN TABLE AND NOT A SCAN. Bun writes a module table at the end of the file and
+// points at it from a fixed struct just before the `\n---- Bun! ----\n` trailer. That table names
+// every embedded module, gives its exact bounds, and names the ENTRY POINT BY INDEX — so nothing here
+// has to know what the entry point is called, scan for delimiters, or disambiguate look-alike records.
+// It also means the only thing this file is coupled to is BUN'S container format, which changes when
+// Bun changes rather than when Claude ships. There is deliberately no version literal in this file and
+// no {version: offset} table anywhere in the tree.
+//
+// MEASURED, on two shipped binaries a month apart, with one code path and no special cases:
+//   2.1.226 (279,661,952 bytes) — 14 modules, entry id 0 = /$bunfs/root/src/entrypoints/cli.js,
+//     contents at 245,797,944, length 23,985,682. Those are exactly the bounds the previous
+//     delimiter-scanning extractor measured, and the slice `node --check` accepts; they are also
+//     byte-identical to what `Debugger.getScriptSource` returns from a LIVE session.
+//   2.1.258 (199,027,600 bytes) — 1,818 modules, entry id 5 = /$bunfs/root/cli, an ESM graph of
+//     1,640 js modules (the entry plus 1,639 code-split chunks) plus native, compressed and
+//     text assets.
+// Those numbers are dated observations, not inputs: nothing below reads them.
+//
+// [LAW:effects-at-boundaries] the whole parser is pure (Buffer in, result out); reading the binary is
+//   a separate one-line edge. That is why the tests need no 199MB fixture and no mocks.
+// [LAW:parse-dont-validate] the output is a PROVEN graph or a typed absence — never a half-parsed
+//   table that callers must re-check, and never a record wearing the shape of a good one.
+
+'use strict';
+
+const fs = require('fs');
+
+// Bun writes this immediately after the offsets struct, at the end of the graph it appended to the
+// executable. On macOS the code signature follows it, so the LAST occurrence is the real one.
+const TRAILER = Buffer.from('\n---- Bun! ----\n', 'latin1');
+
+// The struct between the module blob and the trailer. Only the four fields below are read; the
+// remaining bytes are not named here, because naming a field whose meaning has not been established
+// would be a map claiming to show territory nobody has walked.
+const OFFSETS_BYTES = 32;
+const OFFSETS = { byteCount: 0, modulesOffset: 8, modulesLength: 12, entryPointId: 16 };
+
+// One module's row in that table. Every offset in a row is relative to the START of the blob.
+const ROW_BYTES = 52;
+const ROW = { nameOffset: 0, nameLength: 4, contentsOffset: 8, contentsLength: 12, encoding: 48, loader: 49 };
+
+// How the contents are stored, and what they are. Both come from the container itself, so nothing
+// downstream has to sniff bytes to decide how to decode a module or what to do with it.
+const ENCODINGS = { 0: 'binary', 1: 'utf8', 2: 'utf16le' };
+const LOADERS = { 1: 'js', 5: 'file', 10: 'napi', 13: 'text' };
+
+// Embedded module paths are rooted at Bun's virtual filesystem. Used only to check that a decoded
+// name IS a name — a row whose name is arbitrary bytes means the table was not where we thought.
+const VIRTUAL_ROOT = '/$bunfs/';
+
+// Every way this can fail to produce a graph, named. Callers switch on the reason to log WHY they
+// fell back to stock claude, so these are part of the contract, not debug strings.
+// [LAW:no-silent-failure] an unreadable container is reported, never guessed past.
+const ABSENT = {
+  unreadable: 'binary-unreadable',
+  noTrailer: 'no-bun-module-graph-trailer',
+  trailerTooEarly: 'bun-trailer-has-no-offsets-struct-before-it',
+  blobTooLarge: 'module-blob-larger-than-the-file',
+  duplicateName: 'two-modules-share-one-name',
+  tableOutOfRange: 'module-table-outside-blob',
+  tableNotWholeRows: 'module-table-is-not-whole-rows',
+  empty: 'module-table-empty',
+  rowOutOfRange: 'module-contents-outside-blob',
+  badName: 'module-name-is-not-a-virtual-path',
+  unknownEncoding: 'module-has-unknown-encoding',
+  unknownLoader: 'module-has-unknown-loader',
+  entryOutOfRange: 'entry-point-id-outside-module-table',
+  entryNotJs: 'entry-point-is-not-a-javascript-module',
+};
+
+const absent = (reason, detail) => (detail === undefined ? { ok: false, reason } : { ok: false, reason, detail });
+
+// Parse the graph out of a whole standalone executable.
+// Returns { ok: true, modules, entryIndex, entryName } or { ok: false, reason }. Callers cannot
+// receive a module list that has not passed every check below. [LAW:parse-dont-validate]
+function readGraph(buf) {
+  const trailerAt = buf.lastIndexOf(TRAILER);
+  if (trailerAt === -1) return absent(ABSENT.noTrailer);
+
+  const offsets = trailerAt - OFFSETS_BYTES;
+  // A trailer with no room for its own struct in front of it is a trailer-shaped run of bytes, not
+  // a module graph. Saying so beats reporting that no trailer was found, which would be false.
+  if (offsets < 0) return absent(ABSENT.trailerTooEarly, `trailer at ${trailerAt}`);
+  const at = (field) => buf.readUInt32LE(offsets + field);
+
+  // byteCount is the one 64-bit field here. Reading only its low half would work on every binary
+  // measured so far and would silently produce a wrong blob start the first time it did not — a
+  // valid-looking graph built from the wrong bytes, which is the single outcome this file refuses.
+  const byteCount = buf.readBigUInt64LE(offsets + OFFSETS.byteCount);
+  // One check covers both ways this field can be wrong — a value too large for the file, and a value
+  // whose high half was never meant to be discarded — because they are the same statement: the blob
+  // must fit in front of the struct that describes it.
+  if (byteCount > BigInt(offsets)) return absent(ABSENT.blobTooLarge, `${byteCount} bytes claimed before offset ${offsets}`);
+
+  // The blob is byteCount bytes ending where the offsets struct begins; every pointer below is
+  // relative to its start.
+  const blob = offsets - Number(byteCount);
+
+  const tableAt = blob + at(OFFSETS.modulesOffset);
+  const tableLength = at(OFFSETS.modulesLength);
+  if (tableAt < blob || tableAt + tableLength > offsets) return absent(ABSENT.tableOutOfRange);
+  if (tableLength % ROW_BYTES !== 0) return absent(ABSENT.tableNotWholeRows, `${tableLength} is not a multiple of ${ROW_BYTES}`);
+
+  const count = tableLength / ROW_BYTES;
+  if (count === 0) return absent(ABSENT.empty);
+
+  const modules = [];
+  const seen = new Set();
+  for (let i = 0; i < count; i++) {
+    const row = tableAt + i * ROW_BYTES;
+    const field = (f) => buf.readUInt32LE(row + f);
+    const nameAt = blob + field(ROW.nameOffset), nameLength = field(ROW.nameLength);
+    const contentsAt = blob + field(ROW.contentsOffset), contentsLength = field(ROW.contentsLength);
+    if (nameAt < blob || nameAt + nameLength > offsets) return absent(ABSENT.rowOutOfRange, `row ${i} name`);
+    if (contentsAt < blob || contentsAt + contentsLength > offsets) return absent(ABSENT.rowOutOfRange, `row ${i} contents`);
+
+    const name = buf.toString('latin1', nameAt, nameAt + nameLength);
+    if (!name.startsWith(VIRTUAL_ROOT)) return absent(ABSENT.badName, `row ${i}: ${JSON.stringify(name.slice(0, 40))}`);
+    // Callers key these by name, so a duplicate does not collide here — it makes one of the two
+    // modules unreachable somewhere downstream, with nothing to show for it.
+    if (seen.has(name)) return absent(ABSENT.duplicateName, name);
+    seen.add(name);
+
+    // An unrecognised code means Bun's format moved under us. Decoding it as a neighbouring value
+    // would produce a module that looks fine and is wrong, which is the one outcome worth refusing.
+    const encoding = ENCODINGS[buf[row + ROW.encoding]];
+    const loader = LOADERS[buf[row + ROW.loader]];
+    if (encoding === undefined) return absent(ABSENT.unknownEncoding, `row ${i}: ${buf[row + ROW.encoding]}`);
+    if (loader === undefined) return absent(ABSENT.unknownLoader, `row ${i}: ${buf[row + ROW.loader]}`);
+
+    modules.push({
+      name, loader, encoding, offset: contentsAt, length: contentsLength,
+      bytes: () => buf.subarray(contentsAt, contentsAt + contentsLength),
+      // 'binary' contents have no text form; latin1 is the byte-preserving decode, so a caller that
+      // asks anyway gets its bytes back rather than replacement characters.
+      text: () => buf.toString(encoding === 'binary' ? 'latin1' : encoding, contentsAt, contentsAt + contentsLength),
+    });
+  }
+
+  const entryIndex = at(OFFSETS.entryPointId);
+  if (entryIndex >= modules.length) return absent(ABSENT.entryOutOfRange, `${entryIndex} of ${modules.length}`);
+  // An entry the host cannot evaluate is not an entry. Proving it here means no caller has to ask.
+  // [LAW:parse-dont-validate]
+  if (modules[entryIndex].loader !== 'js') return absent(ABSENT.entryNotJs, `${modules[entryIndex].name} is a ${modules[entryIndex].loader} module`);
+
+  return { ok: true, modules, entryIndex, entryName: modules[entryIndex].name };
+}
+
+// The edge: the only line in this module that touches the world. [LAW:effects-at-boundaries]
+function readGraphFromFile(binaryPath) {
+  let buf;
+  try {
+    buf = fs.readFileSync(binaryPath);
+  } catch (e) {
+    return absent(ABSENT.unreadable, e && e.message);
+  }
+  return readGraph(buf);
+}
+
+module.exports = { ABSENT, ENCODINGS, LOADERS, ROW_BYTES, VIRTUAL_ROOT, readGraph, readGraphFromFile };
+
+if (require.main === module) (function main() {
+  const [binaryPath] = process.argv.slice(2);
+  if (!binaryPath) {
+    process.stderr.write('usage: bun-graph.js <installed-claude-binary>\n');
+    process.exit(2);
+  }
+  const g = readGraphFromFile(binaryPath);
+  // A summary, never the sources: this CLI is the launcher's self-check and a human's diagnostic,
+  // and 32MB on stdout serves neither. The digest is what makes two runs comparable.
+  const out = g.ok
+    ? {
+      ok: true, modules: g.modules.length, entryIndex: g.entryIndex, entryName: g.entryName,
+      byLoader: g.modules.reduce((acc, m) => ({ ...acc, [m.loader]: (acc[m.loader] || 0) + 1 }), {}),
+      entrySha256: require('crypto').createHash('sha256').update(g.modules[g.entryIndex].bytes()).digest('hex'),
+    }
+    : g;
+  process.stdout.write(JSON.stringify(out) + '\n');
+  process.exit(g.ok ? 0 : 1);
+})();