npm - backthread - Versions diffs - 0.6.0 → 0.8.0 - Mend

backthread 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/.claude-plugin/plugin.json +1 -1
package/README.md +16 -12
package/dist-bundle/backthread.js +743 -297
package/package.json +13 -7

package/dist-bundle/backthread.js CHANGED Viewed

@@ -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,114 +6891,11 @@ 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";
-// src/loopback.ts
-import { createServer } from "node:http";
-import { randomBytes } from "node:crypto";
-function generateState() {
-  return base64url(randomBytes(32));
-}
-function base64url(bytes) {
-  return bytes.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function validateCallback(method, rawUrl, expectedState) {
-  if ((method ?? "").toUpperCase() !== "GET") return { ok: false, reason: "bad_method" };
-  let url2;
-  try {
-    url2 = new URL(rawUrl ?? "", "http://127.0.0.1");
-  } catch {
-    return { ok: false, reason: "wrong_path" };
-  }
-  if (url2.pathname !== "/callback") return { ok: false, reason: "wrong_path" };
-  const errorParam = url2.searchParams.get("error");
-  if (errorParam) return { ok: false, reason: "error_param", error: errorParam };
-  const state = url2.searchParams.get("state");
-  if (state === null || state !== expectedState) return { ok: false, reason: "state_mismatch" };
-  const token = url2.searchParams.get("token");
-  if (!token || !/^backthread_pat_[A-Za-z0-9_-]+$/.test(token)) {
-    return { ok: false, reason: "missing_token" };
-  }
-  return { ok: true, token };
-}
-function resultPage(ok) {
-  const title = ok ? "You\u2019re connected" : "Something went wrong";
-  const body = ok ? "Backthread is now authorized on this device. You can close this tab and return to your terminal." : "Backthread couldn\u2019t finish authorizing this device. Close this tab and run <code>backthread login</code> again.";
-  return `<!doctype html><html><head><meta charset="utf-8"><title>${title}</title>
-<style>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:18vh auto;padding:0 1.5rem;color:#18181b}
-h1{font-size:1.25rem}code{background:#f4f4f5;padding:.1em .3em;border-radius:4px}</style></head>
-<body><h1>${title}</h1><p>${body}</p></body></html>`;
-}
-function startLoopbackServer() {
-  return new Promise((resolveStart, rejectStart) => {
-    const state = generateState();
-    let outcome = null;
-    let onOutcome = null;
-    const deliver = (o) => {
-      if (outcome) return;
-      outcome = o;
-      onOutcome?.();
-    };
-    const server = createServer((req, res) => {
-      const result = validateCallback(req.method, req.url, state);
-      if (!result.ok && result.reason === "wrong_path") {
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end("not found");
-        return;
-      }
-      res.writeHead(result.ok ? 200 : 400, { "Content-Type": "text/html; charset=utf-8" });
-      res.end(resultPage(result.ok));
-      if (result.ok && result.token) {
-        deliver({ token: result.token });
-      } else {
-        deliver({
-          error: new Error(
-            result.reason === "error_param" ? `web app reported: ${result.error}` : `invalid callback (${result.reason})`
-          )
-        });
-      }
-    });
-    server.on("error", (err) => {
-      if (outcome === null && onOutcome === null) rejectStart(err);
-      else deliver({ error: err });
-    });
-    server.listen(0, "127.0.0.1", () => {
-      const addr = server.address();
-      const port = addr.port;
-      const close = () => {
-        try {
-          server.close();
-        } catch {
-        }
-      };
-      const waitForToken = (timeoutMs = 5 * 6e4) => new Promise((resolve, reject) => {
-        const finish = () => {
-          if (!outcome) return;
-          close();
-          if ("token" in outcome) resolve(outcome.token);
-          else reject(outcome.error);
-        };
-        const timer = setTimeout(() => {
-          close();
-          reject(new Error("timed out waiting for the browser to authorize this device"));
-        }, timeoutMs);
-        onOutcome = () => {
-          clearTimeout(timer);
-          finish();
-        };
-        if (outcome) {
-          clearTimeout(timer);
-          finish();
-        }
-      });
-      resolveStart({ port, state, waitForToken, close });
-    });
-  });
-}
 // src/urls.ts
 var DEFAULT_APP_URL = "https://app.backthread.dev";
 function appBaseUrl(env = process.env) {
@@ -7002,10 +6903,11 @@ function appBaseUrl(env = process.env) {
   if (override && override.trim().length > 0) return override.replace(/\/+$/, "");
   return DEFAULT_APP_URL;
 }
-function buildCliAuthUrl(port, state, env = process.env) {
+function buildCliAuthUrl(session, clientPubKey, env = process.env, label) {
   const u = new URL("/cli-auth", appBaseUrl(env));
-  u.searchParams.set("port", String(port));
-  u.searchParams.set("state", state);
+  u.searchParams.set("session", session);
+  u.searchParams.set("k", clientPubKey);
+  if (label && label.trim().length > 0) u.searchParams.set("label", label.trim());
   return u.toString();
 }
 var DEFAULT_WORKER_URL = "https://clew-ingest-worker.arpy-183.workers.dev";
@@ -7032,6 +6934,9 @@ function buildIngestDecisionsUrl(env = process.env) {
 function buildOnboardingStateUrl(env = process.env) {
   return new URL(`${functionsBaseUrl(env).replace(/\/+$/, "")}/onboarding-state`).toString();
 }
+function buildCliAuthPollUrl(env = process.env) {
+  return new URL(`${functionsBaseUrl(env).replace(/\/+$/, "")}/cli-auth-poll`).toString();
+}
 function buildRepoDeepLink(owner, name, env = process.env) {
   const base = appBaseUrl(env);
   return `${base}/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`;
@@ -7044,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: [] };
   }
@@ -7278,22 +7183,117 @@ function configLocationHint(env) {
   return env.BACKTHREAD_CONFIG_DIR ? `${env.BACKTHREAD_CONFIG_DIR}/config.json` : "~/.backthread/config.json";
 }
+// src/cliAuthCrypto.ts
+import { createECDH, hkdfSync, createDecipheriv, randomBytes } from "node:crypto";
+var HKDF_SALT = Buffer.from("backthread-cli-auth");
+var HKDF_INFO = Buffer.from("device-token-v1");
+function generateSessionId() {
+  return toB64url(randomBytes(32));
+}
+function generateEphemeralKeypair() {
+  const ecdh = createECDH("prime256v1");
+  ecdh.generateKeys();
+  return { ecdh, publicKeyB64url: toB64url(ecdh.getPublicKey()) };
+}
+function decryptToken(enc, ecdh) {
+  const pagePub = fromB64url(enc.page_ephemeral_pubkey);
+  const shared = ecdh.computeSecret(pagePub);
+  const aesKey = Buffer.from(hkdfSync("sha256", shared, HKDF_SALT, HKDF_INFO, 32));
+  const ctFull = fromB64url(enc.ciphertext);
+  const tag = ctFull.subarray(ctFull.length - 16);
+  const ct = ctFull.subarray(0, ctFull.length - 16);
+  const iv = fromB64url(enc.iv);
+  const decipher = createDecipheriv("aes-256-gcm", aesKey, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
+}
+function toB64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromB64url(s) {
+  return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+}
+// src/cliAuthPoll.ts
+var TOKEN_RE = /^backthread_pat_[A-Za-z0-9_-]+$/;
+async function pollForToken(sessionId, keypair, opts = {}) {
+  const env = opts.env ?? process.env;
+  const doFetch = opts.fetchImpl ?? fetch;
+  const interval = opts.intervalMs ?? 1500;
+  const timeout = opts.timeoutMs ?? 5 * 6e4;
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = opts.now ?? (() => Date.now());
+  const url2 = buildCliAuthPollUrl(env);
+  const deadline = now() + timeout;
+  while (now() < deadline) {
+    let res;
+    try {
+      res = await doFetch(url2, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...versionHeaders() },
+        // The CLI is the CONSUMING poller (default mode) — the browser peeks separately.
+        body: JSON.stringify({ session_id: sessionId })
+      });
+    } catch {
+      await sleep(interval);
+      continue;
+    }
+    if (res.status === 429 || res.status >= 500) {
+      await sleep(interval);
+      continue;
+    }
+    const body = await res.json().catch(() => null);
+    const status = typeof body?.status === "string" ? body.status : null;
+    if (status === "ready") {
+      const enc = extractPayload(body);
+      if (!enc) return { ok: false, reason: "error", message: "incomplete token payload from the server" };
+      let token;
+      try {
+        token = decryptToken(enc, keypair.ecdh);
+      } catch {
+        return { ok: false, reason: "error", message: "could not decrypt the token (key mismatch)" };
+      }
+      if (!TOKEN_RE.test(token)) {
+        return { ok: false, reason: "error", message: "the decrypted token was malformed" };
+      }
+      return { ok: true, token };
+    }
+    if (status === "expired") {
+      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 `backthread login`" };
+    }
+    await sleep(interval);
+  }
+  return { ok: false, reason: "timeout", message: "timed out waiting for the browser to authorize this device" };
+}
+function extractPayload(body) {
+  if (!body) return null;
+  const { page_ephemeral_pubkey, iv, ciphertext } = body;
+  if (typeof page_ephemeral_pubkey === "string" && typeof iv === "string" && typeof ciphertext === "string") {
+    return { page_ephemeral_pubkey, iv, ciphertext };
+  }
+  return null;
+}
 // src/login.ts
 async function login(opts = {}) {
   const env = opts.env ?? process.env;
   const log = opts.log ?? ((m) => console.error(m));
   if (opts.claim) {
-    const result = await exchangeClaim(opts.claim, { env, label: deviceLabel() });
-    log(result.message);
-    return { ok: result.ok, message: result.message };
+    const result2 = await exchangeClaim(opts.claim, { env, label: deviceLabel() });
+    log(result2.message);
+    return { ok: result2.ok, message: result2.message };
   }
   if (opts.device) {
     return deviceLogin(log);
   }
-  const handle = await startLoopbackServer();
-  const authUrl = buildCliAuthUrl(handle.port, handle.state, env);
+  const sessionId = generateSessionId();
+  const keypair = generateEphemeralKeypair();
+  const authUrl = buildCliAuthUrl(sessionId, keypair.publicKeyB64url, env, deviceLabel());
   log("Opening your browser to authorize this device\u2026");
-  log(`If it doesn't open, visit:
+  log(`If it doesn't open \u2014 or you're on a remote/SSH box \u2014 open this on any device:
   ${authUrl}
 `);
@@ -7303,17 +7303,21 @@ async function login(opts = {}) {
       log("(Could not open a browser automatically \u2014 use the URL above.)");
     }
   }
-  let token;
-  try {
-    token = await handle.waitForToken();
-  } catch (err) {
-    handle.close();
-    return { ok: false, message: `Login failed: ${err.message}` };
+  const poll = opts.pollImpl ?? pollForToken;
+  const result = await poll(sessionId, keypair, { env });
+  if (!result.ok) {
+    return { ok: false, message: pollFailureMessage(result) };
   }
-  await updateConfig({ device_token: token }, env);
+  await updateConfig({ device_token: result.token }, env);
   log(`Authorized. Token stored in ${configLocationHint2(env)} (chmod 0600).`);
   return { ok: true, message: "Device authorized and token stored." };
 }
+function pollFailureMessage(result) {
+  if (result.reason === "expired" || result.reason === "timeout") {
+    return `Login ${result.reason === "expired" ? "expired" : "timed out"}: ${result.message}. Re-run \`backthread login\` to try again.`;
+  }
+  return `Login failed: ${result.message}`;
+}
 function deviceLabel() {
   try {
     const h = hostname();
@@ -7330,10 +7334,11 @@ function deviceLogin(log) {
     [
       "Headless (--device) login is not available yet.",
       "",
-      "The device-code fallback needs a server-side device-authorization endpoint",
-      "that ships in a later task. For now, run `backthread login` on a machine with a",
-      "browser, or mint a token from the web app (Account \u2192 Connected devices) and",
-      'place it in ~/.backthread/config.json under "device_token".'
+      "You usually don\u2019t need it: `backthread login` prints a URL you can open on ANY",
+      "device (phone, laptop) \u2014 the token is delivered by polling, so the browser doesn\u2019t",
+      "have to be on this machine. For a fully browserless box, mint a token from the web",
+      "app (Account \u2192 Connected devices) and place it in ~/.backthread/config.json under",
+      '"device_token", or use `--claim <code>` from the web app.'
     ].join("\n")
   );
   return { ok: false, message: "--device fallback not implemented yet." };
@@ -7347,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]";
@@ -7708,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;
 }
@@ -7722,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)) {
@@ -7736,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 {
   }
@@ -7789,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;
@@ -7802,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;
@@ -7888,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;
@@ -7979,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 {
@@ -8014,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: {} };
   }
