very-happy-cli 0.2.165 → 0.2.167

package/dist/{apiMachine-B_cJldfa.cjs → apiMachine-BgMxGPsR.cjs}

@@ -1,56 +1,57 @@
 'use strict';
 
 var socket_ioClient = require('socket.io-client');
-var logger = require('./logger-D0hkk7Vo.cjs');
-var lidState = require('./lidState-z9ekRpZu.cjs');
-var mirrorProtocol = require('./mirrorProtocol-BUtmg1ws.cjs');
-var configuration = require('./configuration-BE61XNsg.cjs');
+var logger = require('./logger-B_MWPbZz.cjs');
+var lidState = require('./lidState-Bc2K9H9l.cjs');
+var mirrorProtocol = require('./mirrorProtocol-BdcN6QlN.cjs');
+var configuration = require('./configuration-C3piBtxY.cjs');
 var cliUpdate = require('./cliUpdate-DsKXPFYp.cjs');
-var registerCommonHandlers = require('./registerCommonHandlers--8ds2auE.cjs');
+var registerCommonHandlers = require('./registerCommonHandlers-DVYB3iVn.cjs');
 var promises = require('node:fs/promises');
 var path = require('node:path');
 var os = require('node:os');
 var node_child_process = require('node:child_process');
-var persistence = require('./persistence-C6ztVW1W.cjs');
+var persistence = require('./persistence-BYGl0QYw.cjs');
 var authRelay = require('./authRelay-BdYkC1Po.cjs');
 var limits = require('./limits-C-a7gr04.cjs');
-var time = require('./time-BbzJ7PJQ.cjs');
+var time = require('./time-BXvtjhe9.cjs');
 var pty = require('node-pty');
 var terminals = require('./terminals-B_bfC9c2.cjs');
 var tmuxSocket = require('./tmuxSocket-D-Xt6Vn-.cjs');
-var index = require('./index-DIodyAqF.cjs');
+var index = require('./index-PNMQPKhz.cjs');
 var node_crypto = require('node:crypto');
 var node_fs = require('node:fs');
 var axios = require('axios');
+var projectPath = require('./projectPath-ChLhdOyt.cjs');
 var ids = require('./ids-B6ZC0HGt.cjs');
 var detectCLI = require('./detectCLI-DR9ZaN6B.cjs');
-var localHappyAgentAuth = require('./localHappyAgentAuth-BCx0y1qW.cjs');
+var localHappyAgentAuth = require('./localHappyAgentAuth-T5GOvRha.cjs');
 var path$1 = require('./path-B7zW-WwE.cjs');
 var oneShotPrompts = require('./oneShotPrompts-CL0dip9C.cjs');
-var claudeSessionFork = require('./claudeSessionFork-CDJq_b9r.cjs');
-var codexAppServerClient = require('./codexAppServerClient-BuSdeUxT.cjs');
-var index$1 = require('./index-DqlyNgt4.cjs');
+var claudeSessionFork = require('./claudeSessionFork-Byd8zD1U.cjs');
+var codexAppServerClient = require('./codexAppServerClient-TiW9OBk4.cjs');
+var index$1 = require('./index-C9hI8a10.cjs');
 var codexThreadFork = require('./codexThreadFork-DNekT4nQ.cjs');
+var rateLimitWindows = require('./rateLimitWindows-CusGIqlq.cjs');
 require('chalk');
 require('node:util');
 require('os');
 require('child_process');
-require('./package-UkmvSFsg.cjs');
+require('./package-C9ZP9bpX.cjs');
 require('util');
 require('fs/promises');
 require('crypto');
 require('path');
 require('cross-spawn');
-require('./projectPath-ChLhdOyt.cjs');
-require('url');
 require('zod');
 require('tweetnacl');
 require('./terminalTitleSuggest-DhvRFX3H.cjs');
 require('./loginShellEnv-BkuYtExZ.cjs');
+require('url');
 require('fs');
 require('node:readline');
 require('./contentLogMetadata-ZSFk_NjQ.cjs');
-require('./manager-Cly8xVIR.cjs');
+require('./manager-HrEj442o.cjs');
 require('@anthropic-ai/sandbox-runtime');
 require('@paralleldrive/cuid2');
 
@@ -207,7 +208,7 @@ const TODO_LIST_MAX_ITEMS = 500;
 const TODO_TITLE_MAX_CHARS = 500;
 const FIELD_MAX_CHARS = 200;
 const PRIORITIES = ["none", "low", "medium", "high"];
