viewable-one 0.0.0-stage → 0.12.1

package/lib/doctor.mjs

@@ -0,0 +1,464 @@
+// ONE LIST, ONE ROW EACH, and a green run means "a session filed from the
+// board in this folder will actually start".
+//
+// Everything a person could otherwise only learn by running a session and
+// watching it fail: is this folder registered, is the daemon loaded, is it
+// beating, is the board sign-in one the board will still accept, does this
+// machine have an engine, is Claude Code logged in, is there a newer version.
+// Six questions plus the four the sync already answers (ruling 5: "doctor
+// lists each as a row").
+//
+// "IS THE APP WRITING THE MIRROR" WAS THE FIFTH, and it is retired 2026-09-13
+// along with the row that asked it - the mirror has not existed since
+// 2026-09-11. The count is unchanged because the sign-in row stopped being a
+// file-exists check on the same day and became a real one. See both dated
+// notes below.
+//
+// EXIT 0 WHEN ALL GREEN, 1 OTHERWISE, because a doctor whose exit code says
+// nothing cannot be put in front of anything.
+//
+// A ROW IS NEVER RED FOR A FACT ABOUT THE WORLD rather than about this
+// install. Offline is "unknown", not a failure - a machine on a plane is not
+// broken. An engine that is not installed is only red when NO engine is.
+//
+// TWO ROWS JOINED THE LIST ON 2026-09-07 (brief 21, session 4).
+//
+// The FIRST row now names the platform, per ruling 6C: "macOS", "Windows" or
+// "WSL (Linux)". It is there because every row under it means something
+// slightly different depending on the answer - "login agent" is a LaunchAgent
+// on one machine, a scheduled task on the next - and because "it works in
+// WSL" being mistaken for "it works on Windows" is the exact confusion the
+// ruling exists to end.
+//
+// The GIT row is a WARNING and not a FAIL, per ruling 8B. Without git there
+// is no worktree, so `makeWorktreeImpl` already falls back to running the
+// session in the linked folder itself - unisolated, which is a real cost and
+// not a broken install. On Windows that also means no Bash tool, since Claude
+// Code runs Bash calls through Git Bash. So the row says what is lost and
+// doctor still exits 0: a person who has decided to run unisolated should not
+// have to read a red list for ever.
+
+import { row, warnRow } from "./cli-output.mjs";
+import { PROBE_BINS, detectAgents, execProbe, versionFrom } from "./detect.mjs";
+import { DAEMON_LABEL, daemonPackageVersion, daemonScriptPath, loginDaemon, noDaemonInstall } from "./logindaemon.mjs";
+import { RUNNER_PUSH_STALE_MS } from "./spawn.mjs";
+import { projectMcpServerKey } from "./project-mcp.mjs";
+import { syncFolder } from "./sync.mjs";
+import { readAgentSelection } from "./agent-selection.mjs";
+import { compareVersions, latestFromNpm, packageVersion, verifyInstalledCli } from "./update.mjs";
+import { PERSONAL_TOKEN_REJECTED_HINT, REAUTH_REQUIRED_HINT, hostedStatus } from "./auth.mjs";
+import { presence as hostedPresence } from "./runnerApi.mjs";
+
+// `row` is imported from cli-output.mjs (brief 31 review, 2026-09-12 - it
+// used to be a local copy, byte-identical to lib/uninstall.mjs's own and
+// lib/uninstall-project.mjs's own). `action` is the same escape hatch
+// sync.mjs's own `row()` carries (2026-09-11): the generic "run glytch init"
+// is wrong exactly when init is the thing that already failed, or fixes
+// nothing at all - "not signed in to the board" needs `glytch login`, not
+// `glytch init`, and printing the default there is the same loop ruling 6C
+// named for Task Scheduler.
+
+/** The one-line step that turns a WRITTEN board entry into an AUTHENTICATED
+ * one (brief 30, 2026-09-11). Writing `.mcp.json` / `.codex/config.toml` /
+ * `opencode.json` is this package's job; the OAuth handshake against
+ * `https://app.viewable.one/mcp` is each agent's own, dynamic client
+ * registration meaning there is no shared secret to write into a config file
+ * for it - so doctor names the step rather than performing it.
+ *
+ * VERIFIED AGAINST THE BINARIES INSTALLED ON THIS MACHINE, 2026-09-11:
+ * `codex mcp login <name>` (`codex mcp login --help`, Codex CLI) and
+ * `opencode mcp auth <name>` (`opencode mcp auth --help`, opencode 1.18.23)
+ * are both real subcommands that name the server.
+ *
+ * CLAUDE CODE'S LINE WAS MARKED UNVERIFIED HERE UNTIL 2026-09-12 (brief 31,
+ * Move 2), and the mark was true when it was written: on 2.1.34 `claude mcp
+ * --help` listed only `add`/`add-json`/`get`/`list`/`remove`/`serve`, no
+ * login verb, so `/mcp` inside the interactive TUI was the only path and all
+ * this file could do was repeat the docs. `claude mcp login <name>` exists
+ * from 2.1.186, and it was RUN on 2.1.269 against the real endpoint from
+ * outside a session: "Authenticated with "board". Its tools are now available
+ * in Claude Code." So the line names the verb and its version floor, and
+ * keeps `/mcp` as the fallback for an older install - `viewable init` now runs
+ * the verb itself when the floor is met (lib/init-connect.mjs). */
+// Keyed by the ROW's key, not the agent name: Claude Code's row is always
+// "mcp" (lib/sync.mjs's syncMcpJson names it that regardless of how it was
+// selected), and "codex"/"opencode" already match the agent name because
+// syncProjectMcp and the legacy syncOpencode both key their row on it.
+// RENAMED 2026-09-12 (brief 31, Move 3, ruling 3): the server key each
+// verb names is `glytch`, not `board` - Claude Code's own consent page then
+// registers the client as "Claude Code (glytch)" (Move 4), matching what
+// `.mcp.json`, `.codex/config.toml` and `opencode.json` now all call it.
+export const BOARD_SIGN_IN = {
+  mcp: "Sign in: claude mcp login viewable, on Claude Code 2.1.186 or newer. Below that floor there is no shell verb: open a session on this project, run /mcp, and authenticate the board connection.",
+  codex: "Sign in: codex mcp login viewable",
+  opencode: "Sign in: opencode mcp auth viewable",
+};
+
+/** Append the sign-in step to a row that named a board entry, but only once
+ * the file itself is in a state worth signing in to - never on "unreadable"
+ * or a `write:false` "missing"/"legacy-command" report, where there is
+ * nothing on disk yet for the OAuth flow to reach. */
+async function withSignIn(rows, root) {
+  for (const r of rows) {
+    if (r.ok && Object.hasOwn(BOARD_SIGN_IN, r.key)) {
+      const key = await projectMcpServerKey(root, r.key === "mcp" ? "claude" : r.key);
+      const hint = BOARD_SIGN_IN[r.key].replace("viewable", key);
+      r.detail = r.detail ? `${r.detail} ${hint}` : hint;
+    }
+  }
+  return rows;
+}
+
+// `warnRow` is imported from cli-output.mjs too (same dedup). Ruling 8B, and
+// the only user of it here is the git row. `allGreen` counts it as green,
+// deliberately.
+
+/** "signed in as someone@example.com", or "signed in as account 4db90780..."
+ *  when the board could name the id but not the address. Null when there is
+ *  no account to name at all, which leaves the row's old reason standing.
+ *
+ *  The id is SHORTENED to its first segment on purpose: this row is read by a
+ *  person checking whether the account is the one they think it is, and the
+ *  first eight characters settle that as well as thirty-six do while still
+ *  fitting the line. The full id is in the app's own settings if the two ever
+ *  need comparing character by character. */
+const accountLine = (account) => {
+  if (!account) return null;
+  if (typeof account.email === "string" && account.email !== "") return `signed in as ${account.email}`;
+  if (typeof account.id === "string" && account.id !== "") return `signed in as account ${account.id.split("-")[0]}`;
+  return null;
+};
+
+const ago = (ms) => {
+  const s = Math.round(ms / 1000);
+  if (s < 90) return `${s}s ago`;
+  const m = Math.round(s / 60);
+  if (m < 90) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  return h < 48 ? `${h}h ago` : `${Math.round(h / 24)} days ago`;
+};
+
+/* THE FOLDER-LINKED QUESTION. "Is this folder linked to a board?" is
+ * answered by the "daemon beating" row above: `runner_projects` is where a
+ * linked folder is recorded, and its "never" case already says `No runner
+ * heartbeat for this folder` with the step that fixes it. There is no
+ * second thing to check. */
+
+/** Every row, in the order they are printed. Everything the outside world
+ * answers is injected, so the whole of doctor is testable without a daemon,
+ * a network or a launchctl. */
+export async function doctorRows(
+  root,
+  {
+    env = process.env,
+    exec,
+    launchctl,
+    now = Date.now(),
+    version = packageVersion(),
+    latest = latestFromNpm,
+    loaded,
+    agents,
+    write = true,
+    verify = verifyInstalledCli,
+    // The machine, and what it installs a login daemon as. Both injected so
+    // the suite can print the Windows and WSL lists on this Mac.
+    platform = process.platform,
+    procVersion,
+    impl = loginDaemon({ env, platform, procVersion }),
+    // The "daemon beating" row's own network call (brief 31, "doctor asks
+    // the board") - injected the same way `latest` above is, so the suite
+    // exercises fresh/stale/no-row/offline without a real board-runner or a
+    // real fetch. Real default: bridge/lib/runnerApi.mjs's `presence`,
+    // reading `runner_projects.last_seen_at` under this row's own bearer.
+    presence = hostedPresence,
+    fetchImpl,
+  } = {},
+) {
+  const selected = await readAgentSelection(root);
+  const found = agents ?? (await detectAgents({ env, ...(exec ? { exec } : {}) }));
+
+  // Ruling 6C's row, first, because it says what every row below it means.
+  const what = impl.describe();
+  const rows = [
+    row("platform", "platform", true, what.platformLabel, `your computer runs it as ${what.mechanism} (${what.file})`),
+  ];
+  // Only a fresh terminal can prove the durable entry point. A same-version
+  // checkout or temporary copy must never become the login service (#749).
+  const service = write && !noDaemonInstall(env)
+    ? await verify({ env, platform, expectedVersion: version }) : { ok: true };
+  const synced = await syncFolder(root, { env, exec, launchctl, agents: found,
+    write: write && service.ok, impl, platform, scriptPath: service.scriptPath });
+  rows.push(...await withSignIn(synced.map((r) => !service.ok && r.key === "plist"
+    ? row("plist", impl.rowLabel, false, "not verified", service.error, service.error) : r), root));
+
+  // Move 5, brief 31: the row above only checks that a plist/launcher/unit
+  // is there and loaded - not that it runs the package a person thinks they
+  // installed. His Mac's plist pointed at an `~/.npm/_npx` cache running
+  // 0.5.0 while this same `doctor` ran from a 0.7.0 checkout, and the row
+  // above called the login agent fine because that is all it ever asked. So
+  // this row reads the daemon's OWN script path off disk and compares the
+  // package beside it to the one answering right now - never red for the
+  // FACT that there is no daemon file yet (the row above already says so) or
+  // that the path on disk cannot be resolved to a package, per the "never
+  // red for a fact about the world" rule at the top of this file.
+  const daemonPath = await daemonScriptPath({ env, platform, procVersion, impl });
+  if (daemonPath === null) {
+    rows.push(row("daemonVersion", "daemon package", true, "unknown", "no daemon file to check yet"));
+  } else {
+    const daemonVersion = await daemonPackageVersion(daemonPath);
+    if (daemonVersion === null) {
+      rows.push(row("daemonVersion", "daemon package", true, "unknown", `could not read the package.json beside ${daemonPath}`));
+    } else if (daemonVersion === version) {
+      rows.push(row("daemonVersion", "daemon package", true, "same", `${version} at ${daemonPath}`));
+    } else {
+      rows.push(
+        row(
+          "daemonVersion",
+          "daemon package",
+          false,
+          "mismatch",
+          `${daemonVersion} in ${daemonPath}, ${version} here`,
+          "run `viewable init` from this install so your computer runs it",
+        ),
+      );
+    }
+  }
+
+  // Read once, here, because the "daemon beating" row below needs it before
+  // its own row is pushed (a bearer this doctor already knows is missing is
+  // a wasted network call, not a diagnostic) - reused, unchanged, for the
+  // "board sign-in" row further down. No network call of its own
+  // (hostedStatus's own header): a doctor row read constantly should not
+  // cost one just to learn whether there is a credential on file at all.
+  const boardAuth = await hostedStatus(env);
+
+  // The daemon, in two halves that fail differently: the OS holding the
+  // registration, and the runner actually writing its mark. Ruling 1A chose
+  // Task Scheduler over a Startup shortcut precisely so this half survives on
+  // Windows - `schtasks /query` answers it, a shortcut could not.
+  const state = loaded === undefined ? await impl.loadedState({ env, ...(launchctl ? { exec: launchctl } : {}) }) : { loaded, unavailable: false, why: "" };
+  rows.push(
+    state.loaded
+      ? row("daemon", "daemon loaded", true, "loaded", `${impl.holder} is holding ${DAEMON_LABEL}`)
+      : state.unavailable
+        ? // Ruling 6C: an older WSL with no systemd is told the truth and given
+          // the fallback. The "daemon beating" row below is the honest proof
+          // either way, which is why this one does not go red over a machine
+          // that has no user systemd to install into.
+          warnRow("daemon", "daemon loaded", "no systemd here", state.why)
+        : row("daemon", "daemon loaded", false, "not loaded", `${impl.holder} does not have ${DAEMON_LABEL}: run viewable init`),
+  );
+
+  // THE ROW THIS FILE'S FINDING IS ABOUT (brief 31, 2026-09-12, "doctor asks
+  // the board"). Before this fix the row read a local mark file
+  // (`.glytch/inbox/spawn/.runner.json`, `readMark`) that nothing over rows
+  // writes any more - register/heartbeat replaced it with
+  // `runner_projects.last_seen_at` the day brief 30 Move 1/2 landed, and this
+  // row was simply never updated for that: a 0.7.0 daemon beating the board
+  // every few seconds still read FAIL "stopped" here forever, because the
+  // file it checked had not moved since an earlier daemon last wrote it. So
+  // the row now asks the board directly, through the new read-only
+  // `presence` op (bridge/lib/runnerApi.mjs, supabase/functions/board-runner/
+  // runner.mjs) - the same fact `runner_projects` already answers the app's
+  // own UI with (src/runs/projects.ts), reached the only way this CLI can
+  // reach it: over the hosted endpoint under its own bearer, not PostgREST.
+  //
+  // BOARD SIGN-IN IS CHECKED FIRST so a machine that never ran `glytch
+  // login` gets one clear answer ("sign in to see the heartbeat") rather
+  // than a network call this doctor already knows will refuse for lack of a
+  // bearer - the "board sign-in" row below is where the fix for THAT lives.
+  // NEVER RED for either "not signed in" or "offline": both are facts about
+  // the world, not this install, the same rule the file's own header states
+  // for every other row - a machine on a plane, or one that has not run
+  // `glytch login` yet, is not a daemon that stopped beating.
+  // WHICH ACCOUNT THE BEARER REACHES, filled from the same presence call the
+  // beat row makes (2026-09-14). Null when that call did not happen or did not
+  // come back: this must never turn a row red on its own.
+  let boardAccount = null;
+  if (!boardAuth.signedIn) {
+    rows.push(row("beat", "daemon beating", true, "unknown", "sign in to see the heartbeat"));
+  } else {
+    const presenceResult = await presence({ paths: [root] }, { env, ...(fetchImpl ? { fetchImpl } : {}) });
+    if (presenceResult.ok) boardAccount = presenceResult.account ?? null;
+    if (!presenceResult.ok) {
+      rows.push(row("beat", "daemon beating", true, "unknown", `could not reach the board to check: ${presenceResult.error}`));
+    } else {
+      // "local" is the exact host value bridge/lib/runner.mjs's
+      // registerAndFindProject registers this machine's projects under
+      // (`settings.host ?? "local"`) - matched here too, so a folder this
+      // account also runs on a different, remote host does not read as
+      // "watching" off a stranger's beat.
+      const mine = (presenceResult.projects ?? []).find((p) => p.path === root && p.host === "local");
+      if (!mine) {
+        rows.push(
+          row(
+            "beat",
+            "daemon beating",
+            false,
+            "never",
+            "No runner heartbeat for this folder. Run viewable init from the project folder linked to your board.",
+          ),
+        );
+      } else {
+        const age = now - Date.parse(mine.last_seen_at);
+        rows.push(
+          age <= RUNNER_PUSH_STALE_MS
+            ? row("beat", "daemon beating", true, "watching", `last beat ${ago(age)}`)
+            : row("beat", "daemon beating", false, "stopped", `last beat ${ago(age)}, past the ${RUNNER_PUSH_STALE_MS / 1000}s staleness window`),
+        );
+      }
+    }
+  }
+
+  // The "board mirror" row stood here until 2026-09-13. See the retirement
+  // note above mirrorFreshness's old home for what it was and why it is gone.
+
+  const names = PROBE_BINS.filter((b) => (selected === null || selected.includes(b.key)) && found?.[b.key]?.found).map(
+    (b) => `${b.label}${found[b.key].version ? ` ${found[b.key].version}` : ""}`,
+  );
+  const missing = selected?.filter((key) => !found?.[key]?.found) ?? [];
+  rows.push(
+    missing.length > 0
+      ? row("agents", "coding agents", false, "missing", `Selected but not installed: ${missing.join(", ")}. Install them or rerun viewable init to change the selection.`)
+      : names.length > 0
+      ? row("agents", "coding agents", true, "found", names.join(", "))
+      : row("agents", "coding agents", false, "none", "no coding agent on PATH: install Claude Code, opencode or Codex"),
+  );
+
+  rows.push(
+    selected !== null && !selected.includes("claude")
+      ? row("login", "Claude Code login", true, "n/a", "Claude Code is not selected for this project")
+      : found?.claude?.found !== true
+      ? row("login", "Claude Code login", true, "n/a", "Claude Code is not installed on your computer")
+      : found.claude.loggedIn
+        // The detail no longer names the file (2026-09-12). It said
+        // "~/.claude/.credentials.json is there" and on macOS that file is
+        // usually NOT there - the credential is a login-Keychain item, which
+        // is what lib/detect.mjs asks for first. A row whose state is right
+        // and whose reason is wrong is worse than one that just says the
+        // state: it sends someone looking for a file that was never written.
+        ? row("login", "Claude Code login", true, "logged in", "a stored credential was found: the login Keychain on macOS, ~/.claude/.credentials.json elsewhere")
+        : row("login", "Claude Code login", false, "logged out", "run `claude` once and log in, or sessions fail at spawn"),
+  );
+
+  // ONE ROW (brief 30, W2a): the local stdio MCP server is retired, and
+  // every agent reaches the board through the hosted endpoint now
+  // (bridge/lib/auth.mjs) - so a run's board tools need this to
+  // be true rather than a mirror on disk. No network call: a doctor row read
+  // constantly should not cost one, and `hostedToken`'s own refresh already
+  // covers the "signed in but the access token has aged" case at call time.
+  // `boardAuth` itself was already read above, before the "daemon beating"
+  // row, which needs the same answer first.
+  //
+  // THE CHECK THIS ROW DID NOT HAVE, added 2026-09-13 alongside the backoff
+  // in lib/auth.mjs. "Signed in" used to mean no more than "auth.json is
+  // there", so a machine whose credential the endpoint had revoked read GREEN
+  // on the one row a person checks when their runner cannot authenticate -
+  // the file is present, and presence was the whole test. It is the same
+  // fault the retired "board mirror" row had in the other direction: a row
+  // whose reason is wrong is worse than no row.
+  //
+  // `hostedStatus` now also reports whether the credential carries a
+  // dead-credential mark - written next to auth.json by whichever process met
+  // the refusal, usually the daemon, which is why doctor can report it from a
+  // different process. STILL NO NETWORK CALL: it is one more small file read,
+  // so the bargain the rest of doctor keeps is intact.
+  rows.push(
+    boardAuth.dead === true
+      ? boardAuth.via === "personal token"
+        // A REJECTED PERSONAL TOKEN READS DIFFERENTLY (2026-09-19, brief 43
+        // review, B2). It was never going to expire or refresh - it is
+        // revoked from Settings - so "expired and cannot be renewed" would
+        // have been the wrong sentence even after the mark started being
+        // written for it. "rejected" names what actually happened, and the
+        // hint names the actual fix: a fresh token, not `glytch login`.
+        ? row(
+            "boardAuth",
+            "board sign-in",
+            false,
+            "rejected",
+            `the personal token in ~/.glytch/auth.json was rejected by the board${boardAuth.deadSince ? ` (since ${boardAuth.deadSince})` : ""}`,
+            PERSONAL_TOKEN_REJECTED_HINT,
+          )
+        : row(
+            "boardAuth",
+            "board sign-in",
+            false,
+            "expired",
+            `the credential in ~/.glytch/auth.json was refused by the board${boardAuth.deadSince ? ` (since ${boardAuth.deadSince})` : ""} and cannot be renewed`,
+            REAUTH_REQUIRED_HINT,
+          )
+      : boardAuth.signedIn
+      ? row(
+          "boardAuth",
+          "board sign-in",
+          true,
+          "signed in",
+          // AND WHO AS (2026-09-14). "Signed in" was the whole reason, and a
+          // credential left on a previous account reads exactly like a
+          // credential on the right one - which is how two days of session
+          // reports landed on a board nobody was looking at. The name comes
+          // from the board's `presence` op, which resolved this very token,
+          // so it is the endpoint's answer and not a guess off a local file.
+          // Missing when the call did not happen or did not come back; the
+          // row then says what it always said rather than nothing.
+          accountLine(boardAccount) ??
+            // `via: "personal token"` (brief 43, 2026-09-19) is VIEWABLE_BOARD_TOKEN
+            // persisted to disk rather than read live from the environment -
+            // worded like its own case, not folded into the generic
+            // "auth.json is there" that only ever meant an OAuth login before.
+            (boardAuth.via === "VIEWABLE_BOARD_TOKEN"
+              ? "VIEWABLE_BOARD_TOKEN is set"
+              : boardAuth.via === "personal token"
+                ? "a personal access token is stored in ~/.glytch/auth.json"
+                : "~/.glytch/auth.json is there"),
+        )
+      : row(
+          "boardAuth",
+          "board sign-in",
+          false,
+          "not signed in",
+          "run `viewable login`, or set VIEWABLE_BOARD_TOKEN to a personal access token for a script",
+          "Run `viewable login`. It opens a browser to sign in and approve, and the credential lands in ~/.glytch/auth.json. Re-running `viewable init` does not do this step.",
+        ),
+  );
+
+  // Ruling 8B: no git is a WARNING and sessions run unisolated. On Windows it
+  // is Git for Windows, and it carries the Bash tool with it.
+  const git = await (exec ?? execProbe)("git", ["--version"]);
+  rows.push(
+    git?.ok === true
+      ? row("git", "git", true, "found", versionFrom(git.stdout) ? `git ${versionFrom(git.stdout)}` : "git is on PATH")
+      : warnRow(
+          "git",
+          "git",
+          "missing",
+          impl.platform === "windows"
+            ? "no git: sessions run unisolated in the linked folder, and Claude Code's Bash tool needs Git for Windows"
+            : "no git: sessions run unisolated in the linked folder, with no worktree of their own",
+        ),
+  );
+
+  const newestPublished = await latest().catch(() => null);
+  rows.push(
+    newestPublished === null
+      ? row("version", "version", true, "unknown", `${version} installed; npm did not answer (offline?)`)
+      : compareVersions(newestPublished, version) > 0
+        ? row("version", "version", true, "update available", `${version} installed, ${newestPublished} on npm: npm i -g glytch`)
+        : row("version", "version", true, "current", `${version} is the latest`),
+  );
+
+  return rows;
+}
+
+/** Format for a terminal. One row per line, the state in a column, the detail
+ * after it. */
+export function formatRows(rows) {
+  return rows.map(
+    (r) => `${r.warn ? "warn" : r.ok ? "ok  " : "FAIL"}  ${r.label.padEnd(22)} ${r.state.padEnd(16)} ${r.detail}`,
+  );
+}
+
+/** A warn row is green (ruling 8B): the install works, and what it costs is
+ * printed rather than counted as a failure. */
+export const allGreen = (rows) => rows.every((r) => r.ok);

