backthread 0.7.0 → 0.9.0

package/dist-bundle/backthread.js

@@ -6,7 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -6887,7 +6891,7 @@ var require_dist = __commonJS({
 
 // src/bin/backthread.ts
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { realpathSync } from "node:fs";
+import { realpathSync as realpathSync2 } from "node:fs";
 
 // src/login.ts
 import { hostname } from "node:os";
@@ -6945,7 +6949,7 @@ function browserCommand(platform) {
     case "darwin":
       return { cmd: "open", prefixArgs: [] };
     case "win32":
-      return { cmd: "cmd", prefixArgs: ["/c", "start", ""] };
+      return { cmd: "rundll32", prefixArgs: ["url.dll,FileProtocolHandler"] };
     default:
       return { cmd: "xdg-open", prefixArgs: [] };
   }
@@ -7258,7 +7262,7 @@ async function pollForToken(sessionId, keypair, opts = {}) {
       return { ok: false, reason: "expired", message: "the login session expired before you authorized" };
     }
     if (status === "consumed") {
-      return { ok: false, reason: "error", message: "this login was already used \u2014 start a fresh `bt login`" };
+      return { ok: false, reason: "error", message: "this login was already used \u2014 start a fresh `backthread login`" };
     }
     await sleep(interval);
   }
@@ -7348,8 +7352,416 @@ async function ensureAuth(opts = {}) {
   return readConfig(env);
 }
 
+// src/logout.ts
+async function runLogout(env = process.env) {
+  const where = configLocationHint3(env);
+  let cfg;
+  try {
+    cfg = await readConfig(env);
+  } catch (err) {
+    return { ok: false, cleared: false, message: `Couldn't read ${where} to sign out (${err.message ?? err}). Check its permissions and retry.` };
+  }
+  if (!cfg.device_token) {
+    return { ok: true, cleared: false, message: `Already signed out \u2014 no device token in ${where}.` };
+  }
+  const next = {};
+  if (cfg.account !== void 0) next.account = cfg.account;
+  if (cfg.repo !== void 0) next.repo = cfg.repo;
+  await writeConfig(next, env);
+  const kept = cfg.repo ? ` (kept your ${cfg.repo} link)` : "";
+  return {
+    ok: true,
+    cleared: true,
+    message: `Signed out. Removed this device's token from ${where}${kept}.
+Revoke it server-side under Account \u2192 Connected devices; \`backthread login\` re-authorizes.`
+  };
+}
+function configLocationHint3(env) {
+  return env.BACKTHREAD_CONFIG_DIR ? configPath(env) : "~/.backthread/config.json";
+}
+
+// src/update.ts
+import { realpathSync } from "node:fs";
+
+// src/upgradeNudge.ts
+import { join as join3 } from "node:path";
+import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, chmod as chmod2 } from "node:fs/promises";
+function upgradeNudgeStatePath(env = process.env) {
+  return join3(configDir(env), "upgrade-nudge.json");
+}
+var UPGRADE_NUDGE_THROTTLE_MS = 24 * 60 * 60 * 1e3;
+function parseState(raw) {
+  try {
+    const obj = JSON.parse(raw);
+    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+      const at = obj.lastUpgradeNudgeAt;
+      if (typeof at === "number" && Number.isFinite(at)) return { lastUpgradeNudgeAt: at };
+    }
+  } catch {
+  }
+  return {};
+}
+async function readState(env) {
+  try {
+    return parseState(await readFile2(upgradeNudgeStatePath(env), "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function writeState(state, env) {
+  try {
+    const dir = configDir(env);
+    await mkdir2(dir, { recursive: true, mode: DIR_MODE });
+    await chmod2(dir, DIR_MODE).catch(() => {
+    });
+    const path = upgradeNudgeStatePath(env);
+    await writeFile2(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
+    await chmod2(path, CONFIG_MODE).catch(() => {
+    });
+  } catch {
+  }
+}
+async function maybeUpgradeNudge(upgrade, deps = {}) {
+  try {
+    if (typeof upgrade !== "string" || upgrade.trim().length === 0) return null;
+    const env = deps.env ?? process.env;
+    const now = deps.now ? deps.now() : Date.now();
+    const state = await readState(env);
+    if (typeof state.lastUpgradeNudgeAt === "number" && now - state.lastUpgradeNudgeAt < UPGRADE_NUDGE_THROTTLE_MS) {
+      return null;
+    }
+    await writeState({ lastUpgradeNudgeAt: now }, env);
+    return upgrade.trim();
+  } catch {
+    return null;
+  }
+}
+async function resetUpgradeNudge(deps = {}) {
+  try {
+    const env = deps.env ?? process.env;
+    const now = deps.now ? deps.now() : Date.now();
+    await writeState({ lastUpgradeNudgeAt: now }, env);
+  } catch {
+  }
+}
+
+// src/npm.ts
+import { execFile } from "node:child_process";
+function runNpm(args) {
+  const isWin = process.platform === "win32";
+  const npm = isWin ? "npm.cmd" : "npm";
+  return new Promise((resolve) => {
+    try {
+      execFile(
+        npm,
+        args,
+        { timeout: 12e4, windowsHide: true, shell: isWin, maxBuffer: 8 * 1024 * 1024 },
+        (err, stdout, stderr) => {
+          resolve({
+            ok: !err,
+            stdout: (stdout ?? "").toString().trim(),
+            stderr: (stderr ?? "").toString().trim()
+          });
+        }
+      );
+    } catch (e) {
+      resolve({ ok: false, stdout: "", stderr: e.message ?? String(e) });
+    }
+  });
+}
+
+// src/update.ts
+var SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+var NPX_SEGMENT_RE = /(?:^|[\\/])_npx[\\/]/;
+function detectInstallContext(env, scriptPath) {
+  if (typeof env.CLAUDE_PLUGIN_ROOT === "string" && env.CLAUDE_PLUGIN_ROOT.trim().length > 0) return "plugin";
+  if (scriptPath && NPX_SEGMENT_RE.test(scriptPath)) return "npx";
+  return "global";
+}
+function resolveScriptPath() {
+  const raw = process.argv[1] ?? "";
+  if (!raw) return "";
+  if (NPX_SEGMENT_RE.test(raw)) return raw;
+  try {
+    return realpathSync(raw);
+  } catch {
+    return raw;
+  }
+}
+function firstLine(s) {
+  const line = s.split("\n").map((l) => l.trim()).find((l) => l.length > 0);
+  return line ?? "unknown npm error";
+}
+async function runUpdate(deps = {}) {
+  const env = deps.env ?? process.env;
+  const log = deps.log ?? ((m) => console.error(m));
+  const current = (deps.currentVersion ?? cliVersion)();
+  const runNpm2 = deps.runNpm ?? runNpm;
+  const resetNudge = deps.resetNudge ?? ((e) => resetUpgradeNudge({ env: e }));
+  const scriptPath = deps.scriptPath ?? resolveScriptPath();
+  const context = detectInstallContext(env, scriptPath);
+  if (context === "npx") {
+    return {
+      ok: true,
+      context,
+      updated: false,
+      message: "You're running Backthread via `npx`, which already fetches the latest published version\non every run \u2014 nothing to update. Want a pinned, always-available binary?\n  npm i -g backthread\nThen `backthread update` pulls new releases on demand."
+    };
+  }
+  if (context === "plugin") {
+    return {
+      ok: true,
+      context,
+      updated: false,
+      message: "This is the Claude Code plugin's bundled copy of Backthread \u2014 the plugin manages it,\nnot npm. Update it from Claude Code:\n  /plugin update backthread\nFor a standalone terminal CLI too: `npm i -g backthread`."
+    };
+  }
+  log("Checking npm for the latest backthread\u2026");
+  const view = await runNpm2(["view", "backthread", "version"]);
+  if (!view.ok || !SEMVER_RE.test(view.stdout)) {
+    const why = view.ok ? `unexpected npm output "${view.stdout}"` : firstLine(view.stderr);
+    return {
+      ok: false,
+      context,
+      updated: false,
+      message: `Couldn't check npm for the latest version (${why}). Are you online? Your current install (${current}) is untouched.`
+    };
+  }
+  const latest = view.stdout;
+  if (current === latest) {
+    await resetNudge(env);
+    return { ok: true, context, updated: false, message: `Backthread is already up to date (${current} is the latest).` };
+  }
+  log(`Updating backthread ${current} \u2192 ${latest} (npm i -g backthread@latest)\u2026`);
+  const install = await runNpm2(["install", "-g", "backthread@latest"]);
+  if (!install.ok) {
+    return {
+      ok: false,
+      context,
+      updated: false,
+      message: `npm couldn't install backthread@latest: ${firstLine(install.stderr)}
+Your current install (${current}) is untouched. If this is a permissions error, retry with your global-install method (e.g. a Node version manager, or sudo).`
+    };
+  }
+  await resetNudge(env);
+  return {
+    ok: true,
+    context,
+    updated: true,
+    message: `Updated Backthread ${current} \u2192 ${latest}. Restart any long-running sessions to pick it up.`
+  };
+}
+
+// src/doctor.ts
+import { homedir as homedir2 } from "node:os";
+import { join as join4 } from "node:path";
+import { readFile as readFile3, stat } from "node:fs/promises";
+var SEMVER_RE2 = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+var REPO_SLUG_RE = /^[^/\s]+\/[^/\s]+$/;
+async function loadConfig(env) {
+  try {
+    return { config: await readConfig(env), error: null };
+  } catch (e) {
+    return { config: null, error: e };
+  }
+}
+function authCheck(loaded, env) {
+  if (loaded.error) {
+    return {
+      key: "auth",
+      label: "Auth",
+      status: "fail",
+      critical: true,
+      detail: `couldn't read ${configHint(env)} (${loaded.error.message ?? loaded.error}) \u2014 check its permissions`
+    };
+  }
+  if (loaded.config?.device_token) {
+    return { key: "auth", label: "Auth", status: "ok", detail: "signed in (device token present)" };
+  }
+  return { key: "auth", label: "Auth", status: "fail", critical: true, detail: "not signed in \u2014 run `backthread login`" };
+}
+async function permsCheck(deps, env) {
+  if (process.platform === "win32") {
+    return { key: "perms", label: "Config perms", status: "info", detail: "n/a on Windows (POSIX modes not enforced)" };
+  }
+  const doStat = deps.statImpl ?? ((p) => stat(p));
+  const filePath = configPath(env);
+  const dirPath = configDir(env);
+  let fileMode = null;
+  let dirMode = null;
+  try {
+    fileMode = (await doStat(filePath)).mode & 511;
+  } catch {
+    return { key: "perms", label: "Config perms", status: "info", detail: "no config file yet (run `backthread login`)" };
+  }
+  try {
+    dirMode = (await doStat(dirPath)).mode & 511;
+  } catch {
+    dirMode = null;
+  }
+  const fileLoose = (fileMode & 63) !== 0;
+  const dirLoose = dirMode !== null && (dirMode & 63) !== 0;
+  if (fileLoose || dirLoose) {
+    return {
+      key: "perms",
+      label: "Config perms",
+      status: "warn",
+      detail: `too open (config ${octal(fileMode)}${dirMode !== null ? `, dir ${octal(dirMode)}` : ""}) \u2014 run \`chmod 600 ${configHint(env)}\` (dir 700)`
+    };
+  }
+  return { key: "perms", label: "Config perms", status: "ok", detail: `config 0600${dirMode !== null ? ", dir 0700" : ""}` };
+}
+function repoCheck(loaded) {
+  if (loaded.error) {
+    return { key: "repo", label: "Repo", status: "warn", detail: "could not read the connected repo" };
+  }
+  const repo = loaded.config?.repo;
+  if (repo && REPO_SLUG_RE.test(repo)) {
+    return { key: "repo", label: "Repo", status: "ok", detail: repo };
+  }
+  if (repo) {
+    return { key: "repo", label: "Repo", status: "warn", detail: `connected slug "${repo}" is not owner/name \u2014 reconnect in the web app` };
+  }
+  return { key: "repo", label: "Repo", status: "warn", detail: "no repo connected \u2014 run `backthread install` (or connect it in the web app)" };
+}
+var AGENT_HOOK_FILES = [
+  { agent: "claude-code", files: (h) => [join4(h, ".claude", "settings.json")] },
+  { agent: "gemini", files: (h) => [join4(h, ".gemini", "settings.json")] },
+  { agent: "codex", files: (h) => [join4(h, ".codex", "hooks.json"), join4(h, ".codex", "config.toml")] },
+  { agent: "cursor", files: (h) => [join4(h, ".cursor", "hooks.json"), join4(h, ".cursor", "mcp.json")] }
+];
+async function hookCheck(deps, env) {
+  const home = deps.home ?? homedir2();
+  const cwd = deps.cwd ?? process.cwd();
+  const doRead = deps.readFileImpl ?? ((p) => readFile3(p, "utf8"));
+  const mentions = async (path) => {
+    try {
+      return (await doRead(path)).includes("backthread");
+    } catch {
+      return false;
+    }
+  };
+  const asPlugin = typeof env.CLAUDE_PLUGIN_ROOT === "string" && env.CLAUDE_PLUGIN_ROOT.trim().length > 0;
+  const wired = [];
+  if (asPlugin) wired.push("claude-code (plugin)");
+  for (const { agent, files } of AGENT_HOOK_FILES) {
+    for (const f of files(home)) {
+      if (await mentions(f)) {
+        wired.push(agent);
+        break;
+      }
+    }
+  }
+  const projectScoped = await mentions(join4(cwd, ".claude", "settings.json")) || await mentions(join4(cwd, ".claude", "settings.local.json"));
+  const userScopedCC = asPlugin || await mentions(join4(home, ".claude", "settings.json"));
+  const uniqueWired = Array.from(new Set(wired));
+  if (projectScoped && !userScopedCC) {
+    return {
+      key: "hook",
+      label: "Capture hook",
+      status: "warn",
+      detail: "PROJECT-scoped only \u2014 blind in git worktrees + other repos (ARP-680). Re-run `backthread install` for the user-scope hook."
+    };
+  }
+  if (uniqueWired.length > 0) {
+    return { key: "hook", label: "Capture hook", status: "ok", detail: `wired for ${uniqueWired.join(", ")}` };
+  }
+  return {
+    key: "hook",
+    label: "Capture hook",
+    status: "warn",
+    detail: "not detected \u2014 run `backthread install` here (or `backthread install --agent <codex|cursor|gemini>`)"
+  };
+}
+async function connectivityCheck(deps, env) {
+  const doFetch = deps.fetchImpl ?? fetch;
+  const timeout = deps.connectTimeoutMs ?? 5e3;
+  const targets = [
+    { name: "worker", url: workerBaseUrl(env) },
+    { name: "functions", url: functionsBaseUrl(env) }
+  ];
+  const results = await Promise.all(
+    targets.map(async ({ name, url: url2 }) => {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      try {
+        const res = await doFetch(url2, { method: "GET", signal: controller.signal });
+        await res.body?.cancel?.().catch(() => {
+        });
+        return { name, reachable: true };
+      } catch {
+        return { name, reachable: false };
+      } finally {
+        clearTimeout(timer);
+      }
+    })
+  );
+  const down = results.filter((r) => !r.reachable).map((r) => r.name);
+  if (down.length === 0) {
+    return { key: "connectivity", label: "Connectivity", status: "ok", detail: "worker + functions reachable" };
+  }
+  return {
+    key: "connectivity",
+    label: "Connectivity",
+    status: "warn",
+    detail: `couldn't reach ${down.join(" + ")} (offline, or blocked by a proxy/firewall?)`
+  };
+}
+async function versionCheck(deps) {
+  const current = cliVersion();
+  const redact = redactVersion();
+  const base = `backthread ${current} \xB7 redact ${redact}`;
+  const runNpm2 = deps.runNpm ?? runNpm;
+  const view = await runNpm2(["view", "backthread", "version"]);
+  if (!view.ok || !SEMVER_RE2.test(view.stdout)) {
+    return { key: "version", label: "Version", status: "info", detail: `${base} (couldn't check npm for the latest \u2014 offline?)` };
+  }
+  const latest = view.stdout;
+  if (current === latest) {
+    return { key: "version", label: "Version", status: "ok", detail: `${base} (latest)` };
+  }
+  return { key: "version", label: "Version", status: "info", detail: `${base} \u2014 update available (${latest}): \`backthread update\`` };
+}
+async function collectChecks(deps = {}) {
+  const env = deps.env ?? process.env;
+  const loaded = await loadConfig(env);
+  const [perms, hook, connectivity, version2] = await Promise.all([
+    permsCheck(deps, env),
+    hookCheck(deps, env),
+    connectivityCheck(deps, env),
+    versionCheck(deps)
+  ]);
+  return [authCheck(loaded, env), perms, repoCheck(loaded), hook, connectivity, version2];
+}
+var GLYPH = { ok: "\u2713", fail: "\u2717", warn: "\u26A0", info: "\u2139" };
+function formatReport(checks) {
+  const width = Math.max(...checks.map((c) => c.label.length));
+  const lines = checks.map((c) => `${GLYPH[c.status]} ${c.label.padEnd(width)}  ${c.detail}`);
+  const fails = checks.filter((c) => c.status === "fail").length;
+  const warns = checks.filter((c) => c.status === "warn").length;
+  let summary;
+  if (fails > 0) summary = `
+${fails} issue${fails === 1 ? "" : "s"} to fix \u2014 see the \u2717 above, then re-run \`backthread doctor\`.`;
+  else if (warns > 0) summary = `
+Mostly good \u2014 the \u26A0 above are worth a look but capture can still run.`;
+  else summary = `
+All good \u2014 Backthread is set up. \u{1F9F5}`;
+  return ["backthread doctor\n", ...lines, summary].join("\n");
+}
+async function runDoctor(deps = {}) {
+  const checks = await collectChecks(deps);
+  const exitCode = checks.some((c) => c.status === "fail" && c.critical) ? 1 : 0;
+  return { text: formatReport(checks), exitCode, checks };
+}
+function octal(mode) {
+  return "0" + mode.toString(8).padStart(3, "0");
+}
+function configHint(env) {
+  return env.BACKTHREAD_CONFIG_DIR ? configPath(env) : "~/.backthread/config.json";
+}
+
 // src/capture.ts
-import { readFile as readFile9 } from "node:fs/promises";
+import { readFile as readFile10 } from "node:fs/promises";
 
 // ../packages/redact/src/index.ts
 var CODE_REDACTION = "[code redacted]";
@@ -7709,8 +8121,8 @@ async function inferDecisions(transcript, config2, opts = {}) {
 }
 
 // src/connectNudge.ts
-import { join as join3 } from "node:path";
-import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, chmod as chmod2 } from "node:fs/promises";
+import { join as join5 } from "node:path";
+import { readFile as readFile4, writeFile as writeFile3, mkdir as mkdir3, chmod as chmod3 } from "node:fs/promises";
 function parseRepoStatus(value) {
   return value === "connected" || value === "not_connected" || value === "disconnected" ? value : null;
 }
@@ -7723,10 +8135,10 @@ function parseNextStep(value) {
   return "absent";
 }
 function nudgeStatePath(env = process.env) {
-  return join3(configDir(env), "connect-nudge.json");
+  return join5(configDir(env), "connect-nudge.json");
 }
 var MAX_REMEMBERED = 50;
-function parseState(raw) {
+function parseState2(raw) {
   try {
     const obj = JSON.parse(raw);
     if (obj && typeof obj === "object" && Array.isArray(obj.nudged)) {
@@ -7737,22 +8149,22 @@ function parseState(raw) {
   }
   return { nudged: [] };
 }
-async function readState(env) {
+async function readState2(env) {
   try {
-    return parseState(await readFile2(nudgeStatePath(env), "utf8"));
+    return parseState2(await readFile4(nudgeStatePath(env), "utf8"));
   } catch {
     return { nudged: [] };
   }
 }
-async function writeState(state, env) {
+async function writeState2(state, env) {
   try {
     const dir = configDir(env);
-    await mkdir2(dir, { recursive: true, mode: DIR_MODE });
-    await chmod2(dir, DIR_MODE).catch(() => {
+    await mkdir3(dir, { recursive: true, mode: DIR_MODE });
+    await chmod3(dir, DIR_MODE).catch(() => {
     });
     const path = nudgeStatePath(env);
-    await writeFile2(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
-    await chmod2(path, CONFIG_MODE).catch(() => {
+    await writeFile3(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
+    await chmod3(path, CONFIG_MODE).catch(() => {
     });
   } catch {
   }
@@ -7790,12 +8202,12 @@ async function maybeNudge(status, repo, sessionId, deps = {}) {
     }
     if (line === null) return false;
     const log = deps.log ?? ((m) => console.error(m));
-    const state = await readState(env);
+    const state = await readState2(env);
     if (state.nudged.includes(sessionId)) return false;
     log(line);
     const nudged = [...state.nudged, sessionId];
     if (nudged.length > MAX_REMEMBERED) nudged.splice(0, nudged.length - MAX_REMEMBERED);
-    await writeState({ nudged }, env);
+    await writeState2({ nudged }, env);
     return true;
   } catch {
     return false;
@@ -7803,84 +8215,28 @@ async function maybeNudge(status, repo, sessionId, deps = {}) {
 }
 
 // src/firstRun.ts
-import { join as join10 } from "node:path";
-import { readFile as readFile8, writeFile as writeFile7, mkdir as mkdir7, chmod as chmod6 } from "node:fs/promises";
+import { join as join11 } from "node:path";
+import { readFile as readFile9, writeFile as writeFile7, mkdir as mkdir7, chmod as chmod6 } from "node:fs/promises";
 
 // src/install.ts
-import { readFile as readFile7, writeFile as writeFile6, mkdir as mkdir6 } from "node:fs/promises";
-import { homedir as homedir5 } from "node:os";
-import { join as join9 } from "node:path";
-
-// src/captureCommand.ts
-import { stat } from "node:fs/promises";
-import { homedir as homedir2 } from "node:os";
-import { join as join5 } from "node:path";
-
-// src/upgradeNudge.ts
-import { join as join4 } from "node:path";
-import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3, chmod as chmod3 } from "node:fs/promises";
-function upgradeNudgeStatePath(env = process.env) {
-  return join4(configDir(env), "upgrade-nudge.json");
-}
-var UPGRADE_NUDGE_THROTTLE_MS = 24 * 60 * 60 * 1e3;
-function parseState2(raw) {
-  try {
-    const obj = JSON.parse(raw);
-    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
-      const at = obj.lastUpgradeNudgeAt;
-      if (typeof at === "number" && Number.isFinite(at)) return { lastUpgradeNudgeAt: at };
-    }
-  } catch {
-  }
-  return {};
-}
-async function readState2(env) {
-  try {
-    return parseState2(await readFile3(upgradeNudgeStatePath(env), "utf8"));
-  } catch {
-    return {};
-  }
-}
-async function writeState2(state, env) {
-  try {
-    const dir = configDir(env);
-    await mkdir3(dir, { recursive: true, mode: DIR_MODE });
-    await chmod3(dir, DIR_MODE).catch(() => {
-    });
-    const path = upgradeNudgeStatePath(env);
-    await writeFile3(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
-    await chmod3(path, CONFIG_MODE).catch(() => {
-    });
-  } catch {
-  }
-}
-async function maybeUpgradeNudge(upgrade, deps = {}) {
-  try {
-    if (typeof upgrade !== "string" || upgrade.trim().length === 0) return null;
-    const env = deps.env ?? process.env;
-    const now = deps.now ? deps.now() : Date.now();
-    const state = await readState2(env);
-    if (typeof state.lastUpgradeNudgeAt === "number" && now - state.lastUpgradeNudgeAt < UPGRADE_NUDGE_THROTTLE_MS) {
-      return null;
-    }
-    await writeState2({ lastUpgradeNudgeAt: now }, env);
-    return upgrade.trim();
-  } catch {
-    return null;
-  }
-}
+import { readFile as readFile8, writeFile as writeFile6, mkdir as mkdir6 } from "node:fs/promises";
+import { homedir as homedir6 } from "node:os";
+import { join as join10 } from "node:path";
 
 // src/captureCommand.ts
+import { stat as stat2 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { join as join6 } from "node:path";
 function slugifyCwd(cwd) {
   return cwd.replace(/[^A-Za-z0-9]/g, "-");
 }
 function deriveTranscriptPath(sessionId, cwd, home) {
   if (!sessionId || sessionId.trim().length === 0) return null;
-  return join5(home, ".claude", "projects", slugifyCwd(cwd), `${sessionId}.jsonl`);
+  return join6(home, ".claude", "projects", slugifyCwd(cwd), `${sessionId}.jsonl`);
 }
 async function defaultStat(path) {
   try {
-    const s = await stat(path);
+    const s = await stat2(path);
     return s.isFile();
   } catch {
     return false;
@@ -7889,7 +8245,7 @@ async function defaultStat(path) {
 async function resolveTranscriptPath(input, deps = {}) {
   const explicit = input.transcriptPath;
   if (explicit && explicit.trim().length > 0) return explicit;
-  const home = (deps.homedirImpl ?? homedir2)();
+  const home = (deps.homedirImpl ?? homedir3)();
   const cwd = input.cwd ?? process.cwd();
   const derived = deriveTranscriptPath(input.sessionId, cwd, home);
   if (!derived) return null;
@@ -7980,17 +8336,17 @@ function parseManualArgs(argv) {
 }
 
 // src/sweep.ts
-import { readFile as readFile5, stat as stat2, readdir } from "node:fs/promises";
+import { readFile as readFile6, stat as stat3, readdir } from "node:fs/promises";
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { homedir as homedir3 } from "node:os";
-import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join7 } from "node:path";
+import { homedir as homedir4 } from "node:os";
+import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join8 } from "node:path";
 
 // src/sweepLedger.ts
-import { join as join6 } from "node:path";
-import { readFile as readFile4, writeFile as writeFile4, mkdir as mkdir4, chmod as chmod4 } from "node:fs/promises";
+import { join as join7 } from "node:path";
+import { readFile as readFile5, writeFile as writeFile4, mkdir as mkdir4, chmod as chmod4 } from "node:fs/promises";
 var MAX_PROCESSED = 2e4;
 function sweepStatePath(env = process.env) {
-  return join6(configDir(env), "sweep-state.json");
+  return join7(configDir(env), "sweep-state.json");
 }
 function parseSweepState(raw) {
   try {
@@ -8015,7 +8371,7 @@ function serializeSweepState(state) {
 }
 async function readSweepState(env = process.env) {
   try {
-    return parseSweepState(await readFile4(sweepStatePath(env), "utf8"));
+    return parseSweepState(await readFile5(sweepStatePath(env), "utf8"));
   } catch {
     return { processed: [], lastSweptAt: {} };
   }
@@ -8118,7 +8474,7 @@ async function defaultReadDir(dir) {
 }
 async function defaultPathExists(path) {
   try {
-    await stat2(path);
+    await stat3(path);
     return true;
   } catch {
     return false;
@@ -8132,7 +8488,7 @@ function defaultMainRoot(cwd) {
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
     if (!out) return null;
-    const abs = isAbsolute2(out) ? out : join7(cwd, out);
+    const abs = isAbsolute2(out) ? out : join8(cwd, out);
     return dirname2(abs.replace(/\/+$/, ""));
   } catch {
     return null;
@@ -8150,7 +8506,7 @@ async function runSweep(input = {}, deps = {}) {
       return [];
     }
   };
-  const baseReadFile = deps.readFileImpl ?? ((p) => readFile5(p, "utf8"));
+  const baseReadFile = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
   const doReadFile = async (p) => {
     try {
       return await baseReadFile(p);
@@ -8179,7 +8535,7 @@ async function runSweep(input = {}, deps = {}) {
   const doReadState = deps.readSweepStateImpl ?? readSweepState;
   const doWriteState = deps.writeSweepStateImpl ?? writeSweepState;
   try {
-    const home = (deps.homedirImpl ?? homedir3)();
+    const home = (deps.homedirImpl ?? homedir4)();
     const now = (deps.nowImpl ?? (() => (/* @__PURE__ */ new Date()).toISOString()))();
     const cwd = input.cwd ?? process.cwd();
     const target = resolveRepo(cwd, readRemote);
@@ -8207,7 +8563,7 @@ async function runSweep(input = {}, deps = {}) {
     }
     const mainRoot = doMainRoot(cwd) ?? cwd;
     const mainSlug = slugifyCwd(mainRoot);
-    const projectsRoot = join7(home, ".claude", "projects");
+    const projectsRoot = join8(home, ".claude", "projects");
     const entries = await doReadDir(projectsRoot);
     const candidates = entries.filter((n) => n === mainSlug || n.startsWith(mainSlug + "-")).sort();
     const skip = new Set(state.processed);
@@ -8220,12 +8576,12 @@ async function runSweep(input = {}, deps = {}) {
     let captured = 0;
     let decisions = 0;
     for (const dirName of candidates) {
-      const dir = join7(projectsRoot, dirName);
+      const dir = join8(projectsRoot, dirName);
       const files = (await doReadDir(dir)).filter((n) => n.endsWith(".jsonl")).sort();
       if (files.length === 0) continue;
       let embeddedCwd = null;
       for (const file2 of files) {
-        embeddedCwd = extractCwdFromRaw(await doReadFile(join7(dir, file2)));
+        embeddedCwd = extractCwdFromRaw(await doReadFile(join8(dir, file2)));
         if (embeddedCwd) break;
       }
       const cwdExists = embeddedCwd ? await doPathExists(embeddedCwd) : false;
@@ -8264,7 +8620,7 @@ async function runSweep(input = {}, deps = {}) {
         try {
           outcome = await run(
             {
-              transcript_path: join7(dir, file2),
+              transcript_path: join8(dir, file2),
               cwd: cls.cwd ?? mainRoot,
               session_id: sid,
               hook_event_name: "SessionEnd"
@@ -8325,12 +8681,12 @@ async function runBackfill(input = {}, deps = {}) {
 }
 
 // src/installAgent.ts
-import { execFile } from "node:child_process";
+import { execFile as execFile2 } from "node:child_process";
 import { promisify } from "node:util";
-import { homedir as homedir4 } from "node:os";
-import { join as join8, dirname as dirname3 } from "node:path";
-import { readFile as readFile6, writeFile as writeFile5, mkdir as mkdir5, chmod as chmod5 } from "node:fs/promises";
-var execFileP = promisify(execFile);
+import { homedir as homedir5 } from "node:os";
+import { join as join9, dirname as dirname3 } from "node:path";
+import { readFile as readFile7, writeFile as writeFile5, mkdir as mkdir5, chmod as chmod5 } from "node:fs/promises";
+var execFileP = promisify(execFile2);
 var MCP_COMMAND = "npx";
 var MCP_ARGS = ["-y", "backthread", "mcp"];
 function hookCommand(agent) {
@@ -8425,8 +8781,8 @@ async function writeJson(deps, path, obj) {
   await doWrite(path, JSON.stringify(obj, null, 2) + "\n");
 }
 async function installGemini(home, deps) {
-  const doRead = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
-  const path = join8(home, ".gemini", "settings.json");
+  const doRead = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
+  const path = join9(home, ".gemini", "settings.json");
   const current = await loadJsonObject(doRead, path);
   const a = withMcpServer(current);
   const b = withNestedHook(a.next, "SessionEnd", hookCommand("gemini-cli"), { name: "backthread-capture" }, [
@@ -8436,9 +8792,9 @@ async function installGemini(home, deps) {
   return [{ path, wrote: a.changed || b.changed }];
 }
 async function installCodex(home, deps) {
-  const doRead = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
+  const doRead = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
   const writes = [];
-  const tomlPath = join8(home, ".codex", "config.toml");
+  const tomlPath = join9(home, ".codex", "config.toml");
   let toml = "";
   try {
     toml = await doRead(tomlPath);
@@ -8459,7 +8815,7 @@ args = [${MCP_ARGS.map((a) => `"${a}"`).join(", ")}]
     await doWrite(tomlPath, toml + sep + block);
     writes.push({ path: tomlPath, wrote: true });
   }
-  const hooksPath = join8(home, ".codex", "hooks.json");
+  const hooksPath = join9(home, ".codex", "hooks.json");
   const current = await loadJsonObject(doRead, hooksPath);
   const h = withNestedHook(current, "Stop", hookCommand("codex"), { timeout: 60 }, [legacyHookCommand("codex")]);
   if (h.changed) await writeJson(deps, hooksPath, h.next);
@@ -8467,12 +8823,12 @@ args = [${MCP_ARGS.map((a) => `"${a}"`).join(", ")}]
   return writes;
 }
 async function installCursor(home, deps) {
-  const doRead = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
+  const doRead = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
   const nodeBinDir = deps.nodeBinDir ?? dirname3(process.execPath);
   const writes = [];
-  const scriptDir = join8(home, ".cursor", "hooks");
-  const captureScriptPath = join8(scriptDir, "backthread-capture.sh");
-  const mcpScriptPath = join8(scriptDir, "backthread-mcp.sh");
+  const scriptDir = join9(home, ".cursor", "hooks");
+  const captureScriptPath = join9(scriptDir, "backthread-capture.sh");
+  const mcpScriptPath = join9(scriptDir, "backthread-mcp.sh");
   writes.push(
     await writeCursorScript(
       deps,
@@ -8482,12 +8838,12 @@ async function installCursor(home, deps) {
     )
   );
   writes.push(await writeCursorScript(deps, mcpScriptPath, cursorWrapperScript(nodeBinDir, "mcp")));
-  const mcpPath = join8(home, ".cursor", "mcp.json");
+  const mcpPath = join9(home, ".cursor", "mcp.json");
   const mcpCurrent = await loadJsonObject(doRead, mcpPath);
   const m = withCursorMcpServer(mcpCurrent, mcpScriptPath);
   if (m.changed) await writeJson(deps, mcpPath, m.next);
   writes.push({ path: mcpPath, wrote: m.changed });
-  const hooksPath = join8(home, ".cursor", "hooks.json");
+  const hooksPath = join9(home, ".cursor", "hooks.json");
   const hooksCurrent = await loadJsonObject(doRead, hooksPath);
   const c = withCursorStopHook(hooksCurrent, captureScriptPath);
   if (c.changed) await writeJson(deps, hooksPath, c.next);
@@ -8521,7 +8877,7 @@ function cursorWrapperScript(nodeBinDir, backthreadArgs, latest = false) {
   ].join("\n") + "\n";
 }
 async function writeCursorScript(deps, path, content) {
-  const doRead = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
+  const doRead = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
   const doChmod = deps.chmodImpl ?? ((p, mode) => chmod5(p, mode));
   let existing = null;
   try {
@@ -8595,7 +8951,7 @@ async function versionGate(agent, deps) {
   return null;
 }
 async function runInstallAgent(agent, deps = {}) {
-  const home = deps.home ?? homedir4();
+  const home = deps.home ?? homedir5();
   const versionWarning = await versionGate(agent, deps);
   let writes;
   switch (agent) {
@@ -8637,12 +8993,12 @@ var LEGACY_HOOK_COMMANDS = [
 ];
 var OUR_HOOK_COMMANDS = /* @__PURE__ */ new Set([HOOK_COMMAND, ...LEGACY_HOOK_COMMANDS]);
 async function registerHook(deps = {}) {
-  const doReadFile = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
+  const doReadFile = deps.readFileImpl ?? ((p) => readFile8(p, "utf8"));
   const doWriteFile = deps.writeFileImpl ?? ((p, d) => writeFile6(p, d));
   const doMkdir = deps.mkdirImpl ?? (async (d) => void await mkdir6(d, { recursive: true }));
-  const home = deps.home ?? homedir5();
-  const settingsDir = join9(home, ".claude");
-  const settingsPath = join9(settingsDir, "settings.json");
+  const home = deps.home ?? homedir6();
+  const settingsDir = join10(home, ".claude");
+  const settingsPath = join10(settingsDir, "settings.json");
   let settings = {};
   let raw = null;
   try {
@@ -8754,9 +9110,9 @@ function stripSessionEndHook(settings) {
   return next;
 }
 async function unregisterProjectHook(cwd, deps = {}) {
-  const doReadFile = deps.readFileImpl ?? ((p) => readFile7(p, "utf8"));
+  const doReadFile = deps.readFileImpl ?? ((p) => readFile8(p, "utf8"));
   const doWriteFile = deps.writeFileImpl ?? ((p, d) => writeFile6(p, d));
-  const settingsPath = join9(cwd, ".claude", "settings.json");
+  const settingsPath = join10(cwd, ".claude", "settings.json");
   let raw;
   try {
     raw = await doReadFile(settingsPath);
@@ -9021,7 +9377,7 @@ function normalizeState(raw) {
 
 // src/firstRun.ts
 function firstRunStatePath(env = process.env) {
-  return join10(configDir(env), "first-run.json");
+  return join11(configDir(env), "first-run.json");
 }
 function parseFirstRunState(raw) {
   try {
@@ -9040,7 +9396,7 @@ function parseFirstRunState(raw) {
 }
 async function readFirstRunState(env = process.env) {
   try {
-    return parseFirstRunState(await readFile8(firstRunStatePath(env), "utf8"));
+    return parseFirstRunState(await readFile9(firstRunStatePath(env), "utf8"));
   } catch {
     return {};
   }
@@ -9215,7 +9571,7 @@ function readStream(stream) {
 async function runCapture(input, deps = {}) {
   const env = deps.env ?? process.env;
   const log = deps.log ?? ((m) => console.error(m));
-  const doReadFile = deps.readFileImpl ?? ((p) => readFile9(p, "utf8"));
+  const doReadFile = deps.readFileImpl ?? ((p) => readFile10(p, "utf8"));
   const doReadConfig = deps.readConfigImpl ?? readConfig;
   const fireEnsureAuth = deps.ensureAuthImpl ?? ((e) => {
     void ensureAuth({ env: e }).catch(() => {
@@ -9395,8 +9751,8 @@ async function persistDerived(decisions, repo, config2, decidedAt, ctx) {
 
 // src/fromHook.ts
 import { spawn as spawn2 } from "node:child_process";
-import { join as join11 } from "node:path";
-import { readFile as readFile10, writeFile as writeFile8, mkdir as mkdir8, chmod as chmod7 } from "node:fs/promises";
+import { join as join12 } from "node:path";
+import { readFile as readFile11, writeFile as writeFile8, mkdir as mkdir8, chmod as chmod7 } from "node:fs/promises";
 var KNOWN_AGENTS = /* @__PURE__ */ new Set([
   "claude-code",
   "codex",
@@ -9437,7 +9793,7 @@ function normalizeHookInput(payload, _agent) {
   return out;
 }
 function captureStatePath(env = process.env) {
-  return join11(configDir(env), "capture-sessions.json");
+  return join12(configDir(env), "capture-sessions.json");
 }
 var MAX_REMEMBERED2 = 200;
 function parseState3(raw) {
@@ -9460,7 +9816,7 @@ function parseState3(raw) {
 }
 async function readState3(env) {
   try {
-    return parseState3(await readFile10(captureStatePath(env), "utf8"));
+    return parseState3(await readFile11(captureStatePath(env), "utf8"));
   } catch {
     return { captured: [], watermarks: {} };
   }
@@ -9633,6 +9989,45 @@ function codexStdout(agent, status, outcome) {
   return ack;
 }
 
+// src/suggest.ts
+var MAX_DISTANCE = 2;
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  let curr = new Array(n + 1);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+function preferable(candidate, incumbent) {
+  if (candidate.length !== incumbent.length) return candidate.length < incumbent.length;
+  return candidate < incumbent;
+}
+function nearestCommand(input, commands) {
+  const needle = input.toLowerCase();
+  if (needle.length === 0) return null;
+  let best = null;
+  let bestDist = Infinity;
+  for (const cmd of commands) {
+    const d = editDistance(needle, cmd.toLowerCase());
+    if (d > MAX_DISTANCE || d >= needle.length) continue;
+    if (d < bestDist || d === bestDist && best !== null && preferable(cmd, best)) {
+      best = cmd;
+      bestDist = d;
+    }
+  }
+  return best;
+}
+
 // ../node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
@@ -33697,8 +34092,49 @@ var StdioServerTransport = class {
 };
 
 // src/query.ts
+import { execFileSync as execFileSync3 } from "node:child_process";
 var DEFAULT_QUESTION = "How does this project work?";
-var GROUNDED_ASK_TIMEOUT_MS = 3e4;
+var GROUNDED_ASK_TIMEOUT_MS = 45e3;
+var GROUNDED_ASK_ATTEMPTS = 2;
+var defaultGitRunner2 = (args, cwd) => {
+  try {
+    execFileSync3("git", args, { cwd, stdio: ["ignore", "ignore", "ignore"], timeout: 3e3 });
+    return 0;
+  } catch (e) {
+    const status = e.status;
+    return typeof status === "number" ? status : 128;
+  }
+};
+var SHA_RE = /^[0-9a-f]{7,40}$/i;
+function countCitationsAfterCheckout(citations, cwd, runGit = defaultGitRunner2) {
+  const stale = /* @__PURE__ */ new Map();
+  for (const c of citations) {
+    if (c.anchorSha && SHA_RE.test(c.anchorSha)) stale.set(c.anchorSha, false);
+  }
+  if (stale.size === 0) return 0;
+  for (const sha of stale.keys()) {
+    const exists = runGit(["rev-parse", "--quiet", "--verify", `${sha}^{commit}`], cwd);
+    if (exists === 1) {
+      stale.set(sha, true);
+      continue;
+    }
+    if (exists !== 0) return 0;
+    const contained = runGit(["merge-base", "--is-ancestor", sha, "HEAD"], cwd);
+    if (contained === 1) {
+      stale.set(sha, true);
+      continue;
+    }
+    if (contained !== 0) return 0;
+  }
+  let n = 0;
+  for (const c of citations) {
+    if (c.anchorSha && stale.get(c.anchorSha)) n += 1;
+  }
+  return n;
+}
+function stalenessNote(n) {
+  return `Note: ${n} of the decisions cited above landed after your checkout \u2014 this answer reflects the tracked branch.`;
+}
 function parseSlug2(slug) {
   const parts = slug.trim().replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
   if (parts.length !== 2) return null;
@@ -33745,33 +34181,46 @@ async function queryDecisions(input, deps = {}) {
     }
     const deepLink = buildRepoDeepLink(repo.owner, repo.name, env);
     const question = typeof input.question === "string" && input.question.trim().length > 0 ? input.question.trim() : DEFAULT_QUESTION;
-    const ac = new AbortController();
-    const timer = setTimeout(() => ac.abort(), GROUNDED_ASK_TIMEOUT_MS);
     let res;
-    try {
-      res = await doFetch(buildGroundedAskUrl(env), {
-        method: "POST",
-        headers: {
-          // Bearer device token — never logged.
-          Authorization: `Bearer ${config2.device_token}`,
-          "Content-Type": "application/json",
-          ...versionHeaders()
-          // x-backthread-version — server-side compat guard
-        },
-        // The server accepts `repo` as an "owner/name" slug (it re-resolves + gates).
-        body: JSON.stringify({ question, repo: `${repo.owner}/${repo.name}` }),
-        signal: ac.signal
-      });
-    } catch (e) {
-      const aborted2 = e.name === "AbortError";
+    let failDetail = "";
+    for (let attempt = 1; attempt <= GROUNDED_ASK_ATTEMPTS; attempt++) {
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), GROUNDED_ASK_TIMEOUT_MS);
+      try {
+        res = await doFetch(buildGroundedAskUrl(env), {
+          method: "POST",
+          headers: {
+            // Bearer device token — never logged.
+            Authorization: `Bearer ${config2.device_token}`,
+            "Content-Type": "application/json",
+            ...versionHeaders()
+            // x-backthread-version — server-side compat guard
+          },
+          // The server accepts `repo` as an "owner/name" slug (it re-resolves + gates).
+          body: JSON.stringify({ question, repo: `${repo.owner}/${repo.name}` }),
+          signal: ac.signal
+        });
+        if (res.status >= 500 && attempt < GROUNDED_ASK_ATTEMPTS) {
+          failDetail = `grounded-ask rejected (${res.status})`;
+          res = void 0;
+          continue;
+        }
+        break;
+      } catch (e) {
+        const aborted2 = e.name === "AbortError";
+        failDetail = aborted2 ? `grounded-ask timed out after ${GROUNDED_ASK_TIMEOUT_MS / 1e3}s` : `grounded-ask request failed: ${e.message}`;
+        res = void 0;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    if (!res) {
       return {
         status: "read-failed",
-        detail: aborted2 ? `grounded-ask timed out after ${GROUNDED_ASK_TIMEOUT_MS / 1e3}s \u2014 try again.` : `grounded-ask request failed: ${e.message}`,
+        detail: `${failDetail} (after ${GROUNDED_ASK_ATTEMPTS} attempts) \u2014 try again.`,
         repo,
         deepLink
       };
-    } finally {
-      clearTimeout(timer);
     }
     let payload;
     try {
@@ -33799,13 +34248,22 @@ async function queryDecisions(input, deps = {}) {
       };
     }
     const upgrade = typeof rec.upgrade === "string" && rec.upgrade.length > 0 ? rec.upgrade : void 0;
+    const citations = normalizeCitations(rec.citations);
+    let renderedAnswer = answer;
+    try {
+      const n = countCitationsAfterCheckout(citations, input.cwd ?? process.cwd(), deps.runGitImpl);
+      if (n > 0) renderedAnswer = `${answer}
+
+${stalenessNote(n)}`;
+    } catch {
+    }
     return {
       status: "ok",
       detail: `grounded answer (${typeof rec.coverage === "string" ? rec.coverage : "partial"} coverage)`,
       repo,
-      answer,
+      answer: renderedAnswer,
       coverage: typeof rec.coverage === "string" ? rec.coverage : void 0,
-      citations: normalizeCitations(rec.citations),
+      citations,
       inferredSpans: Array.isArray(rec.inferredSpans) ? rec.inferredSpans.map(String) : [],
       // Prefer the server's deepLink; fall back to the locally-built one.
       deepLink: typeof rec.deepLink === "string" && rec.deepLink.length > 0 ? rec.deepLink : deepLink,
@@ -33825,7 +34283,8 @@ function normalizeCitations(raw) {
       title: String(r.title ?? ""),
       url: String(r.url ?? ""),
       moduleIds: Array.isArray(r.moduleIds) ? r.moduleIds.map(String) : [],
-      decidedAt: typeof r.decidedAt === "string" ? r.decidedAt : null
+      decidedAt: typeof r.decidedAt === "string" ? r.decidedAt : null,
+      anchorSha: typeof r.anchorSha === "string" ? r.anchorSha : null
     };
   });
 }
@@ -33921,15 +34380,15 @@ async function startMcpServer(deps = {}) {
 }
 
 // src/routingStats.ts
-import { join as join12 } from "node:path";
-import { readFile as readFile11, writeFile as writeFile9, mkdir as mkdir9, chmod as chmod8 } from "node:fs/promises";
+import { join as join13 } from "node:path";
+import { readFile as readFile12, writeFile as writeFile9, mkdir as mkdir9, chmod as chmod8 } from "node:fs/promises";
 var STATS_FILE = "routing-stats.json";
 function statsPath(env) {
-  return join12(configDir(env), STATS_FILE);
+  return join13(configDir(env), STATS_FILE);
 }
 async function readRoutingStats(deps = {}) {
   const env = deps.env ?? process.env;
-  const read = deps.readFileImpl ?? readFile11;
+  const read = deps.readFileImpl ?? readFile12;
   try {
     const raw = await read(statsPath(env), "utf8");
     const obj = JSON.parse(raw);
@@ -34002,40 +34461,60 @@ async function runSessionStart(deps = {}) {
 }
 
 // src/bin/backthread.ts
-var USAGE = `backthread \u2014 capture the "why" of your AI-coded changes
+var USAGE = `backthread \u2014 keep the thread on what your AI agent actually shipped
 
 Usage:
-  backthread                    Set up Backthread (the unified front door \u2014 same as
-                          \`backthread start\`): trust copy + one-tap auth + your next
-                          step. Idempotent. [--claim <code>]
-  backthread start              First-run setup (backs the /backthread:start slash command):
-                          trust copy + one-tap auth + your next step. Idempotent.
+  backthread [command] [flags]
+
+Setup
+  backthread                    Set up Backthread here (the front door): sign in, connect
+                          this repo, wire up capture. Idempotent \u2014 re-run it anytime.
                           [--claim <code>]
-  backthread login              Authorize this device (opens your browser)
-  backthread login --claim <code>
-                          Authorize with a single-use claim code from the web app
-                          (no browser needed \u2014 codes expire in ~10 minutes)
-  backthread login --device     Headless / SSH login (device-code flow \u2014 coming soon)
-  backthread whoami             Show the current device's config (token is never printed)
-  backthread how <question>     Ask how/why something in this repo works \u2014 prints a
-                          grounded, cited answer from your Backthread decision log
-                          (backs the /backthread:how slash command). [--cwd <path>]
+  backthread start              Same as above, behind the /backthread:start slash command.
+  backthread login              Authorize this device (opens your browser; works over SSH \u2014
+                          the printed URL opens on any device) [--claim <code>] [--device]
+  backthread logout             Sign this device out \u2014 drop the local token, keep the repo link
+  backthread whoami             Show this device's config (the token is never printed)
+
+Ask
+  backthread how <question>     Ask how/why something here works \u2014 a grounded, cited answer
+                          from your decision log (backs /backthread:how). [--cwd <path>]
+
+Capture
   backthread capture            Capture this session's decisions (run by the SessionEnd/Stop hook)
-  backthread capture --from-hook
-                          Shared multi-agent hook entrypoint: read the hook payload off
-                          STDIN and capture the named transcript (always exits 0)
-                          [--agent <codex|cursor|gemini-cli>] [--detach]
-  backthread capture --manual   Manually capture a session now (the /backthread capture slash command)
+  backthread capture --manual   Capture the current session now (the /backthread capture command)
                           [--session <id>] [--transcript <path>] [--cwd <dir>]
   backthread mcp                Start the MCP server (capture + query tools) over stdio
-  backthread install            Set up capture for this repo (login + hook + backfill history)
-                          [--claim <code>] [--skip-auth] [--skip-hook] [--skip-backfill]
-  backthread install --agent <codex|cursor|gemini>
-                          Set up capture for another agent: write its USER-GLOBAL
-                          MCP server config + session-end capture hook (idempotent)
-  backthread help               Show this message
 
-Docs: https://app.backthread.dev`;
+Manage
+  backthread install            Set up capture for this repo (login + hook + backfill history)
+                          [--claim <code>] [--agent <codex|cursor|gemini>] [--skip-auth]
+                          [--skip-hook] [--skip-backfill]
+  backthread update             Update a global install to the latest (also -u). npx is
+                          always latest already; the plugin updates via /plugin update.
+  backthread doctor             Diagnose your setup \u2014 auth, capture hook, connectivity,
+                          version, repo. Prints \u2713/\u2717 with fix hints; exits non-zero if broken.
+  backthread version            Print the installed version (also --version, -v)
+  backthread help               Show this message (also --help, -h)
+
+Your source never leaves your machine unredacted \u2014 it's checkable in this OSS repo.
+Docs:     https://app.backthread.dev
+Security: https://backthread.dev/security`;
+var KNOWN_COMMANDS = [
+  "start",
+  "login",
+  "logout",
+  "whoami",
+  "how",
+  "ask",
+  "capture",
+  "mcp",
+  "install",
+  "update",
+  "doctor",
+  "version",
+  "help"
+];
 function parseClaimFlag(rest) {
   const i = rest.indexOf("--claim");
   if (i === -1) return void 0;
@@ -34089,6 +34568,18 @@ async function main(argv, deps = {}) {
       console.log(lines.join("\n"));
       return cfg.device_token ? 0 : 1;
     }
+    case "logout": {
+      const logoutImpl = deps.runLogoutImpl ?? runLogout;
+      const result = await logoutImpl();
+      console.log(result.message);
+      return result.ok ? 0 : 1;
+    }
+    case "doctor": {
+      const doctorImpl = deps.runDoctorImpl ?? runDoctor;
+      const result = await doctorImpl();
+      console.log(result.text);
+      return result.exitCode;
+    }
     case "capture": {
       if (rest.includes("--from-hook")) {
         const raw = await readRawHookInput();
@@ -34165,6 +34656,19 @@ async function main(argv, deps = {}) {
     }
     case void 0:
       return onboarding(rest);
+    case "update":
+    case "--update":
+    case "-u": {
+      const updateImpl = deps.runUpdateImpl ?? runUpdate;
+      const result = await updateImpl();
+      console.log(result.message);
+      return result.ok ? 0 : 1;
+    }
+    case "version":
+    case "--version":
+    case "-v":
+      console.log(cliVersion());
+      return 0;
     case "help":
     case "--help":
     case "-h":
@@ -34172,9 +34676,14 @@ async function main(argv, deps = {}) {
       return 0;
     default:
       if (command.startsWith("-")) return onboarding(argv);
-      console.error(`Unknown command: ${command}
-
-${USAGE}`);
+      {
+        const guess = nearestCommand(command, KNOWN_COMMANDS);
+        const didYouMean = guess ? ` Did you mean \`backthread ${guess}\`?` : "";
+        console.error(
+          `Unknown command: ${command}.${didYouMean}
+Run \`backthread help\` to see everything backthread can do.`
+        );
+      }
       return 1;
   }
 }
@@ -34185,7 +34694,7 @@ function isEntryPoint() {
     const self = fileURLToPath2(import.meta.url);
     const resolve = (p) => {
       try {
-        return realpathSync(p);
+        return realpathSync2(p);
       } catch {
         return p;
       }