@@ -8117,7 +8474,7 @@ async function defaultReadDir(dir) {
 }
 async function defaultPathExists(path) {
   try {
-    await stat2(path);
+    await stat3(path);
     return true;
   } catch {
     return false;
@@ -8131,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;
@@ -8149,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);
@@ -8178,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);
@@ -8206,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);
@@ -8219,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;
@@ -8263,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"
@@ -8324,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) {
@@ -8424,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" }, [
@@ -8435,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);
@@ -8458,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);
@@ -8466,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,
@@ -8481,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);
@@ -8520,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 {
@@ -8594,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) {
@@ -8636,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 {
@@ -8753,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);
@@ -9020,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 {
@@ -9039,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 {};
   }
@@ -9214,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(() => {
@@ -9394,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",
@@ -9436,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) {
@@ -9459,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: {} };
   }
@@ -9632,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) {
@@ -14533,8 +14929,8 @@ function uint8ArrayToBase64(bytes) {
   }
   return btoa(binaryString);
 }
-function base64urlToUint8Array(base64url4) {
-  const base643 = base64url4.replace(/-/g, "+").replace(/_/g, "/");
+function base64urlToUint8Array(base64url3) {
+  const base643 = base64url3.replace(/-/g, "+").replace(/_/g, "/");
   const padding = "=".repeat((4 - base643.length % 4) % 4);
   return base64ToUint8Array(base643 + padding);
 }
@@ -14791,7 +15187,7 @@ var safeDecodeAsync = /* @__PURE__ */ _safeDecodeAsync($ZodRealError);
 var regexes_exports = {};
 __export(regexes_exports, {
   base64: () => base64,
-  base64url: () => base64url2,
+  base64url: () => base64url,
   bigint: () => bigint,
   boolean: () => boolean,
   browserEmail: () => browserEmail,
@@ -14886,7 +15282,7 @@ var mac = (delimiter) => {
 var cidrv4 = /^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$/;
 var cidrv6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|::|([0-9a-fA-F]{1,4})?::([0-9a-fA-F]{1,4}:?){0,6})\/(12[0-8]|1[01][0-9]|[1-9]?[0-9])$/;
 var base64 = /^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$/;
-var base64url2 = /^[A-Za-z0-9_-]*$/;
+var base64url = /^[A-Za-z0-9_-]*$/;
 var hostname2 = /^(?=.{1,253}\.?$)[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[-0-9a-zA-Z]{0,61}[0-9a-zA-Z])?)*\.?$/;
 var domain = /^([a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/;
 var httpProtocol = /^https?$/;
@@ -15900,14 +16296,14 @@ var $ZodBase64 = /* @__PURE__ */ $constructor("$ZodBase64", (inst, def) => {
   };
 });
 function isValidBase64URL(data) {
-  if (!base64url2.test(data))
+  if (!base64url.test(data))
     return false;
   const base643 = data.replace(/[-_]/g, (c) => c === "-" ? "+" : "/");
   const padded = base643.padEnd(Math.ceil(base643.length / 4) * 4, "=");
   return isValidBase64(padded);
 }
 var $ZodBase64URL = /* @__PURE__ */ $constructor("$ZodBase64URL", (inst, def) => {
-  def.pattern ?? (def.pattern = base64url2);
+  def.pattern ?? (def.pattern = base64url);
   $ZodStringFormat.init(inst, def);
   inst._zod.bag.contentEncoding = "base64url";
   inst._zod.check = (payload) => {
@@ -25936,7 +26332,7 @@ __export(external_exports, {
   any: () => any,
   array: () => array,
   base64: () => base642,
-  base64url: () => base64url3,
+  base64url: () => base64url2,
   bigint: () => bigint2,
   boolean: () => boolean2,
   catch: () => _catch2,
@@ -26166,7 +26562,7 @@ __export(schemas_exports2, {
   any: () => any,
   array: () => array,
   base64: () => base642,
-  base64url: () => base64url3,
+  base64url: () => base64url2,
   bigint: () => bigint2,
   boolean: () => boolean2,
   catch: () => _catch2,
@@ -26788,7 +27184,7 @@ var ZodBase64URL = /* @__PURE__ */ $constructor("ZodBase64URL", (inst, def) => {
   $ZodBase64URL.init(inst, def);
   ZodStringFormat.init(inst, def);
 });
-function base64url3(params) {
+function base64url2(params) {
   return _base64url(ZodBase64URL, params);
 }
 var ZodE164 = /* @__PURE__ */ $constructor("ZodE164", (inst, def) => {
@@ -33920,15 +34316,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);
@@ -34001,40 +34397,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;
@@ -34088,6 +34504,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();
@@ -34164,6 +34592,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":
@@ -34171,9 +34612,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;
   }
 }
@@ -34184,7 +34630,7 @@ function isEntryPoint() {
     const self = fileURLToPath2(import.meta.url);
     const resolve = (p) => {
       try {
-        return realpathSync(p);
+        return realpathSync2(p);
       } catch {
         return p;
       }