package/lib/exitClass.mjs

@@ -0,0 +1,64 @@
+// Exit code classification for child processes. Distinguishes crashes (SIGSEGV,
+// SIGABRT, etc.) from clean exits and other failures, so runRequest can retry
+// crashes that happen before any output streamed.
+
+/** 128+N, the shell's own spelling of "died on signal N", which is how a
+ * Windows child reports a crash it has no signal to carry. Only the signals
+ * the set below already calls a crash are listed, and SIGKILL is deliberately
+ * absent: 137 there would be someone else's kill, and the runner's own kill
+ * arrives as `isKill` through the signal branch. */
+const WINDOWS_SIGNAL_EXITS = new Map([
+  [132, "SIGILL"],
+  [133, "SIGTRAP"],
+  [134, "SIGABRT"],
+  [135, "SIGBUS"],
+  [136, "SIGFPE"],
+  [139, "SIGSEGV"],
+]);
+
+/** Classify a child's exit code and signal.
+ * Returns { isCrash: boolean, isKill: boolean, description: string }. */
+export function classifyExit(code, signal, platform = process.platform) {
+  // SIGKILL is never retried - it means the runner itself killed the child.
+  if (signal === "SIGKILL") {
+    return { isCrash: false, isKill: true, description: "killed (SIGKILL)" };
+  }
+
+  // Unix crash signals
+  const crashSignals = new Set(["SIGSEGV", "SIGABRT", "SIGBUS", "SIGILL", "SIGFPE", "SIGTRAP"]);
+  if (signal && crashSignals.has(signal)) {
+    return { isCrash: true, isKill: false, description: `crash (${signal})` };
+  }
+
+  // Windows crash codes (access violation, stack overflow, etc.)
+  // 0xC0000005 = access violation, 0xC00000FD = stack overflow
+  const windowsCrashCodes = new Set([0xC0000005, 0xC00000FD, 3221225477, 3221225725]);
+  if (typeof code === "number" && windowsCrashCodes.has(code)) {
+    const hex = `0x${code.toString(16).toUpperCase()}`;
+    return { isCrash: true, isKill: false, description: `crash (${hex})` };
+  }
+
+  // A CRASH ON WINDOWS ARRIVES AS A NUMBER, NEVER AS A SIGNAL (2026-09-07,
+  // brief 21, the first windows-latest run). Windows has no signals, so a child
+  // that aborts - `process.abort()`, an assertion failure, a Node fatal error -
+  // closes with `signal === null` and code 128+SIGABRT, the same 128+N
+  // convention a POSIX shell reports. The crash-signal set above therefore saw
+  // nothing, every abort read as "exit 134", and BOTH halves of the retry
+  // ruling were wrong on that platform: a crash before any output was not
+  // retried, and a crash after output was reported as a plain non-zero exit
+  // rather than as the crash it was. Only win32, because a POSIX child that
+  // aborts brings its signal with it and one that exits 134 deliberately means
+  // 134.
+  if (platform === "win32" && typeof code === "number" && WINDOWS_SIGNAL_EXITS.has(code)) {
+    return { isCrash: true, isKill: false, description: `crash (${WINDOWS_SIGNAL_EXITS.get(code)})` };
+  }
+
+  // Not a crash
+  if (signal) {
+    return { isCrash: false, isKill: false, description: signal };
+  }
+  if (typeof code === "number") {
+    return { isCrash: false, isKill: false, description: `exit ${code}` };
+  }
+  return { isCrash: false, isKill: false, description: "unknown" };
+}