-function str(value, max = FIELD_MAX_CHARS) {
+function str$1(value, max = FIELD_MAX_CHARS) {
   if (typeof value !== "string") return void 0;
   const flat = value.replace(/\s+/g, " ").trim();
   if (!flat) return void 0;
@@ -238,8 +239,8 @@ function parseTodoList(stdout) {
       continue;
     }
     const r = raw;
-    const id = str(r.id);
-    const title = str(r.title, TODO_TITLE_MAX_CHARS);
+    const id = str$1(r.id);
+    const title = str$1(r.title, TODO_TITLE_MAX_CHARS);
     if (!id || !title) {
       dropped++;
       continue;
@@ -249,10 +250,10 @@ function parseTodoList(stdout) {
       id,
       title,
       status: r.status === "done" ? "done" : "open",
-      ...str(r.due) ? { due: str(r.due) } : {},
+      ...str$1(r.due) ? { due: str$1(r.due) } : {},
       ...priority ? { priority } : {},
-      ...str(r.group) ? { group: str(r.group) } : {},
-      ...str(r.note) ? { note: str(r.note) } : {}
+      ...str$1(r.group) ? { group: str$1(r.group) } : {},
+      ...str$1(r.note) ? { note: str$1(r.note) } : {}
     });
   }
   return { items, dropped, truncated: hitCap };
@@ -4989,8 +4990,8 @@ function buildCaptureBatch(o) {
 const CAPTURE_FULL_BUDGET_BYTES = 1024 * 1024;
 const ALT_ENTER = Buffer.from("\x1B[?1049h", "ascii");
 const CURSOR_HOME = Buffer.from("\x1B[H", "ascii");
-const CRLF = Buffer.from("\r\n", "ascii");
-const SGR_RESET = Buffer.from("\x1B[0m", "ascii");
+const CRLF$1 = Buffer.from("\r\n", "ascii");
+const SGR_RESET$1 = Buffer.from("\x1B[0m", "ascii");
 function normalizeCaptureLines(blob) {
   if (blob.length === 0) return blob;
   const lines = [];
@@ -5005,7 +5006,7 @@ function normalizeCaptureLines(blob) {
   if (start < blob.length) lines.push(blob.subarray(start));
   const out = [];
   lines.forEach((l, i) => {
-    if (i > 0) out.push(CRLF);
+    if (i > 0) out.push(CRLF$1);
     out.push(l);
   });
   return Buffer.concat(out);
@@ -5033,31 +5034,31 @@ function assembleRestore(responses, paneState, budget = CAPTURE_FULL_BUDGET_BYTE
       realCount = lines.length;
       while (lines.length < rows) lines.push(EMPTY);
     }
-    const realBody = joinCrlf(lines.slice(0, realCount));
+    const realBody = joinCrlf$1(lines.slice(0, realCount));
     const padCount = lines.length - realCount;
-    const padBody = padCount > 0 ? Buffer.concat([realCount > 0 ? CRLF : EMPTY, SGR_RESET, joinCrlf(new Array(padCount).fill(EMPTY))]) : EMPTY;
+    const padBody = padCount > 0 ? Buffer.concat([realCount > 0 ? CRLF$1 : EMPTY, SGR_RESET$1, joinCrlf$1(new Array(padCount).fill(EMPTY))]) : EMPTY;
     const cursor = paneState ? Buffer.from(`\x1B[${paneState.cursorY + 1};${paneState.cursorX + 1}H`, "ascii") : Buffer.alloc(0);
-    return Buffer.concat([realBody, padBody, SGR_RESET, tail, cursor]);
+    return Buffer.concat([realBody, padBody, SGR_RESET$1, tail, cursor]);
   };
-  const wrapFull = (b) => Buffer.concat([SGR_RESET, b, SGR_RESET]);
-  const wrapSmall = (b) => Buffer.concat([b, SGR_RESET]);
+  const wrapFull = (b) => Buffer.concat([SGR_RESET$1, b, SGR_RESET$1]);
+  const wrapSmall = (b) => Buffer.concat([b, SGR_RESET$1]);
   if (!alternateOn) {
     const history2 = trimTrailingBlankRows(normalizeCaptureLines(get("history")));
     const smallHistory = trimTrailingBlankRows(normalizeCaptureLines(get("smallHistory")));
     const withHistory = (h) => Buffer.concat(
-      h.length > 0 ? [truncateToBudget(h, budget), SGR_RESET, CRLF, screen()] : [screen()]
+      h.length > 0 ? [truncateToBudget(h, budget), SGR_RESET$1, CRLF$1, screen()] : [screen()]
     );
     return { full: wrapFull(withHistory(history2)), small: wrapSmall(withHistory(smallHistory)), alternateOn };
   }
   const history = trimTrailingBlankRows(normalizeCaptureLines(get("history")));
   const saved = trimTrailingBlankRows(normalizeCaptureLines(get("altSaved")));
   const scrollback = truncateToBudget(
-    Buffer.concat(history.length > 0 && saved.length > 0 ? [history, SGR_RESET, CRLF, saved] : [history, saved]),
+    Buffer.concat(history.length > 0 && saved.length > 0 ? [history, SGR_RESET$1, CRLF$1, saved] : [history, saved]),
     budget
   );
-  const altScreen = Buffer.concat([ALT_ENTER, CURSOR_HOME, SGR_RESET, screen()]);
+  const altScreen = Buffer.concat([ALT_ENTER, CURSOR_HOME, SGR_RESET$1, screen()]);
   return {
-    full: wrapFull(Buffer.concat([scrollback, scrollback.length > 0 ? CRLF : Buffer.alloc(0), altScreen])),
+    full: wrapFull(Buffer.concat([scrollback, scrollback.length > 0 ? CRLF$1 : Buffer.alloc(0), altScreen])),
     small: wrapSmall(altScreen),
     alternateOn
   };
@@ -5071,7 +5072,7 @@ function stripTrailingNewlines(blob) {
 function trimTrailingBlankRows(blob) {
   const lines = splitLines(blob);
   while (lines.length > 0 && lines[lines.length - 1].length === 0) lines.pop();
-  return joinCrlf(lines);
+  return joinCrlf$1(lines);
 }
 function splitLines(blob) {
   const out = [];
@@ -5086,10 +5087,10 @@ function splitLines(blob) {
   if (start < blob.length) out.push(blob.subarray(start));
   return out;
 }
-function joinCrlf(lines) {
+function joinCrlf$1(lines) {
   const parts = [];
   lines.forEach((l, i) => {
-    if (i > 0) parts.push(CRLF);
+    if (i > 0) parts.push(CRLF$1);
     parts.push(l);
   });
   return Buffer.concat(parts);
@@ -5455,7 +5456,7 @@ class TerminalNotifyTracker {
    * Feed one observation for a terminal. Returns the notification event this
    * observation triggers, or null. Call once per terminal per tick.
    */
-  observe(terminalId, state, now, agentKind) {
+  observe(terminalId, state, now, agentKind, opts = {}) {
     let t = this.tracks.get(terminalId);
     if (!t || t.agentKind !== agentKind || now - t.lastObservedAt > 45e3) {
       t = {
@@ -5486,6 +5487,7 @@ class TerminalNotifyTracker {
       t.candidateCount += 1;
       t.lastCountedAt = now;
     }
+    if (opts.authoritative) t.candidateCount = Math.max(t.candidateCount, this.stableTicks);
     if (t.candidateCount < this.stableTicks) return null;
     const prev = t.confirmed;
     t.confirmed = t.candidate;
@@ -5542,6 +5544,403 @@ function sendTerminalNotification(opts) {
   });
 }
 
+const MIN_HOOK_CLAUDE_VERSION = "2.0.0";
+const EVENT_FIRST_VERSIONS = [
+  ["SessionStart", "2.0.0"],
+  ["UserPromptSubmit", "2.0.0"],
+  ["Stop", "2.0.0"],
+  ["Notification", "2.0.0"],
+  ["PostToolUse", "2.0.0"],
+  ["SessionEnd", "2.0.0"],
+  ["PermissionRequest", "2.0.45"],
+  ["PostCompact", "2.1.76"],
+  ["StopFailure", "2.1.78"]
+];
+const KNOWN_EVENTS = new Set(EVENT_FIRST_VERSIONS.map(([name]) => name));
+const TOOL_MATCHER_EVENTS = /* @__PURE__ */ new Set(["PostToolUse", "PermissionRequest"]);
+function parseVersion(v) {
+  const m = typeof v === "string" ? v.trim().match(/^(\d+)\.(\d+)\.(\d+)$/) : null;
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function versionAtLeast(version, floor) {
+  const a = parseVersion(version);
+  const b = parseVersion(floor);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return true;
+}
+function terminalHookEventPlan(claudeVersion) {
+  if (!versionAtLeast(claudeVersion, MIN_HOOK_CLAUDE_VERSION)) return null;
+  return EVENT_FIRST_VERSIONS.filter(([, first]) => versionAtLeast(claudeVersion, first)).map(([name]) => name);
+}
+const TERMINAL_HOOK_TIMEOUT_SECONDS = 10;
+const SAFE_PATH_RE = /^[A-Za-z0-9_./@:+ -]+$/;
+const SAFE_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+function terminalHookCommand(opts) {
+  const { forwarderPath, terminalId, happyHome } = opts;
+  if (!SAFE_PATH_RE.test(forwarderPath) || !SAFE_PATH_RE.test(happyHome) || !SAFE_ID_RE.test(terminalId)) return null;
+  return `[ -f '${forwarderPath}' ] && node '${forwarderPath}' '${terminalId}' '${happyHome}' "$PPID" || true`;
+}
+function buildTerminalHookSettings(events, command) {
+  const hooks = {};
+  for (const event of events) {
+    const entry = { type: "command", command, timeout: TERMINAL_HOOK_TIMEOUT_SECONDS };
+    hooks[event] = [TOOL_MATCHER_EVENTS.has(event) ? { matcher: "*", hooks: [entry] } : { hooks: [entry] }];
+  }
+  return { hooks };
+}
+function injectClaudeSettingsFlag(command, settingsPath) {
+  if (!SAFE_PATH_RE.test(settingsPath) || !isInjectableClaudeCommand(command)) return command;
+  const m = command.match(/^(\s*)claude/);
+  return `${m[1]}claude --settings '${settingsPath}'${command.slice(m[0].length)}`;
+}
+function isInjectableClaudeCommand(command) {
+  return /^\s*claude(?=\s|$)/.test(command) && !/(^|\s)--settings(=|\s|$)/.test(command);
+}
+const str = (v, max = 256) => typeof v === "string" && v.length > 0 && v.length <= max ? v : void 0;
+function parseTerminalAgentHook(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  const raw = body;
+  const event = raw.hook_event_name;
+  if (typeof event !== "string" || !KNOWN_EVENTS.has(event)) return null;
+  const terminalId = str(raw.terminalId, 64);
+  if (!terminalId || !SAFE_ID_RE.test(terminalId)) return null;
+  const claudeSessionId = str(raw.session_id, 128);
+  if (!claudeSessionId) return null;
+  const pid = typeof raw.claudePid === "number" ? raw.claudePid : typeof raw.claudePid === "string" && /^\d{1,10}$/.test(raw.claudePid) ? Number(raw.claudePid) : void 0;
+  const turnId = str(raw.prompt_id, 128) ?? str(raw.promptHash, 64);
+  return {
+    event,
+    terminalId,
+    claudeSessionId,
+    ...pid !== void 0 && Number.isInteger(pid) && pid > 1 ? { claudePid: pid } : {},
+    ...turnId ? { turnId } : {},
+    ...str(raw.agent_id, 128) ? { agentId: str(raw.agent_id, 128) } : {},
+    ...str(raw.notification_type, 64) ? { notificationType: str(raw.notification_type, 64) } : {},
+    ...raw.permissionHint === true ? { permissionHint: true } : {},
+    ...str(raw.trigger, 32) ? { trigger: str(raw.trigger, 32) } : {},
+    ...str(raw.source, 32) ? { source: str(raw.source, 32) } : {},
+    ...str(raw.transcript_path, 4096) ? { transcriptPath: str(raw.transcript_path, 4096) } : {}
+  };
+}
+const NEEDS_INPUT_NOTIFICATIONS = /* @__PURE__ */ new Set(["permission_prompt", "elicitation_dialog"]);
+const IDLE_NOTIFICATIONS = /* @__PURE__ */ new Set(["idle_prompt"]);
+function phaseTo(prev, phase, now, extra = {}) {
+  const { interrupted: _drop, ...rest } = prev;
+  return { ...rest, phase, seq: prev.seq + 1, phaseStartedAt: now, updatedAt: now, ...extra };
+}
+function reduceHookRecord(prev, ev, now) {
+  if (ev.event === "SessionStart") {
+    if (prev && prev.claudeSessionId === ev.claudeSessionId && ev.source !== "clear" && ev.source !== "compact") {
+      return { record: { ...prev, updatedAt: now, ...ev.claudePid ? { claudePid: ev.claudePid } : {} }, changed: false };
+    }
+    return {
+      record: {
+        claudeSessionId: ev.claudeSessionId,
+        ...ev.claudePid ? { claudePid: ev.claudePid } : prev?.claudePid ? { claudePid: prev.claudePid } : {},
+        phase: "done",
+        seq: (prev?.seq ?? 0) + 1,
+        phaseStartedAt: now,
+        updatedAt: now,
+        confirmedTurn: false,
+        ...ev.transcriptPath ? { transcriptPath: ev.transcriptPath } : {}
+      },
+      changed: prev?.phase !== "done"
+    };
+  }
+  if (prev && prev.claudeSessionId !== ev.claudeSessionId) return { record: prev, changed: false };
+  const base = prev ?? {
+    claudeSessionId: ev.claudeSessionId,
+    ...ev.claudePid ? { claudePid: ev.claudePid } : {},
+    phase: "done",
+    seq: 0,
+    phaseStartedAt: now,
+    updatedAt: now,
+    confirmedTurn: false
+  };
+  const withPid = ev.claudePid && !base.claudePid ? { ...base, claudePid: ev.claudePid } : base;
+  const fresh = !prev;
+  const renew = () => ({ record: { ...withPid, updatedAt: now }, changed: fresh });
+  switch (ev.event) {
+    case "SessionEnd":
+      return { record: void 0, changed: !!prev };
+    case "UserPromptSubmit":
+      return { record: phaseTo(withPid, "working", now, { confirmedTurn: true, turnId: ev.turnId }), changed: true };
+    case "PostToolUse":
+      if (withPid.phase === "working") return renew();
+      return { record: phaseTo(withPid, "working", now), changed: true };
+    case "PermissionRequest":
+      return { record: phaseTo(withPid, "needs_input", now), changed: withPid.phase !== "needs_input" || fresh };
+    case "Notification": {
+      if (ev.notificationType && IDLE_NOTIFICATIONS.has(ev.notificationType)) {
+        if (withPid.phase === "done") return renew();
+        return { record: phaseTo(withPid, "done", now), changed: true };
+      }
+      const needsInput = ev.notificationType ? NEEDS_INPUT_NOTIFICATIONS.has(ev.notificationType) : ev.permissionHint === true;
+      if (!needsInput) return renew();
+      return { record: phaseTo(withPid, "needs_input", now), changed: withPid.phase !== "needs_input" || fresh };
+    }
+    case "Stop":
+    case "StopFailure":
+      if (ev.agentId) return renew();
+      return { record: phaseTo(withPid, "done", now), changed: withPid.phase !== "done" || fresh };
+    case "PostCompact":
+      if (ev.trigger !== "manual") return renew();
+      return { record: phaseTo(withPid, "done", now), changed: withPid.phase !== "done" || fresh };
+    default:
+      return renew();
+  }
+}
+const HOOK_WORKING_STALE_MS = 10 * 6e4;
+function fuseAgentState(screen, record, now) {
+  const screenOnly = { ...screen ?? {}, source: "screen" };
+  if (!record) return screenOnly;
+  const s = screen?.agentState;
+  if (s === "shell") return screenOnly;
+  if (screen?.agentKind && screen.agentKind !== "claude") return screenOnly;
+  const hook = (agentState) => ({ agentKind: "claude", agentState, source: "hook" });
+  if (s === "needs_input" || s === "working") return { agentKind: "claude", agentState: s, source: "screen" };
+  switch (record.phase) {
+    case "working":
+    case "needs_input":
+      if (now - record.updatedAt > HOOK_WORKING_STALE_MS) return screenOnly;
+      return hook(record.phase);
+    case "done":
+      return hook("idle");
+  }
+}
+const INTERRUPT_CHECK_DELAYS_MS = [600, 2e3, 5e3];
+const INTERRUPT_CONFIRM_WINDOW_MS = INTERRUPT_CHECK_DELAYS_MS[INTERRUPT_CHECK_DELAYS_MS.length - 1] + 1500;
+const KITTY_ESCAPE_PRESS_RE = /^\x1b\[27(?:;1(?::1)?)?u$/;
+function isInterruptInput(text) {
+  return text === "\x1B" || text === "" || KITTY_ESCAPE_PRESS_RE.test(text);
+}
+function isDialogAnswerInput(text) {
+  return text === "\r" || text === "\n" || text === "\r\n";
+}
+function armsInterruptCheck(text, phase) {
+  if (phase === "working") return isInterruptInput(text);
+  if (phase === "needs_input") return isInterruptInput(text) || isDialogAnswerInput(text);
+  return false;
+}
+function pendingInterruptFor(record, now) {
+  if (!record || !record.confirmedTurn) return null;
+  if (record.phase !== "working" && record.phase !== "needs_input") return null;
+  return {
+    claudeSessionId: record.claudeSessionId,
+    seq: record.seq,
+    phaseStartedAt: record.phaseStartedAt,
+    ...record.turnId ? { turnId: record.turnId } : {},
+    at: now
+  };
+}
+function decideInterrupt(record, pending, screen, now) {
+  if (!record || !record.confirmedTurn) return "drop";
+  if (record.phase !== "working" && record.phase !== "needs_input") return "drop";
+  if (record.claudeSessionId !== pending.claudeSessionId || record.seq !== pending.seq || record.phaseStartedAt !== pending.phaseStartedAt || record.turnId !== pending.turnId) return "drop";
+  if (now - record.updatedAt > HOOK_WORKING_STALE_MS) return "drop";
+  if (now - pending.at > INTERRUPT_CONFIRM_WINDOW_MS) return "drop";
+  if (screen?.agentKind === "claude" && screen.agentState === "idle") return "synthesize";
+  return "wait";
+}
+function synthesizeInterruptDone(record, now) {
+  return { ...phaseTo(record, "done", now), interrupted: true };
+}
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+class TerminalAgentHookStore {
+  constructor(pidAlive = isPidAlive) {
+    this.pidAlive = pidAlive;
+  }
+  records = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  /** Apply one forwarded hook body. Returns the terminal whose list-relevant
+   *  state changed (caller kicks a list refresh), or null. Never throws. */
+  applyHook(body, now) {
+    const ev = parseTerminalAgentHook(body);
+    if (!ev) return null;
+    const prev = this.valid(ev.terminalId);
+    const { record, changed } = reduceHookRecord(prev, ev, now);
+    if (record) this.records.set(ev.terminalId, record);
+    else this.records.delete(ev.terminalId);
+    if (record?.seq !== prev?.seq) this.pending.delete(ev.terminalId);
+    return { terminalId: ev.terminalId, changed };
+  }
+  /** The record if its claude process is still alive; dead ones are dropped. */
+  valid(terminalId) {
+    const record = this.records.get(terminalId);
+    if (!record) return void 0;
+    if (record.claudePid !== void 0 && !this.pidAlive(record.claudePid)) {
+      this.records.delete(terminalId);
+      this.pending.delete(terminalId);
+      return void 0;
+    }
+    return record;
+  }
+  /** Screen observation (undefined = probe failed) → fused state. */
+  fuse(terminalId, screen, now) {
+    return fuseAgentState(screen, this.valid(terminalId), now);
+  }
+  /** A web keystroke reached the pane. True when it armed an inference
+   *  check (Esc/Ctrl+C during a turn; also Enter on a dialog). */
+  noteInput(terminalId, text, now) {
+    const record = this.records.get(terminalId);
+    if (!record || !armsInterruptCheck(text, record.phase)) return false;
+    const pending = pendingInterruptFor(this.valid(terminalId), now);
+    if (!pending) return false;
+    this.pending.set(terminalId, pending);
+    return true;
+  }
+  /** Re-check an armed interrupt against a fresh screen observation. */
+  checkInterrupt(terminalId, screen, now) {
+    const pending = this.pending.get(terminalId);
+    if (!pending) return "none";
+    const record = this.valid(terminalId);
+    const verdict = decideInterrupt(record, pending, screen, now);
+    if (verdict === "wait") return "wait";
+    this.pending.delete(terminalId);
+    if (verdict === "drop" || !record) return "drop";
+    this.records.set(terminalId, synthesizeInterruptDone(record, now));
+    return "synthesized";
+  }
+  has(terminalId) {
+    return this.records.has(terminalId);
+  }
+  forget(terminalId) {
+    this.records.delete(terminalId);
+    this.pending.delete(terminalId);
+  }
+  /** Drop records of terminals that no longer exist. */
+  prune(liveIds) {
+    const keep = new Set(liveIds);
+    for (const id of this.records.keys()) if (!keep.has(id)) this.forget(id);
+    for (const id of this.pending.keys()) if (!keep.has(id)) this.pending.delete(id);
+  }
+}
+
+const TERMINAL_STATUS_FORWARDER_BASENAME = "terminal_status_forwarder.cjs";
+const VERSION_TTL_MS = 6 * 60 * 6e4;
+const VERSION_RETRY_MS = 5 * 6e4;
+function hooksDir() {
+  return path.join(configuration.configuration.happyHomeDir, "tmp", "terminal-hooks");
+}
+function terminalHookSettingsPath(terminalId) {
+  return path.join(hooksDir(), `${terminalId}.json`);
+}
+function probeClaudeVersion(env) {
+  return new Promise((resolveVersion) => {
+    try {
+      node_child_process.execFile("claude", ["--version"], { timeout: 5e3, maxBuffer: 32 * 1024, env }, (error, stdout) => {
+        resolveVersion(error ? null : mirrorProtocol.stableVersion(String(stdout)));
+      });
+    } catch {
+      resolveVersion(null);
+    }
+  });
+}
+class ClaudeVersionCache {
+  constructor(env, probe = probeClaudeVersion) {
+    this.env = env;
+    this.probe = probe;
+  }
+  version = null;
+  checkedAt = 0;
+  inFlight = null;
+  started = false;
+  start(now = Date.now()) {
+    this.started = true;
+    if (this.version === null || now - this.checkedAt > VERSION_TTL_MS) this.refresh(now);
+  }
+  current(now = Date.now()) {
+    if (!this.started) return null;
+    const ttl = this.version ? VERSION_TTL_MS : VERSION_RETRY_MS;
+    if (now - this.checkedAt > ttl) this.refresh(now);
+    return this.version;
+  }
+  /** current(), but waits (bounded) for a probe already in flight —
+   *  for paths that are async anyway (auto-restore). */
+  async settled(timeoutMs) {
+    const pending = this.inFlight;
+    if (pending) {
+      let timer;
+      await Promise.race([pending, new Promise((r) => {
+        timer = setTimeout(r, timeoutMs);
+      })]);
+      if (timer) clearTimeout(timer);
+    }
+    return this.current();
+  }
+  refresh(now) {
+    if (this.inFlight) return;
+    this.checkedAt = now;
+    this.inFlight = this.probe(this.env()).then((parsed) => {
+      this.checkedAt = Date.now();
+      if (parsed) this.version = parsed;
+      logger.logger.debug(`[TERMINAL HOOKS] claude --version \u2192 ${parsed ?? "unresolved"}`);
+    }, () => void 0).finally(() => {
+      this.inFlight = null;
+    });
+  }
+}
+function withTerminalHooks(command, terminalId, claudeVersion) {
+  if (!isInjectableClaudeCommand(command)) return command;
+  const events = terminalHookEventPlan(claudeVersion);
+  if (!events) return command;
+  const hookCommand = terminalHookCommand({
+    forwarderPath: path.resolve(projectPath.projectPath(), "scripts", TERMINAL_STATUS_FORWARDER_BASENAME),
+    terminalId,
+    happyHome: configuration.configuration.happyHomeDir
+  });
+  if (!hookCommand) return command;
+  const path$1 = terminalHookSettingsPath(terminalId);
+  try {
+    node_fs.mkdirSync(hooksDir(), { recursive: true });
+    node_fs.writeFileSync(path$1, JSON.stringify(buildTerminalHookSettings(events, hookCommand), null, 2));
+  } catch (error) {
+    logger.logger.debug(`[TERMINAL HOOKS] settings write failed for ${terminalId}: ${error}`);
+    return command;
+  }
+  const injected = injectClaudeSettingsFlag(command, path$1);
+  if (injected !== command) logger.logger.debug(`[TERMINAL HOOKS] hooks injected for ${terminalId} (claude ${claudeVersion}, ${events.length} events)`);
+  return injected;
+}
+function removeTerminalHookSettings(terminalId) {
+  try {
+    const path = terminalHookSettingsPath(terminalId);
+    if (node_fs.existsSync(path)) node_fs.unlinkSync(path);
+  } catch {
+  }
+}
+function sweepStaleTerminalHookSettings(isLive) {
+  const removed = [];
+  let names;
+  try {
+    names = node_fs.readdirSync(hooksDir());
+  } catch {
+    return removed;
+  }
+  for (const name of names) {
+    const m = name.match(/^([A-Za-z0-9_-]{1,64})\.json$/);
+    if (!m) continue;
+    try {
+      if (isLive(m[1])) continue;
+      node_fs.unlinkSync(path.join(hooksDir(), name));
+      removed.push(m[1]);
+    } catch {
+    }
+  }
+  return removed;
+}
+
 const AUTO_RESTORE_DEFAULT_MAX = 6;
 const AUTO_RESTORE_DEFAULT_WINDOW_HOURS = 24;
 const AUTO_RESTORE_HARD_MAX = 20;
@@ -5692,6 +6091,626 @@ function directTerminalItems(sessions, tmuxIds) {
   return out.sort((a, b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 }
 
+const SCROLLBACK_FILE_MAX_BYTES = 512 * 1024;
+const SCROLLBACK_TOTAL_MAX_BYTES = 64 * 1024 * 1024;
+const SCROLLBACK_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+const SCROLLBACK_CAPTURE_LINES = 5e3;
+const CHECKPOINT_QUIET_MS = 3e3;
+const CHECKPOINT_MIN_INTERVAL_MS = 3e4;
+const CHECKPOINT_MAX_DIRTY_MS = 12e4;
+const CHECKPOINTS_PER_TICK = 4;
+const SCROLLBACK_PERSIST_DEFAULT = true;
+function resolveScrollbackConfig(raw) {
+  const v = raw?.terminalScrollbackPersist;
+  return { enabled: typeof v === "boolean" ? v : SCROLLBACK_PERSIST_DEFAULT };
+}
+const ESC = 27;
+const SGR_RESET = Buffer.from("\x1B[0m", "ascii");
+const CRLF = Buffer.from("\r\n", "ascii");
+function sanitizeArchivedScrollback(input) {
+  const out = Buffer.allocUnsafe(input.length);
+  let o = 0;
+  const n = input.length;
+  let i = 0;
+  while (i < n) {
+    const b = input[i];
+    if (b === ESC) {
+      const next = i + 1 < n ? input[i + 1] : -1;
+      if (next === 91) {
+        let j = i + 2;
+        let paramsOk = true;
+        while (j < n && input[j] >= 48 && input[j] <= 63) {
+          const c = input[j];
+          if (!(c >= 48 && c <= 57 || c === 59 || c === 58)) paramsOk = false;
+          j++;
+        }
+        let intermediates = false;
+        while (j < n && input[j] >= 32 && input[j] <= 47) {
+          intermediates = true;
+          j++;
+        }
+        if (j < n && input[j] >= 64 && input[j] <= 126) {
+          if (input[j] === 109 && paramsOk && !intermediates) {
+            input.copy(out, o, i, j + 1);
+            o += j + 1 - i;
+          }
+          i = j + 1;
+        } else {
+          i = skipToLineEnd(input, j);
+        }
+        continue;
+      }
+      if (next === 93 || next === 80 || next === 95 || next === 94 || next === 88) {
+        let j = i + 2;
+        while (j < n) {
+          if (input[j] === 7 && next === 93) {
+            j += 1;
+            break;
+          }
+          if (input[j] === ESC && j + 1 < n && input[j + 1] === 92) {
+            j += 2;
+            break;
+          }
+          if (input[j] === 10) break;
+          j++;
+        }
+        i = j;
+        continue;
+      }
+      i += next === -1 ? 1 : 2;
+      continue;
+    }
+    if (b < 32 && b !== 9 && b !== 10 && b !== 13) {
+      i++;
+      continue;
+    }
+    if (b === 127) {
+      i++;
+      continue;
+    }
+    if (b === 194 && i + 1 < n && input[i + 1] >= 128 && input[i + 1] <= 159) {
+      i += 2;
+      continue;
+    }
+    out[o++] = b;
+    i++;
+  }
+  return out.subarray(0, o);
+}
+function skipToLineEnd(buf, from) {
+  const nl = buf.indexOf(10, from);
+  return nl === -1 ? buf.length : nl;
+}
+function splitCrlfLines(blob) {
+  const out = [];
+  let start = 0;
+  for (let i = 0; i < blob.length; i++) {
+    if (blob[i] !== 10) continue;
+    let end = i;
+    if (end > start && blob[end - 1] === 13) end -= 1;
+    out.push(blob.subarray(start, end));
+    start = i + 1;
+  }
+  if (start < blob.length) out.push(blob.subarray(start));
+  return out;
+}
+function isBlankRow(row) {
+  return /^(?:\x1b\[[0-9;:]*m| )*$/.test(row.toString("latin1"));
+}
+function joinCrlf(lines) {
+  const parts = [];
+  lines.forEach((l, i) => {
+    if (i > 0) parts.push(CRLF);
+    parts.push(l);
+  });
+  return Buffer.concat(parts);
+}
+function buildCheckpointBody(parts, budget = SCROLLBACK_FILE_MAX_BYTES) {
+  const cleaned = [];
+  for (const part of parts) {
+    const lines = splitCrlfLines(normalizeCaptureLines(sanitizeArchivedScrollback(part)));
+    while (lines.length > 0 && isBlankRow(lines[lines.length - 1])) lines.pop();
+    if (lines.length > 0) cleaned.push(joinCrlf(lines));
+  }
+  const joined = [];
+  cleaned.forEach((c, i) => {
+    if (i > 0) joined.push(SGR_RESET, CRLF);
+    joined.push(c);
+  });
+  return truncateToBudget(Buffer.concat(joined), budget);
+}
+const FILE_MAGIC = "VHSB1";
+function encodeArchiveFile(file) {
+  return Buffer.concat([Buffer.from(`${FILE_MAGIC} ${Math.floor(file.savedAt)}
+`, "ascii"), file.body]);
+}
+function decodeArchiveFile(raw) {
+  if (!raw || raw.length === 0) return null;
+  const nl = raw.indexOf(10);
+  if (nl <= 0 || nl > 64) return null;
+  const m = /^VHSB1 (\d{1,16})$/.exec(raw.subarray(0, nl).toString("ascii"));
+  if (!m) return null;
+  const savedAt = Number(m[1]);
+  if (!Number.isFinite(savedAt) || savedAt <= 0) return null;
+  const body = truncateToBudget(sanitizeArchivedScrollback(raw.subarray(nl + 1)), SCROLLBACK_FILE_MAX_BYTES);
+  if (body.length === 0) return null;
+  return { savedAt, body };
+}
+const DIM = "\x1B[0;2m";
+const RESET = "\x1B[0m";
+const REBUILD_SEPARATOR = Buffer.from(`${DIM}\u2500\u2500 \u91CD\u5EFA \xB7 rebuilt \u2500\u2500${RESET}`, "utf8");
+function chainArchive(prev, live, budget = SCROLLBACK_FILE_MAX_BYTES) {
+  if (!prev) return live ? { savedAt: live.savedAt, body: truncateToBudget(live.body, budget) } : null;
+  if (!live) return { savedAt: prev.savedAt, body: truncateToBudget(prev.body, budget) };
+  const body = Buffer.concat([prev.body, SGR_RESET, CRLF, REBUILD_SEPARATOR, CRLF, live.body]);
+  return { savedAt: Math.max(prev.savedAt, live.savedAt), body: truncateToBudget(body, budget) };
+}
+function pad2(n) {
+  return n < 10 ? `0${n}` : String(n);
+}
+function formatSavedAt(savedAt) {
+  const d = new Date(savedAt);
+  return `${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+function archiveHeaderLine(savedAt) {
+  return Buffer.from(`${DIM}\u2500\u2500 \u4EE5\u4E0B\u4E3A\u4E0A\u6B21\u4F1A\u8BDD\u7684\u8F93\u51FA \xB7 previous session (${formatSavedAt(savedAt)}) \u2500\u2500${RESET}`, "utf8");
+}
+const ARCHIVE_FOOTER_LINE = Buffer.from(`${DIM}\u2500\u2500 \u4EE5\u4E0A\u4E3A\u4E0A\u6B21\u4F1A\u8BDD\u7684\u8F93\u51FA \xB7 \u7EC8\u7AEF\u5DF2\u91CD\u5EFA\uFF0C\u8FDB\u7A0B\u662F\u65B0\u7684 \u2500\u2500${RESET}`, "utf8");
+function withArchivedScrollback(payload, archive) {
+  if (!archive || archive.body.length === 0) return payload;
+  const full = Buffer.concat([
+    SGR_RESET,
+    archiveHeaderLine(archive.savedAt),
+    CRLF,
+    archive.body,
+    SGR_RESET,
+    CRLF,
+    ARCHIVE_FOOTER_LINE,
+    CRLF,
+    payload.full
+  ]);
+  return { ...payload, full };
+}
+const CHECKPOINT_PROBE_FORMAT = "#{session_name}|#{window_activity}|#{alternate_on}|#{@vh_attach}";
+const ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+function parseCheckpointProbe(stdout) {
+  const out = [];
+  for (const line of stdout.split("\n")) {
+    const parts = line.split("|");
+    if (parts.length < 4) continue;
+    const [name, activity, alt] = parts;
+    const attach = parts.slice(3).join("|");
+    if (!name.startsWith("vh-")) continue;
+    const id = name.slice(3);
+    if (!ID_RE.test(id)) continue;
+    if (attach.trim().length > 0) continue;
+    const secs = Number(activity);
+    if (!Number.isFinite(secs) || secs <= 0) continue;
+    out.push({ id, activityAt: secs * 1e3, alternateOn: alt === "1" });
+  }
+  return out;
+}
+const ACTIVITY_RESOLUTION_MS = 1e3;
+function planCheckpoints(terminals, state, now, opts = {}) {
+  const quietMs = opts.quietMs ?? CHECKPOINT_QUIET_MS;
+  const minIntervalMs = opts.minIntervalMs ?? CHECKPOINT_MIN_INTERVAL_MS;
+  const maxDirtyMs = opts.maxDirtyMs ?? CHECKPOINT_MAX_DIRTY_MS;
+  const max = opts.max ?? CHECKPOINTS_PER_TICK;
+  const due = [];
+  for (const t of terminals) {
+    const prev = state.get(t.id);
+    if (prev && t.activityAt + ACTIVITY_RESOLUTION_MS <= prev.at) continue;
+    const lastAt = prev?.at ?? 0;
+    const quiet = now - t.activityAt >= quietMs && now - lastAt >= minIntervalMs;
+    const overdue = now - lastAt >= maxDirtyMs;
+    if (quiet || overdue) due.push({ id: t.id, lastAt });
+  }
+  due.sort((a, b) => a.lastAt - b.lastAt || (a.id < b.id ? -1 : 1));
+  return due.slice(0, Math.max(0, max)).map((d) => d.id);
+}
+function checkpointCaptureArgs(id, alternateOn, lines = SCROLLBACK_CAPTURE_LINES) {
+  const t = `=vh-${id}:`;
+  const n = Math.max(1, Math.floor(lines));
+  if (!alternateOn) return [["capture-pane", "-peqJN", "-t", t, "-S", `-${n}`]];
+  return [
+    ["capture-pane", "-peqJN", "-t", t, "-S", `-${n}`, "-E", "-1"],
+    ["capture-pane", "-peqJN", "-t", t, "-a"]
+  ];
+}
+const FILE_RE = /^([a-zA-Z0-9_-]{1,64})\.(live|prev)\.vhsb$/;
+function archiveFileName(id, kind) {
+  if (!ID_RE.test(id)) throw new Error(`invalid terminal id: ${id}`);
+  return `${id}.${kind}.vhsb`;
+}
+function parseArchiveFileName(name) {
+  const m = FILE_RE.exec(name);
+  return m ? { id: m[1], kind: m[2] } : null;
+}
+function planScrollbackGc(files, keepIds, now, ttlMs = SCROLLBACK_TTL_MS, totalMax = SCROLLBACK_TOTAL_MAX_BYTES) {
+  const doomed = /* @__PURE__ */ new Set();
+  for (const f of files) {
+    if (!f.id || !f.kind) {
+      doomed.add(f.name);
+      continue;
+    }
+    if (now - f.mtimeMs > ttlMs) {
+      doomed.add(f.name);
+      continue;
+    }
+    if (keepIds && !keepIds.has(f.id)) doomed.add(f.name);
+  }
+  const survivors = files.filter((f) => !doomed.has(f.name)).sort((a, b) => a.mtimeMs - b.mtimeMs);
+  let total = survivors.reduce((s, f) => s + f.bytes, 0);
+  for (const f of survivors) {
+    if (total <= totalMax) break;
+    doomed.add(f.name);
+    total -= f.bytes;
+  }
+  return [...doomed];
+}
+
+const CONFIG_REFRESH_MS = 6e4;
+const GC_INTERVAL_MS = 10 * 6e4;
+const SHUTDOWN_FLUSH_BUDGET_MS = 300;
+const KILL_CHECKPOINT_BUDGET_MS = 300;
+const TMUX_TIMEOUT_MS = 5e3;
+const TMUX_MAX_BUFFER = 32 * 1024 * 1024;
+function defaultTmux(env) {
+  return {
+    run: (args, timeoutMs) => new Promise((resolve) => {
+      try {
+        node_child_process.execFile(
+          "tmux",
+          tmuxSocket.tmuxArgs(args),
+          { env: env(), encoding: "buffer", timeout: Math.max(1, timeoutMs ?? TMUX_TIMEOUT_MS), maxBuffer: TMUX_MAX_BUFFER },
+          (err, stdout) => resolve(err ? null : stdout)
+        );
+      } catch {
+        resolve(null);
+      }
+    }),
+    runSync: (args, timeoutMs) => {
+      try {
+        const r = node_child_process.spawnSync("tmux", tmuxSocket.tmuxArgs(args), { env: env(), timeout: Math.max(1, timeoutMs), maxBuffer: TMUX_MAX_BUFFER });
+        return r.status === 0 && r.stdout ? r.stdout : null;
+      } catch {
+        return null;
+      }
+    }
+  };
+}
+class ScrollbackCheckpointer {
+  opts;
+  tmux;
+  now;
+  readConfig;
+  /** Cached switch; the default until settings were read once. */
+  enabled = SCROLLBACK_PERSIST_DEFAULT;
+  configReadAt = 0;
+  lastGcAt = 0;
+  busy = false;
+  /** Set once a tick ran in this process — the shutdown flush is a no-op
+   *  before that (unit tests that only construct+stop never touch tmux). */
+  started = false;
+  stopped = false;
+  state = /* @__PURE__ */ new Map();
+  /** Bumped by promote(): an in-flight capture of an earlier generation must
+   *  not overwrite `.live` after the promotion moved it to `.prev`. */
+  generation = /* @__PURE__ */ new Map();
+  constructor(opts) {
+    this.opts = opts;
+    this.tmux = opts.tmux ?? defaultTmux(opts.env);
+    this.now = opts.now ?? Date.now;
+    this.readConfig = opts.readConfig ?? (() => {
+      try {
+        return resolveScrollbackConfig(JSON.parse(node_fs.readFileSync(path.join(this.opts.homeDir(), "settings.json"), "utf8")));
+      } catch {
+        return resolveScrollbackConfig(null);
+      }
+    });
+  }
+  dir() {
+    return path.join(this.opts.homeDir(), "terminal-scrollback");
+  }
+  filePath(id, kind) {
+    return path.join(this.dir(), archiveFileName(id, kind));
+  }
+  isEnabled() {
+    this.refreshConfig();
+    return this.enabled;
+  }
+  // ── tick ────────────────────────────────────────────────────────────────
+  /** Fire-and-forget from the list-track tick. Never throws. */
+  tick(closedIds) {
+    if (this.busy || this.stopped) return;
+    this.busy = true;
+    this.started = true;
+    void this.runTick(closedIds).catch((e) => logger.logger.debug(`[SCROLLBACK] tick failed: ${e}`)).finally(() => {
+      this.busy = false;
+    });
+  }
+  /** One tick, awaitable (tests). */
+  async runTick(closedIds) {
+    this.started = true;
+    this.refreshConfig();
+    if (!this.enabled) return;
+    const out = await this.tmux.run(["list-sessions", "-F", CHECKPOINT_PROBE_FORMAT]);
+    const probed = out ? parseCheckpointProbe(out.toString("utf8")) : null;
+    if (probed) {
+      this.seedState(probed);
+      const now = this.now();
+      for (const id of planCheckpoints(probed, this.state, now)) {
+        if (this.stopped || !this.enabled) break;
+        const t = probed.find((p) => p.id === id);
+        await this.checkpointOne(t);
+      }
+    }
+    this.maybeGc(probed ? /* @__PURE__ */ new Set([...probed.map((p) => p.id), ...closedIds]) : null);
+  }
+  /** Re-read the switch (at most every CONFIG_REFRESH_MS; always on first
+   *  use, so a replay right after daemon start already honours `false`). */
+  refreshConfig() {
+    const now = this.now();
+    if (this.configReadAt && now - this.configReadAt < CONFIG_REFRESH_MS) return;
+    this.configReadAt = now;
+    let enabled = SCROLLBACK_PERSIST_DEFAULT;
+    try {
+      enabled = this.readConfig().enabled;
+    } catch {
+    }
+    const turnedOff = this.enabled && !enabled;
+    this.enabled = enabled;
+    if (!enabled) {
+      if (turnedOff) logger.logger.info("[SCROLLBACK] terminalScrollbackPersist=false: deleting saved terminal scrollback");
+      this.purge();
+    }
+  }
+  /** First sight of an id after a daemon start: an existing `.live` file
+   *  counts as the last checkpoint (by mtime), so a restart does not re-take
+   *  every terminal at once. */
+  seedState(probed) {
+    for (const t of probed) {
+      if (this.state.has(t.id)) continue;
+      try {
+        const mtime = node_fs.statSync(this.filePath(t.id, "live")).mtimeMs;
+        this.state.set(t.id, { at: mtime - ACTIVITY_RESOLUTION_MS });
+      } catch {
+      }
+    }
+  }
+  async checkpointOne(t) {
+    const gen = this.generation.get(t.id) ?? 0;
+    const startedAt = this.now();
+    const parts = [];
+    for (const args of checkpointCaptureArgs(t.id, t.alternateOn)) {
+      const out = await this.tmux.run(args);
+      if (!out) return;
+      parts.push(out);
+    }
+    if ((this.generation.get(t.id) ?? 0) !== gen || this.stopped || !this.enabled) return;
+    this.writeLive(t.id, buildCheckpointBody(parts), this.now());
+    this.state.set(t.id, { at: startedAt });
+  }
+  writeLive(id, body, now) {
+    if (body.length === 0) {
+      this.removeFile(id, "live");
+      return;
+    }
+    this.writeFile(id, "live", { savedAt: now, body });
+  }
+  // ── promote / replay ────────────────────────────────────────────────────
+  /**
+   * Spec D3: called right before a terminal is rebuilt (new tmux session,
+   * same id). `.live` (the life that ended) is chained onto `.prev` and
+   * removed. Synchronous on purpose — the caller creates the session in the
+   * same turn, so no async capture can slip in between.
+   *
+   * Returns an UNDO that puts both files back exactly as they were: the
+   * caller runs it when the rebuild did not happen (new-session failed —
+   * e.g. a timed-out has-session misread a live session as gone), so the
+   * same life is not archived twice and replayed as a duplicate.
+   * `.live` is only removed once the chained `.prev` was written.
+   */
+  promote(id) {
+    this.generation.set(id, (this.generation.get(id) ?? 0) + 1);
+    this.state.delete(id);
+    const noop = () => {
+    };
+    if (!this.isEnabled()) return noop;
+    try {
+      const liveRaw = this.readFile(id, "live");
+      const prevRaw = this.readFile(id, "prev");
+      const live = decodeArchiveFile(liveRaw);
+      const chained = chainArchive(decodeArchiveFile(prevRaw), live);
+      if (!chained || !live || !liveRaw) return noop;
+      if (!this.writeFile(id, "prev", chained)) return noop;
+      this.removeFile(id, "live");
+      return () => {
+        this.generation.set(id, (this.generation.get(id) ?? 0) + 1);
+        if (prevRaw) this.writeRaw(id, "prev", prevRaw);
+        else this.removeFile(id, "prev");
+        this.writeRaw(id, "live", liveRaw);
+      };
+    } catch (e) {
+      logger.logger.debug(`[SCROLLBACK] promote ${id} failed: ${e}`);
+      return noop;
+    }
+  }
+  /** The archive to replay above a capture of `id`, or null. */
+  replayFor(id) {
+    if (!this.isEnabled()) return null;
+    try {
+      return decodeArchiveFile(this.readFile(id, "prev"));
+    } catch {
+      return null;
+    }
+  }
+  // ── shutdown ────────────────────────────────────────────────────────────
+  /**
+   * Daemon exit: capture every terminal with output newer than its last
+   * checkpoint — ASYNC and in PARALLEL, newest activity first, within
+   * `budgetMs`. Never throws and always resolves by the deadline, so the
+   * caller's state/lock cleanup runs regardless. Best-effort: on a machine
+   * shutdown tmux may already be gone; the periodic checkpoint is the real
+   * guarantee.
+   */
+  async flushOnShutdown(budgetMs = SHUTDOWN_FLUSH_BUDGET_MS) {
+    if (this.stopped) return;
+    this.stopped = true;
+    if (!this.started || !this.enabled) return;
+    let timer;
+    const deadline = new Promise((r) => {
+      timer = setTimeout(r, Math.max(0, budgetMs));
+      timer.unref?.();
+    });
+    const startedAt = Date.now();
+    const left = () => Math.max(1, budgetMs - (Date.now() - startedAt));
+    const work = (async () => {
+      const out = await this.tmux.run(["list-sessions", "-F", CHECKPOINT_PROBE_FORMAT], left());
+      if (!out) return;
+      const probed = parseCheckpointProbe(out.toString("utf8"));
+      this.seedState(probed);
+      const dirty = planCheckpoints(probed, this.state, this.now(), {
+        quietMs: 0,
+        minIntervalMs: 0,
+        maxDirtyMs: 0,
+        max: Number.MAX_SAFE_INTEGER
+      });
+      const byRecent = dirty.map((id) => probed.find((p) => p.id === id)).sort((a, b) => b.activityAt - a.activityAt);
+      let written = 0;
+      await Promise.all(byRecent.map(async (t) => {
+        const at = this.now();
+        const parts = await Promise.all(checkpointCaptureArgs(t.id, t.alternateOn).map((a) => this.tmux.run(a, left())));
+        if (parts.some((p) => !p) || Date.now() - startedAt > budgetMs) return;
+        this.writeLive(t.id, buildCheckpointBody(parts), this.now());
+        this.state.set(t.id, { at });
+        written++;
+      }));
+      if (dirty.length > 0) logger.logger.debug(`[SCROLLBACK] shutdown flush: ${written}/${dirty.length} terminal(s)`);
+    })().catch((e) => logger.logger.debug(`[SCROLLBACK] shutdown flush failed: ${e}`));
+    await Promise.race([work, deadline]);
+    if (timer) clearTimeout(timer);
+  }
+  /**
+   * Synchronous single-terminal capture right before the user kills it, so
+   * a ↻ restore of the close record replays its last output. Bounded by
+   * `budgetMs`; never throws; attach terminals are skipped.
+   */
+  checkpointSync(id, budgetMs = KILL_CHECKPOINT_BUDGET_MS) {
+    try {
+      if (!/^[a-zA-Z0-9_-]{1,64}$/.test(id) || !this.isEnabled()) return false;
+      const deadline = Date.now() + budgetMs;
+      const left = () => deadline - Date.now();
+      const probe = this.tmux.runSync(["display-message", "-p", "-t", `=vh-${id}:`, "#{alternate_on}|#{@vh_attach}"], left());
+      if (!probe) return false;
+      const [alt, ...attach] = probe.toString("utf8").replace(/\r?\n$/, "").split("|");
+      if (attach.join("|").trim().length > 0) return false;
+      const at = this.now();
+      const parts = [];
+      for (const args of checkpointCaptureArgs(id, alt === "1")) {
+        const timeout = left();
+        const part = timeout > 0 ? this.tmux.runSync(args, timeout) : null;
+        if (!part) return false;
+        parts.push(part);
+      }
+      this.writeLive(id, buildCheckpointBody(parts), this.now());
+      this.state.set(id, { at });
+      return true;
+    } catch (e) {
+      logger.logger.debug(`[SCROLLBACK] pre-kill checkpoint ${id} failed: ${e}`);
+      return false;
+    }
+  }
+  // ── fs ──────────────────────────────────────────────────────────────────
+  ensureDir() {
+    const dir = this.dir();
+    node_fs.mkdirSync(dir, { recursive: true, mode: 448 });
+    try {
+      node_fs.chmodSync(dir, 448);
+    } catch {
+    }
+    return dir;
+  }
+  readFile(id, kind) {
+    try {
+      const p = this.filePath(id, kind);
+      if (node_fs.statSync(p).size > SCROLLBACK_FILE_MAX_BYTES * 2) return null;
+      return node_fs.readFileSync(p);
+    } catch {
+      return null;
+    }
+  }
+  /** Atomic 0600 write; false on any failure. */
+  writeFile(id, kind, file) {
+    return this.writeRaw(id, kind, encodeArchiveFile(file));
+  }
+  writeRaw(id, kind, bytes) {
+    try {
+      this.ensureDir();
+      const target = this.filePath(id, kind);
+      const tmp = `${target}.${process.pid}.tmp`;
+      node_fs.writeFileSync(tmp, bytes, { mode: 384 });
+      node_fs.chmodSync(tmp, 384);
+      node_fs.renameSync(tmp, target);
+      return true;
+    } catch (e) {
+      logger.logger.debug(`[SCROLLBACK] write ${id}.${kind} failed: ${e}`);
+      return false;
+    }
+  }
+  removeFile(id, kind) {
+    try {
+      node_fs.unlinkSync(this.filePath(id, kind));
+    } catch {
+    }
+  }
+  listFiles() {
+    let names;
+    try {
+      names = node_fs.readdirSync(this.dir());
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const name of names) {
+      try {
+        const st = node_fs.statSync(path.join(this.dir(), name));
+        if (!st.isFile()) continue;
+        const parsed = parseArchiveFileName(name);
+        out.push({ name, id: parsed?.id ?? null, kind: parsed?.kind ?? null, mtimeMs: st.mtimeMs, bytes: st.size });
+      } catch {
+      }
+    }
+    return out;
+  }
+  maybeGc(keepIds) {
+    const now = this.now();
+    if (this.lastGcAt && now - this.lastGcAt < GC_INTERVAL_MS) return;
+    this.lastGcAt = now;
+    this.gc(keepIds, now);
+  }
+  /** Exposed for tests. */
+  gc(keepIds, now = this.now()) {
+    const doomed = planScrollbackGc(this.listFiles(), keepIds, now);
+    for (const name of doomed) {
+      try {
+        node_fs.unlinkSync(path.join(this.dir(), name));
+      } catch {
+      }
+    }
+    if (doomed.length > 0) logger.logger.debug(`[SCROLLBACK] gc removed ${doomed.length} file(s)`);
+    return doomed;
+  }
+  /** Switch turned off: the saved scrollback goes away entirely. */
+  purge() {
+    try {
+      node_fs.rmSync(this.dir(), { recursive: true, force: true });
+    } catch {
+    }
+    this.state.clear();
+  }
+}
+
 const TOMBSTONE_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
 function tmuxKillVerified(kill, probe) {
   return !kill.error && !probe.error && typeof probe.status === "number" && probe.status !== 0;
@@ -5836,6 +6855,10 @@ function terminalListSignature(items) {
 function hostListSignature(items) {
   return `${isTmuxAvailable() ? "tmux" : "no-tmux"}|${terminalListSignature(items)}`;
 }
+function screenObservation(probe) {
+  if (probe.agentObservedAt === void 0) return void 0;
+  return { agentKind: probe.agentKind, agentState: probe.agentState };
+}
 function looksLikeClaudeCommand(currentCommand) {
   const cmd = (currentCommand || "").trim().replace(/^-/, "").toLowerCase();
   return cmd === "claude" || cmd === "node" || /^\d+\.\d+(\.\d+)?$/.test(cmd);
@@ -6307,6 +7330,8 @@ class WebTerminalManager {
    *  refreshes and notifications into a process that is exiting. */
   shuttingDown = false;
   onAutoRestoreSummaryCb = null;
+  /** B-550: scrollback checkpoints across rebuilds (scrollbackCheckpoint.ts). */
+  scrollback = new ScrollbackCheckpointer({ homeDir: () => configuration.configuration.happyHomeDir, env: ptyEnv });
   /** Report line for the account notification (wired by apiMachine). */
   setOnAutoRestoreSummary(fn) {
     this.onAutoRestoreSummaryCb = fn;
@@ -6345,6 +7370,22 @@ class WebTerminalManager {
   // callback ⇒ tracking is skipped entirely.
   onNotify;
   notifyTracker = new TerminalNotifyTracker();
+  // ── Hook-driven agent status (B-547) ────────────────────────────────────
+  // `claude` commands the daemon types into a terminal get `--settings`
+  // with managed hooks (terminalHookSettings.ts); the forwarded events land
+  // in `agentHooks` and are fused with the screen classifier in
+  // probeAgentState. The screen stays the fallback for everything else.
+  agentHooks = new TerminalAgentHookStore();
+  claudeVersion = new ClaudeVersionCache(ptyEnv);
+  /** Terminals whose LAST probe was decided by a hook record — their
+   *  transitions skip the screen debounce in the notification tracker.
+   *  Daemon-internal: never pushed (wire shape unchanged). */
+  hookSourced = /* @__PURE__ */ new Set();
+  /** Last `#{pane_current_command}` identity seen per terminal, so an
+   *  interrupt re-check can classify the screen without a list read. */
+  lastPolledIdentity = /* @__PURE__ */ new Map();
+  interruptTimers = /* @__PURE__ */ new Map();
+  hookSettingsSwept = false;
   // ── Terminal mirror integration (B-105) ─────────────────────────────────
   /** terminalId → shadow session id (daemon's mirror manager). Feeds the
    *  list push (toggle availability) and closed-terminal records. */
@@ -6371,8 +7412,72 @@ class WebTerminalManager {
   requestListRefresh() {
     this.kickListRefresh();
   }
-  constructor(emit, onNotify) {
-    this.emit = emit;
+  /** B-547: one forwarded status hook (control server /terminal-agent-hook).
+   *  A list-relevant change pushes within the kick debounce instead of
+   *  waiting for the 10 s tick. Never throws. */
+  ingestAgentHook(body) {
+    try {
+      const result = this.agentHooks.applyHook(body, Date.now());
+      if (result?.changed) this.kickListRefresh();
+    } catch (e) {
+      logger.logger.debug(`[WEB TERMINAL] agent hook ingest failed: ${e}`);
+    }
+  }
+  /** B-547: test/diagnostic view — does this terminal hold a hook record? */
+  hasAgentHookRecord(terminalId) {
+    return this.agentHooks.has(terminalId);
+  }
+  /** B-547: once per daemon, drop settings files of terminals whose tmux
+   *  session is gone. Per-id `has-session` (not a list read, whose transient
+   *  failure would look like "no terminals") decides liveness. */
+  sweepHookSettingsOnce() {
+    if (this.hookSettingsSwept || !isTmuxAvailable()) return;
+    this.hookSettingsSwept = true;
+    try {
+      const env = ptyEnv();
+      const removed = sweepStaleTerminalHookSettings((id) => this.terminals.has(id) || node_child_process.spawnSync("tmux", tmuxSocket.tmuxArgs(["has-session", "-t", `=vh-${id}:`]), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }).status !== 1);
+      if (removed.length > 0) logger.logger.debug(`[WEB TERMINAL] removed ${removed.length} stale terminal hook settings file(s)`);
+    } catch (e) {
+      logger.logger.debug(`[WEB TERMINAL] hook settings sweep failed: ${e}`);
+    }
+  }
+  /** B-547: a terminal is gone — drop its hook record, timers and file. */
+  forgetAgentHooks(terminalId) {
+    this.agentHooks.forget(terminalId);
+    this.hookSourced.delete(terminalId);
+    this.lastPolledIdentity.delete(terminalId);
+    for (const t of this.interruptTimers.get(terminalId) ?? []) clearTimeout(t);
+    this.interruptTimers.delete(terminalId);
+    removeTerminalHookSettings(terminalId);
+  }
+  /** B-547: re-check an armed Esc/Ctrl+C at the spec's delays. A later
+   *  keypress re-arms (fresh baseline, fresh timers). */
+  scheduleInterruptChecks(terminalId) {
+    for (const t of this.interruptTimers.get(terminalId) ?? []) clearTimeout(t);
+    const timers = INTERRUPT_CHECK_DELAYS_MS.map((delay) => {
+      const t = setTimeout(() => this.runInterruptCheck(terminalId), delay);
+      t.unref?.();
+      return t;
+    });
+    this.interruptTimers.set(terminalId, timers);
+  }
+  runInterruptCheck(terminalId) {
+    try {
+      const screen = this.probeScreenState(`vh-${terminalId}`, this.lastPolledIdentity.get(terminalId));
+      const verdict = this.agentHooks.checkInterrupt(terminalId, screenObservation(screen), Date.now());
+      if (verdict === "wait") return;
+      for (const t of this.interruptTimers.get(terminalId) ?? []) clearTimeout(t);
+      this.interruptTimers.delete(terminalId);
+      if (verdict === "synthesized") {
+        logger.logger.debug(`[WEB TERMINAL] ${terminalId}: inferred interrupt (Esc/Ctrl+C, no Stop hook)`);
+        this.kickListRefresh();
+      }
+    } catch (e) {
+      logger.logger.debug(`[WEB TERMINAL] interrupt check failed: ${e}`);
+    }
+  }
+  constructor(emit, onNotify) {
+    this.emit = emit;
     this.onNotify = onNotify ?? null;
     this.reaper = setInterval(() => this.reapIdle(), REAP_INTERVAL_MS);
     this.reaper.unref?.();
@@ -6385,6 +7490,8 @@ class WebTerminalManager {
    */
   startListTracking(cb, intervalMs = LIST_TRACK_INTERVAL_MS) {
     this.listChangedCb = cb;
+    this.claudeVersion.start();
+    this.sweepHookSettingsOnce();
     this.lastActivityEmitted = {};
     if (!this.listTrackTimer) {
       this.listTrackTimer = setInterval(() => this.listTrackTick(), intervalMs);
@@ -6407,6 +7514,12 @@ class WebTerminalManager {
       clearTimeout(this.activityFlushTimer);
       this.activityFlushTimer = null;
     }
+    for (const timers of this.interruptTimers.values()) for (const t of timers) clearTimeout(t);
+    this.interruptTimers.clear();
+  }
+  /** B-550: last scrollback checkpoint before the daemon exits (async, ~300ms, never throws). */
+  flushScrollbackForShutdown() {
+    return this.scrollback.flushOnShutdown();
   }
   /**
    * One pty chunk arrived → make sure a realtime activity frame goes out
@@ -6537,6 +7650,8 @@ class WebTerminalManager {
     try {
       const list = this.buildTerminalList();
       this.trackClosures(list);
+      if (list.length > 0) this.agentHooks.prune([...list.map((t) => t.id), ...this.terminals.keys()]);
+      this.scrollback.tick(this.closedTerminals.map((r) => r.id));
       this.trackNotifications(list);
       this.pruneActivityTable(list);
       this.emitActivity(Object.fromEntries(
@@ -6594,6 +7709,7 @@ class WebTerminalManager {
         closedAt: now
       });
       changed = true;
+      this.forgetAgentHooks(id);
       logger.logger.debug(`[WEB TERMINAL] recorded closed terminal ${id}`);
       try {
         this.onTerminalClosedCb?.(id);
@@ -6679,6 +7795,7 @@ class WebTerminalManager {
       if (!isTmuxAvailable()) return;
       const settings = await persistence.readSettings();
       const config = resolveAutoRestoreConfig(settings);
+      await this.claudeVersion.settled(3e3);
       const selection = selectAutoRestore(candidates, {
         now: Date.now(),
         config,
@@ -6787,6 +7904,7 @@ class WebTerminalManager {
       { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }
     ).status === 0;
     if (exists) return false;
+    const undoPromote = plan.attachTmux ? void 0 : this.scrollback.promote(plan.terminalId);
     const envFlags = tmuxSupportsEnvFlag() ? [
       "-e",
       CLAUDE_CLASSIC_RENDERER_ENV,
@@ -6807,6 +7925,7 @@ class WebTerminalManager {
       { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env }
     ).status === 0;
     if (!live) {
+      undoPromote?.();
       logger.logger.debug(`[WEB TERMINAL] auto-restore: tmux create failed for ${plan.terminalId}`);
       return false;
     }
@@ -6840,7 +7959,8 @@ class WebTerminalManager {
       );
     }
     if (plan.command) {
-      for (const argv of startupInjectionArgs(name, plan.command)) {
+      const command = withTerminalHooks(plan.command, plan.terminalId, this.claudeVersion.current());
+      for (const argv of startupInjectionArgs(name, command)) {
         node_child_process.spawnSync("tmux", tmuxSocket.tmuxArgs(argv), { stdio: "ignore", timeout: TMUX_PROBE_TIMEOUT_MS, env });
       }
     }
@@ -6873,7 +7993,13 @@ class WebTerminalManager {
     const now = Date.now();
     this.notifyTracker.prune(list.map((t) => t.id));
     for (const item of list) {
-      const event = this.notifyTracker.observe(item.id, item.agentState, now, item.agentKind);
+      const event = this.notifyTracker.observe(
+        item.id,
+        item.agentState,
+        now,
+        item.agentKind,
+        { authoritative: this.hookSourced.has(item.id) }
+      );
       if (!event) continue;
       try {
         this.onNotify({ terminalId: item.id, title: item.title || "Terminal", event });
@@ -7232,7 +8358,8 @@ class WebTerminalManager {
       logger.logger.debug(`[WEB TERMINAL] ${tmuxSession} attaches user tmux session ${attachTarget.id} (${attachTarget.name})`);
       return { id: attachTarget.id, name: attachTarget.name };
     }
-    const startup = normalizeStartupCommand(startupCommand);
+    const normalized = normalizeStartupCommand(startupCommand);
+    const startup = normalized && tmuxSession.startsWith("vh-") ? withTerminalHooks(normalized, tmuxSession.slice(3), this.claudeVersion.current()) : normalized;
     if (startup) {
       try {
         for (const a of startupInjectionArgs(tmuxSession, startup)) {
@@ -7348,7 +8475,10 @@ class WebTerminalManager {
     });
     const paneState = parsePaneState((byKey.panes ?? Buffer.alloc(0)).toString("utf8"));
     if (paneState) session.paneId = paneState.paneId;
-    const payload = assembleRestore({ ...byKey, tail: unescapeOctal(byKey.tail ?? Buffer.alloc(0)) }, paneState);
+    const payload = withArchivedScrollback(
+      assembleRestore({ ...byKey, tail: unescapeOctal(byKey.tail ?? Buffer.alloc(0)) }, paneState),
+      this.scrollback.replayFor(session.id)
+    );
     if (fresh) {
       session.restoreHeadless(payload.full);
     }
@@ -7407,6 +8537,7 @@ class WebTerminalManager {
     if (!session) return;
     session.lastTouch = Date.now();
     const text = Buffer.from(dataBase64, "base64").toString("utf8");
+    if (this.agentHooks.noteInput(terminalId, text, Date.now())) this.scheduleInterruptChecks(terminalId);
     if (session.transport.kind === "pty") {
       session.transport.pty.write(text);
       return;
@@ -7540,6 +8671,7 @@ class WebTerminalManager {
       this.tombstones[terminalId] = Date.now();
       saveTombstones(this.tombstones);
       this.notifyTracker.remove(terminalId);
+      this.forgetAgentHooks(terminalId);
       logger.logger.debug(`[WEB TERMINAL] killed direct pty ${terminalId}`);
       this.kickListRefresh();
       return true;
@@ -7549,6 +8681,7 @@ class WebTerminalManager {
       return t ? seenInfoOf(t) : void 0;
     })();
     const target = `=vh-${terminalId}:`;
+    this.scrollback.checkpointSync(terminalId);
     const killed = node_child_process.spawnSync("tmux", tmuxSocket.tmuxArgs(["kill-session", "-t", target]), { stdio: "ignore", env: ptyEnv() });
     const verified = node_child_process.spawnSync("tmux", tmuxSocket.tmuxArgs(["has-session", "-t", target]), { stdio: "ignore", env: ptyEnv() });
     if (!tmuxKillVerified(killed, verified)) {
@@ -7590,6 +8723,7 @@ class WebTerminalManager {
     this.tombstones[terminalId] = Date.now();
     saveTombstones(this.tombstones);
     this.notifyTracker.remove(terminalId);
+    this.forgetAgentHooks(terminalId);
     logger.logger.debug(`[WEB TERMINAL] killed session vh-${terminalId}`);
     this.kickListRefresh();
     return true;
@@ -7691,6 +8825,25 @@ class WebTerminalManager {
    *  you've opened this daemon lifetime costs nothing. Cold tmux-only sessions
    *  (pty reaped / never attached) fall back to the tmux probe. */
   probeAgentState(sessionName, polledCommand) {
+    const id = sessionName.startsWith("vh-") ? sessionName.slice(3) : sessionName;
+    if (polledCommand) this.lastPolledIdentity.set(id, polledCommand);
+    const screen = this.probeScreenState(sessionName, polledCommand);
+    const now = Date.now();
+    const fused = this.agentHooks.fuse(id, screenObservation(screen), now);
+    if (fused.source === "screen") {
+      this.hookSourced.delete(id);
+      return screen;
+    }
+    this.hookSourced.add(id);
+    return {
+      agentState: fused.agentState,
+      agentKind: fused.agentKind,
+      agentObservedAt: screen.agentObservedAt ?? now,
+      claudeConfident: screen.claudeConfident
+    };
+  }
+  /** The screen classifier alone (pre-B-547 probeAgentState). */
+  probeScreenState(sessionName, polledCommand) {
     const id = sessionName.startsWith("vh-") ? sessionName.slice(3) : sessionName;
     const live = this.terminals.get(id);
     if (live) {
@@ -7885,7 +9038,7 @@ class WebTerminalManager {
   }
 }
 
-const UUID_RE$2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const UUID_RE$4 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 async function listClaudeProjectDirs(projectsRoot) {
   let names;
   try {
@@ -7916,7 +9069,7 @@ async function collectCandidates$1(projectDirs, exclude) {
     for (const name of names) {
       if (!name.endsWith(".jsonl")) continue;
       const id = name.slice(0, -".jsonl".length);
-      if (!UUID_RE$2.test(id) || exclude.has(id.toLowerCase())) continue;
+      if (!UUID_RE$4.test(id) || exclude.has(id.toLowerCase())) continue;
       const path$1 = path.join(dir, name);
       try {
         const s = await promises.stat(path$1);
@@ -7945,11 +9098,11 @@ async function readHead$1(path, bytes) {
     await fh.close();
   }
 }
-function oneLine$1(text, max) {
+function oneLine$2(text, max) {
   const collapsed = text.replace(/\s+/g, " ").trim();
   return collapsed.length > max ? `${collapsed.slice(0, max - 1)}\u2026` : collapsed;
 }
-function parseTimestamp$1(raw) {
+function parseTimestamp$2(raw) {
   if (typeof raw === "number" && Number.isFinite(raw)) return raw;
   if (typeof raw === "string") {
     const t = Date.parse(raw);
@@ -7976,7 +9129,7 @@ function parseClaudeHistoryHead(head, promptChars) {
     }
     if (!parsed || typeof parsed !== "object") continue;
     if (parsed.type === "summary" && typeof parsed.summary === "string" && !summary) {
-      const s = oneLine$1(parsed.summary, promptChars);
+      const s = oneLine$2(parsed.summary, promptChars);
       if (s) summary = s;
       continue;
     }
@@ -7984,7 +9137,7 @@ function parseClaudeHistoryHead(head, promptChars) {
     if (typeof parsed.entrypoint === "string" && parsed.entrypoint && !entrypoint) entrypoint = parsed.entrypoint;
     if (typeof parsed.gitBranch === "string" && parsed.gitBranch && !gitBranch) gitBranch = parsed.gitBranch;
     if (typeof parsed.version === "string" && parsed.version && !version) version = parsed.version;
-    if (startedAt === null) startedAt = parseTimestamp$1(parsed.timestamp);
+    if (startedAt === null) startedAt = parseTimestamp$2(parsed.timestamp);
     if (!firstPrompt && parsed.type === "user" && !parsed.isSidechain) {
       const content = parsed.message?.content;
       let text = null;
@@ -7996,7 +9149,7 @@ function parseClaudeHistoryHead(head, promptChars) {
       }
       if (text) {
         if (oneShotPrompts.isVeryHappyOneShotPrompt(text)) return null;
-        const cleaned = oneLine$1(stripHarnessTags(text), promptChars);
+        const cleaned = oneLine$2(stripHarnessTags(text), promptChars);
         if (cleaned) firstPrompt = cleaned;
       }
     }
@@ -8050,8 +9203,8 @@ async function listClaudeSessionHistory(options) {
   return { entries, truncated, scanned };
 }
 
-const UUID_RE$1 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const ROLLOUT_RE = /^rollout-.*-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+const UUID_RE$3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ROLLOUT_RE$1 = /^rollout-.*-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
 const VERY_HAPPY_CODEX_ORIGINATOR = "happy-codex";
 function getCodexHomeDir() {
   return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
@@ -8073,7 +9226,7 @@ async function collectCandidates(root, exclude) {
     }
     for (const name of names) {
       const full = path.join(dir, name);
-      const match = ROLLOUT_RE.exec(name);
+      const match = ROLLOUT_RE$1.exec(name);
       if (match) {
         const id = match[1].toLowerCase();
         if (exclude.has(id)) continue;
@@ -8111,11 +9264,11 @@ async function readHead(path, bytes) {
     await fh.close();
   }
 }
-function oneLine(text, max) {
+function oneLine$1(text, max) {
   const collapsed = text.replace(/\s+/g, " ").trim();
   return collapsed.length > max ? `${collapsed.slice(0, max - 1)}\u2026` : collapsed;
 }
-function parseTimestamp(raw) {
+function parseTimestamp$1(raw) {
   if (typeof raw === "number" && Number.isFinite(raw)) return raw;
   if (typeof raw === "string") {
     const t = Date.parse(raw);
@@ -8171,14 +9324,14 @@ function parseCodexHistoryHead(head, promptChars) {
     if (parsed.type === "session_meta" && payload && typeof payload === "object") {
       if (isCodexSubThread(payload)) return null;
       sawMeta = true;
-      if (typeof payload.id === "string" && UUID_RE$1.test(payload.id)) id = payload.id.toLowerCase();
+      if (typeof payload.id === "string" && UUID_RE$3.test(payload.id)) id = payload.id.toLowerCase();
       if (typeof payload.cwd === "string" && payload.cwd) cwd = payload.cwd;
       if (typeof payload.source === "string" && payload.source) entrypoint = payload.source;
       if (typeof payload.originator === "string" && payload.originator) originator = payload.originator;
       if (typeof payload.cli_version === "string" && payload.cli_version) version = payload.cli_version;
       const branch = payload.git && typeof payload.git === "object" ? payload.git.branch : void 0;
       if (typeof branch === "string" && branch) gitBranch = branch;
-      startedAt = parseTimestamp(payload.timestamp) ?? parseTimestamp(parsed.timestamp);
+      startedAt = parseTimestamp$1(payload.timestamp) ?? parseTimestamp$1(parsed.timestamp);
       continue;
     }
     if (!sawMeta) return null;
@@ -8186,11 +9339,11 @@ function parseCodexHistoryHead(head, promptChars) {
     if (!payload || typeof payload !== "object") continue;
     if (parsed.type === "event_msg") {
       if (payload.type === "user_message" && typeof payload.message === "string") {
-        const cleaned = oneLine(stripHarnessBlocks(payload.message), promptChars);
+        const cleaned = oneLine$1(stripHarnessBlocks(payload.message), promptChars);
         if (cleaned) firstPrompt = cleaned;
       } else if (payload.type === "item_completed" && payload.item && payload.item.type === "UserMessage") {
         const text = textFromUserContent(payload.item.content);
-        const cleaned = text ? oneLine(stripHarnessBlocks(text), promptChars) : "";
+        const cleaned = text ? oneLine$1(stripHarnessBlocks(text), promptChars) : "";
         if (cleaned) firstPrompt = cleaned;
       }
       continue;
@@ -8198,7 +9351,7 @@ function parseCodexHistoryHead(head, promptChars) {
     if (parsed.type === "response_item" && payload.type === "message" && payload.role === "user" && !fallbackPrompt) {
       const text = textFromUserContent(payload.content);
       if (text && !isHarnessUserText(text)) {
-        const cleaned = oneLine(stripHarnessBlocks(text), promptChars);
+        const cleaned = oneLine$1(stripHarnessBlocks(text), promptChars);
         if (cleaned) fallbackPrompt = cleaned;
       }
     }
@@ -8228,7 +9381,7 @@ function parseCodexSessionIndex(text) {
       continue;
     }
     if (!parsed || typeof parsed !== "object") continue;
-    if (typeof parsed.id !== "string" || !UUID_RE$1.test(parsed.id)) continue;
+    if (typeof parsed.id !== "string" || !UUID_RE$3.test(parsed.id)) continue;
     if (typeof parsed.thread_name !== "string" || !parsed.thread_name.trim()) continue;
     names.set(parsed.id.toLowerCase(), parsed.thread_name.trim());
   }
@@ -8279,12 +9432,819 @@ async function listCodexSessionHistory(options) {
       updatedAt: Math.round(candidate.updatedAt),
       sizeBytes: candidate.sizeBytes,
       ...rest,
-      ...summary ? { summary: oneLine(summary, promptChars) } : {}
+      ...summary ? { summary: oneLine$1(summary, promptChars) } : {}
     });
   }
   return { entries, truncated, scanned };
 }
 
+const MAX_MESSAGE_CHARS = 4e3;
+const MAX_SESSION_CHARS = 1e6;
+const MAX_TITLE_CHARS = 200;
+const UUID_RE$2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function emptyDocState() {
+  return { meta: {}, msgs: [], chars: 0 };
+}
+function oneLine(text, max) {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > max ? `${collapsed.slice(0, max - 1)}\u2026` : collapsed;
+}
+function parseTimestamp(raw) {
+  if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+  if (typeof raw === "string") {
+    const t = Date.parse(raw);
+    if (Number.isFinite(t)) return t;
+  }
+  return void 0;
+}
+function clip(text) {
+  const trimmed = text.trim();
+  return trimmed.length > MAX_MESSAGE_CHARS ? trimmed.slice(0, MAX_MESSAGE_CHARS) : trimmed;
+}
+function push(state, role, text, at) {
+  if (state.full) return;
+  const x = clip(text);
+  if (!x) return;
+  if (state.chars + x.length > MAX_SESSION_CHARS) {
+    state.full = true;
+    return;
+  }
+  state.msgs.push(at === void 0 ? { r: role, x } : { r: role, t: at, x });
+  state.chars += x.length;
+}
+const CLAUDE_HARNESS_BLOCK = /<(system-reminder|task-notification|command-message|command-name|local-command-stdout|local-command-stderr|local-command-caveat|bash-input|bash-stdout|bash-stderr|user-prompt-submit-hook)>[\s\S]*?<\/\1>/g;
+const CLAUDE_HARNESS_TAG = /<\/?(system-reminder|task-notification|command-message|command-name|command-args|local-command-stdout|local-command-stderr|local-command-caveat|bash-input|bash-stdout|bash-stderr|user-prompt-submit-hook)>/g;
+function stripClaudeHarness(text) {
+  return text.replace(CLAUDE_HARNESS_BLOCK, " ").replace(CLAUDE_HARNESS_TAG, " ");
+}
+function claudeText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return null;
+  const parts = [];
+  for (const block of content) {
+    if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
+      parts.push(block.text);
+    }
+  }
+  return parts.length > 0 ? parts.join("\n") : null;
+}
+function codexText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return null;
+  const parts = [];
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+    const type = part.type;
+    const text = part.text;
+    if ((type === "input_text" || type === "output_text" || type === "text") && typeof text === "string") parts.push(text);
+  }
+  return parts.length > 0 ? parts.join("\n") : null;
+}
+function lineMayMatter(agent, line) {
+  if (agent === "claude") {
+    return line.includes('"user"') || line.includes('"assistant"') || line.includes('"summary"');
+  }
+  return line.includes('"session_meta"') || line.includes('"message"');
+}
+function extractClaudeLine(state, line) {
+  if (state.meta.skip || !line || !lineMayMatter("claude", line)) return;
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return;
+  }
+  if (!parsed || typeof parsed !== "object") return;
+  const meta = state.meta;
+  if (parsed.type === "summary") {
+    if (typeof parsed.summary === "string" && !meta.summary) {
+      const s = oneLine(parsed.summary, MAX_TITLE_CHARS);
+      if (s) meta.summary = s;
+    }
+    return;
+  }
+  if (parsed.isSidechain) return;
+  if (parsed.isMeta || parsed.isCompactSummary) return;
+  if (typeof parsed.cwd === "string" && parsed.cwd && !meta.cwd) meta.cwd = parsed.cwd;
+  if (typeof parsed.gitBranch === "string" && parsed.gitBranch && !meta.gitBranch) meta.gitBranch = parsed.gitBranch;
+  if (typeof parsed.entrypoint === "string" && parsed.entrypoint && !meta.entrypoint) meta.entrypoint = parsed.entrypoint;
+  if (typeof parsed.version === "string" && parsed.version && !meta.version) meta.version = parsed.version;
+  const at = parseTimestamp(parsed.timestamp);
+  if (meta.startedAt === void 0 && at !== void 0) meta.startedAt = at;
+  if (parsed.type !== "user" && parsed.type !== "assistant") return;
+  const raw = claudeText(parsed.message?.content);
+  if (!raw) return;
+  if (parsed.type === "user") {
+    if (!meta.firstPrompt) {
+      if (oneShotPrompts.isVeryHappyOneShotPrompt(raw)) {
+        meta.skip = "one-shot";
+        state.msgs = [];
+        state.chars = 0;
+        return;
+      }
+    }
+    const text = stripClaudeHarness(raw);
+    if (!meta.firstPrompt) {
+      const first = oneLine(text, MAX_TITLE_CHARS);
+      if (first) meta.firstPrompt = first;
+    }
+    push(state, "u", text, at);
+    return;
+  }
+  push(state, "a", raw, at);
+}
+function extractCodexLine(state, line) {
+  if (state.meta.skip || !line) return;
+  const meta = state.meta;
+  if (!meta.sawMeta) {
+    let first;
+    try {
+      first = JSON.parse(line);
+    } catch {
+      meta.skip = "not-rollout";
+      return;
+    }
+    const payload2 = first?.payload;
+    if (first?.type !== "session_meta" || !payload2 || typeof payload2 !== "object") {
+      meta.skip = "not-rollout";
+      return;
+    }
+    if (isCodexSubThread(payload2)) {
+      meta.skip = "subthread";
+      return;
+    }
+    meta.sawMeta = true;
+    if (typeof payload2.id === "string" && UUID_RE$2.test(payload2.id)) meta.id = payload2.id.toLowerCase();
+    if (typeof payload2.cwd === "string" && payload2.cwd) meta.cwd = payload2.cwd;
+    if (typeof payload2.source === "string" && payload2.source) meta.entrypoint = payload2.source;
+    if (typeof payload2.originator === "string" && payload2.originator) meta.originator = payload2.originator;
+    if (typeof payload2.cli_version === "string" && payload2.cli_version) meta.version = payload2.cli_version;
+    const branch = payload2.git && typeof payload2.git === "object" ? payload2.git.branch : void 0;
+    if (typeof branch === "string" && branch) meta.gitBranch = branch;
+    const at2 = parseTimestamp(payload2.timestamp) ?? parseTimestamp(first.timestamp);
+    if (at2 !== void 0) meta.startedAt = at2;
+    return;
+  }
+  if (!lineMayMatter("codex", line)) return;
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return;
+  }
+  const payload = parsed?.payload;
+  if (parsed?.type !== "response_item" || !payload || payload.type !== "message") return;
+  if (payload.role !== "user" && payload.role !== "assistant") return;
+  const raw = codexText(payload.content);
+  if (!raw) return;
+  const at = parseTimestamp(parsed.timestamp);
+  if (payload.role === "user") {
+    if (isHarnessUserText(raw)) return;
+    const text = stripHarnessBlocks(raw);
+    if (!meta.firstPrompt) {
+      const first = oneLine(text, MAX_TITLE_CHARS);
+      if (first) meta.firstPrompt = first;
+    }
+    push(state, "u", text, at);
+    return;
+  }
+  push(state, "a", raw, at);
+}
+function extractLine(agent, state, line) {
+  if (agent === "claude") extractClaudeLine(state, line);
+  else extractCodexLine(state, line);
+}
+
+const INDEX_VERSION = 1;
+const INDEX_FILE_NAME = `index.v${INDEX_VERSION}.jsonl`;
+const DEFAULT_MAX_TEXT_CHARS = 32e6;
+function planFile(prev, cur) {
+  if (!prev) return "reread";
+  if (prev.ino !== cur.ino) return "reread";
+  if (cur.size === prev.size && cur.mtimeMs === prev.mtimeMs) return "skip";
+  if (cur.size < prev.offset || cur.size < prev.size) return "reread";
+  if (cur.size === prev.size) return "reread";
+  return prev.evicted ? "reread" : "append";
+}
+function totalChars(records) {
+  let sum = 0;
+  for (const r of records) sum += r.chars;
+  return sum;
+}
+function enforceTextCap(records, maxChars) {
+  let total = totalChars(records.values());
+  if (total <= maxChars) return 0;
+  const byAge = [...records.values()].filter((r) => r.chars > 0).sort((a, b) => a.mtimeMs - b.mtimeMs);
+  let evicted = 0;
+  for (const r of byAge) {
+    if (total <= maxChars) break;
+    total -= r.chars;
+    r.msgs = [];
+    r.chars = 0;
+    r.evicted = true;
+    evicted += 1;
+  }
+  return evicted;
+}
+function serializeIndex(records, savedAt) {
+  const lines = [JSON.stringify({ v: INDEX_VERSION, savedAt })];
+  for (const r of records) lines.push(JSON.stringify(r));
+  return lines.join("\n") + "\n";
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && typeof value.path === "string" && (value.agent === "claude" || value.agent === "codex") && typeof value.id === "string" && typeof value.ino === "number" && typeof value.size === "number" && typeof value.mtimeMs === "number" && typeof value.offset === "number" && !!value.meta && typeof value.meta === "object" && Array.isArray(value.msgs) && typeof value.chars === "number";
+}
+function parseIndex(text) {
+  const lines = text.split("\n");
+  let header;
+  try {
+    header = JSON.parse(lines[0] ?? "");
+  } catch {
+    return null;
+  }
+  if (!header || header.v !== INDEX_VERSION || typeof header.savedAt !== "number") return null;
+  const records = /* @__PURE__ */ new Map();
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (isRecord(parsed)) records.set(parsed.path, parsed);
+  }
+  return { savedAt: header.savedAt, records };
+}
+function indexFilePath(indexDir) {
+  return path.join(indexDir, INDEX_FILE_NAME);
+}
+async function loadIndex(indexDir) {
+  let text;
+  try {
+    text = await promises.readFile(indexFilePath(indexDir), "utf-8");
+  } catch {
+    return null;
+  }
+  return parseIndex(text);
+}
+async function saveIndex(indexDir, records, savedAt) {
+  await promises.mkdir(indexDir, { recursive: true, mode: 448 });
+  try {
+    await promises.chmod(indexDir, 448);
+  } catch {
+  }
+  const target = indexFilePath(indexDir);
+  const tmp = `${target}.${process.pid}.tmp`;
+  await promises.writeFile(tmp, serializeIndex(records, savedAt), { mode: 384 });
+  await promises.rename(tmp, target);
+}
+async function clearIndexDir(indexDir) {
+  await promises.rm(indexDir, { recursive: true, force: true });
+}
+
+const UUID_RE$1 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ROLLOUT_RE = /^rollout-.*-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+const MAX_LINE_BYTES = 2 * 1024 * 1024;
+const READ_CHUNK_BYTES = 1024 * 1024;
+async function statFile(path) {
+  try {
+    const s = await promises.stat(path);
+    if (!s.isFile()) return null;
+    return { ino: Number(s.ino) || 0, size: s.size, mtimeMs: s.mtimeMs };
+  } catch {
+    return null;
+  }
+}
+async function listDir(path) {
+  try {
+    return await promises.readdir(path);
+  } catch {
+    return [];
+  }
+}
+async function isDir(path) {
+  try {
+    return (await promises.stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function discoverClaudeFiles(projectsRoot) {
+  const out = [];
+  for (const dirName of await listDir(projectsRoot)) {
+    const dir = path.join(projectsRoot, dirName);
+    if (!await isDir(dir)) continue;
+    for (const name of await listDir(dir)) {
+      if (!name.endsWith(".jsonl")) continue;
+      const id = name.slice(0, -".jsonl".length);
+      if (!UUID_RE$1.test(id)) continue;
+      const path$1 = path.join(dir, name);
+      const s = await statFile(path$1);
+      if (!s || s.size === 0) continue;
+      out.push({ path: path$1, agent: "claude", id: id.toLowerCase(), ...s });
+    }
+  }
+  return out;
+}
+async function discoverCodexFiles(sessionsRoot) {
+  const out = [];
+  async function walk(dir, depth) {
+    for (const name of await listDir(dir)) {
+      const full = path.join(dir, name);
+      const match = ROLLOUT_RE.exec(name);
+      if (match) {
+        const s = await statFile(full);
+        if (s && s.size > 0) out.push({ path: full, agent: "codex", id: match[1].toLowerCase(), ...s });
+        continue;
+      }
+      if (name.endsWith(".jsonl") || depth >= 4) continue;
+      if (await isDir(full)) await walk(full, depth + 1);
+    }
+  }
+  await walk(sessionsRoot, 0);
+  return out;
+}
+async function readCompleteLines(path, start, onLine, maxLineBytes = MAX_LINE_BYTES) {
+  const fh = await promises.open(path, "r");
+  try {
+    const buf = Buffer.allocUnsafe(READ_CHUNK_BYTES);
+    let pos = start;
+    let committed = start;
+    let pending = [];
+    let pendingLen = 0;
+    let skipping = false;
+    for (; ; ) {
+      const { bytesRead } = await fh.read(buf, 0, buf.length, pos);
+      if (bytesRead === 0) break;
+      let i = 0;
+      while (i < bytesRead) {
+        const nl = buf.indexOf(10, i);
+        if (nl === -1 || nl >= bytesRead) {
+          const rest = bytesRead - i;
+          if (!skipping) {
+            if (pendingLen + rest > maxLineBytes) {
+              skipping = true;
+              pending = [];
+              pendingLen = 0;
+            } else {
+              pending.push(Buffer.from(buf.subarray(i, bytesRead)));
+              pendingLen += rest;
+            }
+          }
+          break;
+        }
+        if (!skipping) {
+          const seg = buf.subarray(i, nl);
+          if (pendingLen + seg.length <= maxLineBytes) {
+            const line = pendingLen > 0 ? Buffer.concat([...pending, seg]).toString("utf-8") : seg.toString("utf-8");
+            onLine(line.endsWith("\r") ? line.slice(0, -1) : line);
+          }
+        }
+        pending = [];
+        pendingLen = 0;
+        skipping = false;
+        committed = pos + nl + 1;
+        i = nl + 1;
+      }
+      pos += bytesRead;
+    }
+    return committed;
+  } finally {
+    await fh.close();
+  }
+}
+async function indexFile(file, prev, plan) {
+  const base = plan === "append" && prev ? { meta: { ...prev.meta }, msgs: prev.msgs.slice(), chars: prev.chars, ...prev.full ? { full: true } : {} } : emptyDocState();
+  const start = plan === "append" && prev ? prev.offset : 0;
+  let offset = start;
+  if (!base.meta.skip) {
+    offset = await readCompleteLines(file.path, start, (line) => extractLine(file.agent, base, line));
+  } else {
+    offset = file.size;
+  }
+  if (base.meta.skip) {
+    base.msgs = [];
+    base.chars = 0;
+  }
+  return {
+    path: file.path,
+    agent: file.agent,
+    id: file.agent === "codex" && base.meta.id ? base.meta.id : file.id,
+    ino: file.ino,
+    size: file.size,
+    mtimeMs: file.mtimeMs,
+    offset,
+    meta: base.meta,
+    msgs: base.msgs,
+    chars: base.chars,
+    ...base.full ? { full: true } : {}
+  };
+}
+const yieldToLoop = () => new Promise((resolve) => setImmediate(resolve));
+async function refreshRecords(records, options) {
+  const now = options.now ?? Date.now;
+  const cancelled = () => options.isCancelled?.() === true;
+  const [claude, codex, names] = await Promise.all([
+    discoverClaudeFiles(options.roots.claudeProjectsRoot),
+    discoverCodexFiles(options.roots.codexSessionsRoot),
+    promises.readFile(options.roots.codexIndexPath, "utf-8").then(parseCodexSessionIndex, () => /* @__PURE__ */ new Map())
+  ]);
+  if (cancelled()) return { changed: false, cancelled: true, evicted: 0, filesTotal: 0 };
+  const files = [...claude, ...codex];
+  files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const total = files.length;
+  let changed = false;
+  const present = new Set(files.map((f) => f.path));
+  for (const path of [...records.keys()]) {
+    if (!present.has(path)) {
+      records.delete(path);
+      changed = true;
+    }
+  }
+  let done = 0;
+  let lastCheckpoint = now();
+  options.onProgress?.({ filesTotal: total, filesDone: 0 });
+  for (const file of files) {
+    if (cancelled()) return { changed, cancelled: true, evicted: 0, filesTotal: total };
+    const prev = records.get(file.path);
+    const plan = planFile(prev, file);
+    if (plan !== "skip") {
+      try {
+        const next = await indexFile(file, prev, plan);
+        if (cancelled()) return { changed, cancelled: true, evicted: 0, filesTotal: total };
+        records.set(file.path, next);
+        changed = true;
+      } catch {
+      }
+      await yieldToLoop();
+    }
+    done += 1;
+    if (done % 50 === 0 || done === total) options.onProgress?.({ filesTotal: total, filesDone: done });
+    if (options.checkpoint && changed && now() - lastCheckpoint >= (options.checkpointEveryMs ?? 2e4)) {
+      lastCheckpoint = now();
+      await options.checkpoint();
+    }
+  }
+  for (const record of records.values()) {
+    if (record.agent !== "codex") continue;
+    const name = names.get(record.id);
+    if (name && record.meta.summary !== name) {
+      record.meta = { ...record.meta, summary: name };
+      changed = true;
+    }
+  }
+  const evicted = enforceTextCap(records, options.maxTextChars);
+  if (evicted > 0) changed = true;
+  options.onProgress?.({ filesTotal: total, filesDone: total });
+  return { changed, cancelled: false, evicted, filesTotal: total };
+}
+
+const MAX_QUERY_CHARS = 200;
+const MAX_QUERY_TERMS = 8;
+const MAX_RESULTS = 50;
+const DEFAULT_RESULTS = 20;
+const MAX_SNIPPETS = 3;
+const SNIPPET_CHARS = 180;
+const SNIPPET_LEAD = 50;
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function parseQuery(input) {
+  if (typeof input !== "string") return null;
+  const raw = input.replace(/\s+/g, " ").trim().slice(0, MAX_QUERY_CHARS).trim();
+  if (!raw) return null;
+  const words = [...new Set(raw.split(" ").filter(Boolean).map((w) => w.toLowerCase()))].slice(0, MAX_QUERY_TERMS);
+  const terms = words.map((w) => new RegExp(escapeRegExp(w), "i"));
+  const phrase = words.length > 1 ? new RegExp(raw.split(" ").map(escapeRegExp).join("\\s+"), "i") : null;
+  return { terms, phrase, raw };
+}
+function matchRanges(text, terms) {
+  const ranges = [];
+  for (const term of terms) {
+    const global = new RegExp(term.source, "gi");
+    let m;
+    while ((m = global.exec(text)) !== null) {
+      if (m[0].length === 0) {
+        global.lastIndex += 1;
+        continue;
+      }
+      ranges.push([m.index, m.index + m[0].length]);
+      if (ranges.length > 64) break;
+    }
+  }
+  ranges.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  const merged = [];
+  for (const r of ranges) {
+    const last = merged[merged.length - 1];
+    if (last && r[0] <= last[1]) last[1] = Math.max(last[1], r[1]);
+    else merged.push([r[0], r[1]]);
+  }
+  return merged;
+}
+function buildSnippet(text, terms) {
+  let first = -1;
+  for (const term of terms) {
+    const m = term.exec(text);
+    if (m && (first === -1 || m.index < first)) first = m.index;
+  }
+  const start = Math.max(0, (first === -1 ? 0 : first) - SNIPPET_LEAD);
+  const end = Math.min(text.length, start + SNIPPET_CHARS);
+  let window = text.slice(start, end).replace(/\s+/g, " ");
+  if (start > 0) window = `\u2026${window.trimStart()}`;
+  if (end < text.length) window = `${window.trimEnd()}\u2026`;
+  return { text: window, ranges: matchRanges(window, terms) };
+}
+function titleOf(record) {
+  return record.meta.summary || record.meta.firstPrompt || "";
+}
+function searchRecords(records, query, options = {}) {
+  const limit = Math.max(1, Math.min(Math.floor(options.limit ?? DEFAULT_RESULTS), MAX_RESULTS));
+  const newest = /* @__PURE__ */ new Map();
+  for (const r of records) {
+    if (r.meta.skip || !r.meta.cwd) continue;
+    if (options.agent && r.agent !== options.agent) continue;
+    if (!r.meta.firstPrompt && !r.meta.summary) continue;
+    const key = `${r.agent}:${r.id}`;
+    const prev = newest.get(key);
+    if (!prev || r.mtimeMs > prev.mtimeMs) newest.set(key, r);
+  }
+  const scored = [];
+  for (const record of newest.values()) {
+    const title = titleOf(record);
+    const head = `${title}
+${record.meta.firstPrompt ?? ""}
+${record.meta.cwd ?? ""}`;
+    const found = new Array(query.terms.length).fill(false);
+    query.terms.forEach((t, i) => {
+      if (t.test(head)) found[i] = true;
+    });
+    const matched = [];
+    let phrase = query.phrase ? query.phrase.test(head) : true;
+    record.msgs.forEach((msg, index) => {
+      let n = 0;
+      query.terms.forEach((t, i) => {
+        if (t.test(msg.x)) {
+          n += 1;
+          found[i] = true;
+        }
+      });
+      if (n > 0) {
+        matched.push({ msg, hits: n, index });
+        if (!phrase && query.phrase && query.phrase.test(msg.x)) phrase = true;
+      }
+    });
+    if (!found.every(Boolean)) continue;
+    scored.push({ record, phrase, matched });
+  }
+  scored.sort((a, b) => Number(b.phrase) - Number(a.phrase) || b.record.mtimeMs - a.record.mtimeMs);
+  const results = scored.slice(0, limit).map(({ record, matched }) => {
+    const picks = matched.slice().sort((a, b) => b.hits - a.hits || a.index - b.index).slice(0, MAX_SNIPPETS).sort((a, b) => a.index - b.index);
+    const meta = record.meta;
+    return {
+      agent: record.agent,
+      id: record.id,
+      title: titleOf(record),
+      firstPrompt: meta.firstPrompt ?? meta.summary ?? "",
+      ...meta.summary ? { summary: meta.summary } : {},
+      cwd: meta.cwd ?? "",
+      startedAt: meta.startedAt ?? 0,
+      updatedAt: Math.round(record.mtimeMs),
+      sizeBytes: record.size,
+      ...meta.gitBranch ? { gitBranch: meta.gitBranch } : {},
+      ...meta.entrypoint ? { entrypoint: meta.entrypoint } : {},
+      ...meta.originator ? { originator: meta.originator } : {},
+      matchCount: matched.length,
+      snippets: picks.map(({ msg }) => {
+        const s = buildSnippet(msg.x, query.terms);
+        return {
+          role: msg.r === "u" ? "user" : "assistant",
+          text: s.text,
+          ...msg.t !== void 0 ? { at: msg.t } : {},
+          ranges: s.ranges
+        };
+      })
+    };
+  });
+  return { results, truncated: scored.length > limit, total: scored.length };
+}
+
+class HistorySearchService {
+  records = null;
+  loading = null;
+  refreshing = null;
+  progress = { filesTotal: 0, filesDone: 0 };
+  lastRefreshStartedAt = 0;
+  lastIndexedAt;
+  error;
+  /** Bumped by `clear`; a pass started under an older generation stops. */
+  generation = 0;
+  /** A `clear` in progress. Searches arriving meanwhile neither load the
+   *  old file back nor start a pass that would recreate the directory. */
+  clearing = null;
+  idleTimer = null;
+  opts;
+  constructor(options) {
+    this.opts = {
+      maxTextChars: DEFAULT_MAX_TEXT_CHARS,
+      refreshIntervalMs: 3e4,
+      idleUnloadMs: 10 * 6e4,
+      loadWaitMs: 5e3,
+      now: Date.now,
+      ...options
+    };
+  }
+  /** RPC entry point. Validates loosely; unknown fields are ignored. */
+  async handle(params) {
+    const p = params && typeof params === "object" ? params : {};
+    const op = p.op === "status" || p.op === "clear" ? p.op : "search";
+    if (op === "clear") {
+      await this.clear();
+      return { type: "success", status: this.status(), results: [], truncated: false };
+    }
+    if (op === "status") {
+      return { type: "success", status: this.status(), results: [], truncated: false };
+    }
+    const agent = p.agent === "claude" || p.agent === "codex" ? p.agent : void 0;
+    const limit = typeof p.limit === "number" && Number.isFinite(p.limit) ? p.limit : DEFAULT_RESULTS;
+    return this.search(p.query, { agent, limit });
+  }
+  async search(query, options = {}) {
+    if (this.clearing) {
+      await this.clearing;
+      return { type: "success", status: this.status(), results: [], truncated: false };
+    }
+    this.touch();
+    await this.ensureLoaded();
+    this.maybeRefresh();
+    const parsed = parseQuery(query);
+    if (!parsed || !this.records) {
+      return { type: "success", status: this.status(), results: [], truncated: false };
+    }
+    const started = this.opts.now();
+    const out = searchRecords(this.records.values(), parsed, options);
+    logger.logger.debug(`[HISTORY SEARCH] query len=${parsed.raw.length} terms=${parsed.terms.length} \u2192 ${out.total} sessions (${this.opts.now() - started}ms)`);
+    return { type: "success", status: this.status(), results: out.results, truncated: out.truncated };
+  }
+  status() {
+    const records = this.records;
+    let sessions = 0;
+    let evicted = 0;
+    if (records) {
+      for (const r of records.values()) {
+        if (r.meta.skip) continue;
+        sessions += 1;
+        if (r.evicted) evicted += 1;
+      }
+    }
+    const state = this.refreshing || this.loading ? "indexing" : this.error ? "error" : this.lastIndexedAt !== void 0 ? "ready" : "idle";
+    return {
+      state,
+      filesTotal: this.progress.filesTotal,
+      filesDone: this.progress.filesDone,
+      sessions,
+      textChars: records ? totalChars(records.values()) : 0,
+      maxTextChars: this.opts.maxTextChars,
+      evicted,
+      ...this.lastIndexedAt !== void 0 ? { lastIndexedAt: this.lastIndexedAt } : {},
+      ...this.error ? { error: this.error } : {}
+    };
+  }
+  async clear() {
+    if (this.clearing) return this.clearing;
+    const run = this.doClear().finally(() => {
+      if (this.clearing === run) this.clearing = null;
+    });
+    this.clearing = run;
+    return run;
+  }
+  async doClear() {
+    const running = this.refreshing;
+    this.generation += 1;
+    this.records = null;
+    this.loading = null;
+    this.refreshing = null;
+    this.progress = { filesTotal: 0, filesDone: 0 };
+    this.lastRefreshStartedAt = 0;
+    this.lastIndexedAt = void 0;
+    this.error = void 0;
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+    await running?.catch(() => void 0);
+    await clearIndexDir(this.opts.indexDir);
+    logger.logger.debug("[HISTORY SEARCH] index cleared");
+  }
+  /** Resolves when the running refresh (if any) is done — tests and scripts. */
+  async whenIdle() {
+    while (this.loading || this.refreshing) {
+      await (this.loading ?? this.refreshing);
+    }
+  }
+  touch() {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => this.unload(), this.opts.idleUnloadMs);
+    this.idleTimer.unref?.();
+  }
+  unload() {
+    this.idleTimer = null;
+    if (this.refreshing || this.loading) {
+      this.touch();
+      return;
+    }
+    this.records = null;
+    logger.logger.debug("[HISTORY SEARCH] in-memory index unloaded (idle)");
+  }
+  async ensureLoaded() {
+    if (this.clearing) await this.clearing;
+    if (this.records) return;
+    if (!this.loading) {
+      const gen = this.generation;
+      const run = (async () => {
+        const loaded = await loadIndex(this.opts.indexDir);
+        if (gen !== this.generation) return;
+        this.records = loaded?.records ?? /* @__PURE__ */ new Map();
+        if (loaded && this.lastIndexedAt === void 0) this.lastIndexedAt = loaded.savedAt;
+      })().catch((error) => {
+        if (gen !== this.generation) return;
+        logger.logger.debug("[HISTORY SEARCH] index load failed; starting empty", error);
+        this.records = /* @__PURE__ */ new Map();
+      }).finally(() => {
+        if (this.loading === run) this.loading = null;
+      });
+      this.loading = run;
+    }
+    const pending = this.loading;
+    let timer;
+    await Promise.race([
+      pending,
+      new Promise((resolve) => {
+        timer = setTimeout(resolve, this.opts.loadWaitMs);
+        timer.unref?.();
+      })
+    ]);
+    if (timer) clearTimeout(timer);
+  }
+  maybeRefresh() {
+    if (this.clearing || this.refreshing || !this.records) return;
+    const now = this.opts.now();
+    if (this.lastRefreshStartedAt && now - this.lastRefreshStartedAt < this.opts.refreshIntervalMs) return;
+    this.lastRefreshStartedAt = now;
+    const gen = this.generation;
+    const records = this.records;
+    const save = async () => {
+      if (gen !== this.generation || this.clearing) return;
+      await saveIndex(this.opts.indexDir, records.values(), this.opts.now());
+    };
+    const run = (async () => {
+      const roots = await this.opts.resolveRoots();
+      if (gen !== this.generation) return;
+      const started = this.opts.now();
+      const result = await refreshRecords(records, {
+        roots,
+        maxTextChars: this.opts.maxTextChars,
+        isCancelled: () => gen !== this.generation,
+        onProgress: (progress) => {
+          if (gen === this.generation) this.progress = progress;
+        },
+        checkpoint: async () => {
+          if (gen === this.generation) await save();
+        },
+        now: this.opts.now
+      });
+      if (result.cancelled || gen !== this.generation) return;
+      if (result.changed) await save();
+      this.lastIndexedAt = this.opts.now();
+      this.error = void 0;
+      logger.logger.debug(`[HISTORY SEARCH] refresh: ${result.filesTotal} files, changed=${result.changed}, evicted=${result.evicted} (${this.opts.now() - started}ms)`);
+    })().catch((error) => {
+      if (gen !== this.generation) return;
+      this.error = error instanceof Error ? error.message : String(error);
+      logger.logger.debug("[HISTORY SEARCH] refresh failed", error);
+    }).finally(() => {
+      if (this.refreshing === run) this.refreshing = null;
+    });
+    this.refreshing = run;
+  }
+}
+
+async function resolveHistoryRoots() {
+  const homes = await index.refreshAgentHomes(Date.now(), { allowStale: true });
+  return {
+    claudeProjectsRoot: path.join(homes.claudeConfigDir.path, "projects"),
+    codexSessionsRoot: path.join(homes.codexHome.path, "sessions"),
+    codexIndexPath: path.join(homes.codexHome.path, "session_index.jsonl")
+  };
+}
+function historySearchIndexDir() {
+  return path.join(configuration.configuration.happyHomeDir, "history-search");
+}
+function createHistorySearchService() {
+  return new HistorySearchService({ indexDir: historySearchIndexDir(), resolveRoots: resolveHistoryRoots });
+}
+
 function selectLowestLatencyRelay(candidates, probes) {
   const rttById = new Map(probes.map((probe) => [probe.relayId, probe.rttMs]));
   let selected = null;
@@ -8403,6 +10363,74 @@ async function discoverAndClaimRelay(input) {
   }
 }
 
+const RATE_LIMIT_MIN_WRITE_INTERVAL_MS = 6e4;
+const MAX_PENDING_REPORTS = 16;
+class RateLimitPublisher {
+  constructor(deps) {
+    this.deps = deps;
+    this.now = deps.now ?? Date.now;
+    this.minIntervalMs = deps.minIntervalMs ?? RATE_LIMIT_MIN_WRITE_INTERVAL_MS;
+    this.setTimer = deps.setTimer ?? ((fn, ms) => {
+      const handle = setTimeout(fn, ms);
+      handle.unref?.();
+      return handle;
+    });
+    this.clearTimer = deps.clearTimer ?? ((handle) => clearTimeout(handle));
+  }
+  pending = [];
+  timer = null;
+  writing = false;
+  lastWriteAt = 0;
+  stopped = false;
+  now;
+  minIntervalMs;
+  setTimer;
+  clearTimer;
+  report(report) {
+    if (this.stopped) return;
+    this.pending.push(report);
+    if (this.pending.length > MAX_PENDING_REPORTS) {
+      this.pending.splice(0, this.pending.length - MAX_PENDING_REPORTS);
+    }
+    this.schedule();
+  }
+  stop() {
+    this.stopped = true;
+    this.pending = [];
+    if (this.timer) this.clearTimer(this.timer);
+    this.timer = null;
+  }
+  schedule() {
+    if (this.timer || this.writing || this.stopped || this.pending.length === 0) return;
+    const wait = this.lastWriteAt === 0 ? 0 : Math.max(0, this.lastWriteAt + this.minIntervalMs - this.now());
+    this.timer = this.setTimer(() => {
+      this.timer = null;
+      void this.flush();
+    }, wait);
+  }
+  /** Exposed for tests; normally driven by the timer. */
+  async flush() {
+    if (this.writing || this.stopped) return;
+    const reports = this.pending;
+    this.pending = [];
+    if (!rateLimitWindows.planRateLimitWrite(this.deps.getCurrent(), reports, this.now())) return;
+    this.writing = true;
+    this.lastWriteAt = this.now();
+    let written = false;
+    try {
+      written = await this.deps.write(reports);
+    } catch {
+      written = false;
+    } finally {
+      this.writing = false;
+    }
+    if (!written && !this.stopped) {
+      this.pending = [...reports, ...this.pending].slice(-MAX_PENDING_REPORTS);
+    }
+    this.schedule();
+  }
+}
+
 const guardOptions = { log: (message) => logger.logger.debug(message) };
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function requireNonEmptyString(value, name) {
@@ -8434,6 +10462,9 @@ class ApiMachineClient {
     registerCommonHandlers.registerCommonHandlers(this.rpcHandlerManager, process.cwd());
     registerFsHandlers(this.rpcHandlerManager);
     registerTodoHandlers(this.rpcHandlerManager);
+    if (typeof configuration.configuration.happyHomeDir === "string") {
+      mirrorProtocol.registerWorktreeHandlers(this.rpcHandlerManager, mirrorProtocol.configureWorktreeService({ home: configuration.configuration.happyHomeDir, machineId: this.machine.id, log: (msg, err) => logger.logger.debug(msg, err) }));
+    }
     this.wireAutoRestoreReport();
   }
   socket;
@@ -8444,6 +10475,8 @@ class ApiMachineClient {
   keepAliveInterval = null;
   lastKnownCLIAvailability = null;
   lastKnownResumeSupport = null;
+  /** B-549: created on the first `history-search` call. */
+  historySearch = null;
   /** Wall-clock of the last CLI availability probe. Initialised as "already
    *  stale" so the FIRST keep-alive tick always probes and populates the
    *  machine metadata that a connecting/reconnecting web client reads. */
@@ -8453,6 +10486,13 @@ class ApiMachineClient {
   cliUpdateState = null;
   cliUpdatePushChain = Promise.resolve();
   claudeAuthState = null;
+  /** B-587: the machine's hibernation threshold, published as a capability. */
+  agentHibernationIdleMs = null;
+  rateLimitPushChain = Promise.resolve();
+  rateLimitPublisher = new RateLimitPublisher({
+    getCurrent: () => this.machine.daemonState?.rateLimits,
+    write: (reports) => this.writeRateLimits(reports)
+  });
   rpcHandlerManager;
   resumeSessionHandler = null;
   restartSessionHandler = null;
@@ -8513,6 +10553,11 @@ class ApiMachineClient {
   setTerminalTitle(terminalId, title, ifAbsent) {
     return this.webTerminal.setTitle(terminalId, title, ifAbsent);
   }
+  /** B-547: a status hook forwarded from a daemon-launched claude inside a
+   *  web terminal (control server /terminal-agent-hook → here). */
+  ingestTerminalAgentHook(body) {
+    this.webTerminal.ingestAgentHook(body);
+  }
   /**
    * Push text to the clipboard of every web client the user has open
    * (terminal-path claude → `very-happy mcp` → daemon /clipboard → here).
@@ -8536,13 +10581,14 @@ class ApiMachineClient {
     return { delivered: true, truncated: prepared.truncated, totalBytes: prepared.totalBytes };
   }
   /** Queue a terminal preview with the machine key. Delivery does not prove a browser opened it. */
-  pushFilePreview(terminalId, path, mode = "file") {
+  pushFilePreview(terminalId, path, mode = "file", intent) {
     if (!this.socket?.connected) return { delivered: false, error: "daemon is not connected to the server" };
     this.socket.emit("file-preview-push", {
       terminalId,
       payload: authRelay.encodeBase64(authRelay.encrypt(this.machine.encryptionKey, this.machine.encryptionVariant, path)),
       enc: true,
-      mode
+      mode,
+      ...intent ? { intent } : {}
     });
     return { delivered: true };
   }
@@ -8565,6 +10611,26 @@ class ApiMachineClient {
     if (!this.socket?.connected) return;
     this.cliUpdatePushChain = this.cliUpdatePushChain.then(() => this.updateDaemonState((current) => cliUpdate.withCurrentCliUpdateState(current, this.cliUpdateState))).catch((error) => logger.logger.debug("[API MACHINE] Failed to publish CLI update policy:", error));
   }
+  /** B-555: a wrapper's rate-limit observation; written throttled by the publisher. */
+  reportRateLimits(report) {
+    this.rateLimitPublisher.report(report);
+  }
+  writeRateLimits(reports) {
+    if (!this.socket?.connected) return Promise.resolve(false);
+    const attempt = this.rateLimitPushChain.then(() => this.updateDaemonState((current) => {
+      const merged = rateLimitWindows.mergeRateLimitReports(current?.rateLimits, reports, Date.now());
+      return {
+        ...current ?? {},
+        status: current?.status ?? "running",
+        ...merged ? { rateLimits: merged } : {}
+      };
+    })).then(() => true).catch((error) => {
+      logger.logger.debug("[API MACHINE] Failed to publish rate limits:", error);
+      return false;
+    });
+    this.rateLimitPushChain = attempt.then(() => void 0);
+    return attempt;
+  }
   /**
    * B-276: publish the daemon-context Claude auth preflight into daemonState
    * (same serialized push chain as the CLI update policy). Resolves true when
@@ -8586,6 +10652,34 @@ class ApiMachineClient {
     this.cliUpdatePushChain = attempt.then(() => void 0);
     return attempt;
   }
+  /**
+   * B-587: `agent-hibernation-set {idleMs}` (0 = off) and the
+   * `daemonState.agentHibernation` capability. Call before connect().
+   */
+  setAgentHibernationHandlers(initialIdleMs, set) {
+    this.agentHibernationIdleMs = initialIdleMs;
+    this.rpcHandlerManager.registerHandler("agent-hibernation-set", async (params) => {
+      const raw = params?.idleMs;
+      if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) return { error: "invalid-idle-ms" };
+      const idleMs = await set(raw);
+      this.agentHibernationIdleMs = idleMs;
+      await this.publishAgentHibernation();
+      return { agentHibernation: { idleMs } };
+    });
+  }
+  publishAgentHibernation() {
+    const idleMs = this.agentHibernationIdleMs;
+    if (idleMs === null || !this.socket?.connected) return Promise.resolve();
+    const attempt = this.cliUpdatePushChain.then(() => this.updateDaemonState((current) => ({
+      ...current ?? {},
+      status: current?.status ?? "running",
+      agentHibernation: { idleMs, rpcAvailable: true, detectedAt: Date.now() }
+    }))).catch((error) => {
+      logger.logger.debug("[API MACHINE] Failed to publish agent hibernation:", error);
+    });
+    this.cliUpdatePushChain = attempt.then(() => void 0);
+    return attempt;
+  }
   /** B-276 machine RPCs. Responses always carry `claudeAuth` so the web can refresh in place. */
   setClaudeAuthHandlers(handlers) {
     this.rpcHandlerManager.registerHandler("claude-auth-probe", async () => {
@@ -8915,6 +11009,10 @@ class ApiMachineClient {
       });
       return { type: "success", ...result };
     });
+    this.rpcHandlerManager.registerHandler("history-search", async (params) => {
+      this.historySearch ??= createHistorySearchService();
+      return this.historySearch.handle(params);
+    });
     this.rpcHandlerManager.registerHandler("codex-import-session", async (params) => {
       const { directory, codexThreadId, approvedNewDirectoryCreation, permissionMode, title } = params || {};
       if (typeof directory !== "string" || directory.length === 0) {
@@ -9293,13 +11391,17 @@ class ApiMachineClient {
         claudeHistory: { rpcAvailable: true, detectedAt: now },
         // B-464 capability flag: `codex-list-history` / `codex-import-session`.
         codexHistory: { rpcAvailable: true, detectedAt: now },
+        // B-549 capability flag: `history-search` (same restamp discipline).
+        historySearch: { rpcAvailable: true, detectedAt: now },
         // B-084: closed records survive daemon restarts (persisted
         // in closed-terminals.json), so the connect snapshot ships
         // them too — not just the incremental pushes.
         closedTerminals: this.webTerminal.getClosedTerminals(),
         // B-276: re-ship the last preflight so a reconnect never
         // leaves a stale-pid value visible longer than needed.
-        ...this.claudeAuthState ? { claudeAuth: this.claudeAuthState } : {}
+        ...this.claudeAuthState ? { claudeAuth: this.claudeAuthState } : {},
+        // B-587 capability + setting (same restamp discipline).
+        ...this.agentHibernationIdleMs !== null ? { agentHibernation: { idleMs: this.agentHibernationIdleMs, rpcAvailable: true, detectedAt: now } } : {}
       };
     });
     this.webTerminal.startListTracking((terminals) => this.pushTerminalList(terminals));
@@ -9595,9 +11697,14 @@ class ApiMachineClient {
       logger.logger.debug("[API MACHINE] Keep-alive stopped");
     }
   }
+  /** B-550: final terminal scrollback checkpoint; resolves within ~300ms, never rejects. */
+  flushTerminalScrollback() {
+    return this.webTerminal.flushScrollbackForShutdown().catch(() => void 0);
+  }
   shutdown() {
     logger.logger.debug("[API MACHINE] Shutting down");
     this.webTerminal.stopListTracking();
+    this.rateLimitPublisher.stop();
     this.stopKeepAlive();
     if (this.reconnectInterval) {
       clearInterval(this.reconnectInterval);