package/lib/glytchFolder.mjs

@@ -0,0 +1,105 @@
+// THE GLYTCH FOLDER (2026-09-30, the owner's ruling: "like we have .claude we
+// have .glytch by default ... cowork also created projects in Documents").
+//
+// ~/.glytch stays the runner's own, hidden. ~/Glytch is the person's: a
+// visible folder, a git repository, registered like any folder `glytch init`
+// adds. A chat on a board with no folder picked works here, in a subfolder
+// named after the board (`boardFolder` on a chat-turn request, bridge/SPAWN.md),
+// so every board has somewhere to work before anyone has linked a folder.
+//
+// Made when the daemon starts watching, and kept: nothing here removes it.
+
+import { lstat, mkdir, realpath, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { addFolder } from "./registry.mjs";
+import { git, isChatWorktreePath, resolveChatCwd } from "./worktree.mjs";
+
+/** Where the Glytch folder lives, or null when there is none to make.
+ *
+ * GLYTCH_FOLDER names it, and "off" turns it off. A scratch GLYTCH_HOME (the
+ * tests, and every agent that runs glytch for real) gets none unless it names
+ * one: a test must never make a folder in the real home. */
+export function glytchFolderPath(env = process.env) {
+  const named = (env.VIEWABLE_FOLDER ?? env.GLYTCH_FOLDER)?.trim();
+  if (named === "off") return null;
+  if (named) return resolve(named);
+  if ((env.VIEWABLE_HOME ?? env.GLYTCH_HOME)?.trim()) return null;
+  return join(homedir(), "Glytch");
+}
+
+const README =
+  "# Viewable\n\n" +
+  "Coding agents on your boards work here when a board has no folder of its own.\n" +
+  "Each board gets its own subfolder, named after the board.\n\n" +
+  "To have an agent work somewhere else, pick another folder in the chat's folder menu.\n";
+
+// A first commit needs a name and an email, and a fresh machine may have
+// neither. These apply to this one commit only; signing is off for the same
+// reason (a signing prompt would hang the daemon).
+const COMMITTER = ["-c", "user.name=Viewable", "-c", "user.email=glytch@localhost", "-c", "commit.gpgsign=false"];
+
+/** Make the Glytch folder if it is missing, as a git repository with one
+ *  commit (a chat worktree is cut from a commit), and register it. Returns
+ *  the path, or null when there is none. Never throws: a daemon that cannot
+ *  make it still watches every other folder. */
+export async function ensureGlytchFolder(env = process.env, log = () => {}) {
+  const path = glytchFolderPath(env);
+  if (path === null) return null;
+  try {
+    await mkdir(path, { recursive: true });
+    // Its own repository, not one it happens to sit inside: a home folder
+    // kept under git would otherwise lend ~/Glytch its history.
+    const top = await git(["rev-parse", "--show-toplevel"], path);
+    if (!top.ok || (await realpath(top.stdout.trim())) !== (await realpath(path))) {
+      const init = await git(["init"], path);
+      if (!init.ok) throw new Error(`git init failed: ${init.stderr?.trim() || "no detail"}`);
+      await git(["symbolic-ref", "HEAD", "refs/heads/main"], path);
+    }
+    const head = await git(["rev-parse", "--verify", "HEAD"], path);
+    if (!head.ok) {
+      const readme = join(path, "README.md");
+      // Never write through a link or over a file already there. "wx" alone
+      // is enough on POSIX, but Windows follows a dangling link on create and
+      // writes its target, so anything at the name (a link included) is left.
+      const taken = await lstat(readme).then(() => true, (error) => { if (error?.code === "ENOENT") return false; throw error; });
+      if (!taken) {
+        try { await writeFile(readme, README, { flag: "wx" }); } catch (error) { if (error?.code !== "EEXIST") throw error; }
+      }
+      await git(["add", "README.md"], path);
+      const commit = await git([...COMMITTER, "commit", "-m", "Viewable folder"], path);
+      if (!commit.ok) throw new Error(`first commit failed: ${commit.stderr?.trim() || "no detail"}`);
+      log(`made the Viewable folder at ${path}`);
+    }
+    await addFolder(path, env);
+    return path;
+  } catch (error) {
+    log(`could not make the Viewable folder at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+// ---------- THE BOARD'S SUBFOLDER, on a chat turn ----------
+
+/** The chat worktree and the board's subfolder a chat turn runs in. A first
+ *  turn names the tree, and the subfolder is the board's name. Every turn
+ *  after it hands back the runner's own cwd, the subfolder it ran in, and
+ *  keeps it: a renamed board's conversation stays with its files. The parent
+ *  is asked first, so a board named "chat-…" is not read as a tree. */
+export function chatBoardOf(root, cwd, name) {
+  return isChatWorktreePath(root, dirname(cwd)) ? { tree: dirname(cwd), name: basename(cwd) } : { tree: cwd, name };
+}
+
+/** Make the board's subfolder inside the chat worktree and return it, or a
+ *  refusal in words. Checked again once made: a link planted under that name
+ *  would lead the agent out of the folder. */
+export async function makeBoardCwd(root, tree, name) {
+  const path = join(tree, name);
+  try {
+    await mkdir(path, { recursive: true });
+  } catch (error) {
+    return { ok: false, reason: `Could not make the board's folder ${path}: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const checked = resolveChatCwd(root, path);
+  return checked.ok ? { ok: true, path } : { ok: false, reason: `The board's folder ${path}: ${checked.reason}` };
+}