viewable-one 0.0.0-stage → 0.12.1

package/lib/project-mcp.mjs

@@ -0,0 +1,288 @@
+// Fresh configs write viewable (#2328). Existing glytch entries stay readable and keep their name (#2196).
+// Add only the glytch entry, preserving comments, other servers, and any
+// glytch entry the user already owns. Validate both before and after editing.
+//
+// RENAMED 2026-09-12 (brief 31, Move 3): the key written is `glytch`, not
+// `board` - Codex gets `[mcp_servers.glytch]`, opencode gets `mcp.glytch`.
+// An existing `board` entry recognised as ours - the old spawned-command
+// shape, or a `board` entry already at our hosted URL from before this
+// rename - is renamed to `glytch` in place, the same upgrade path
+// `mcpjson.mjs` takes for `.mcp.json`. A `board` entry that is a stranger's
+// own (a different URL, no recognisable legacy command) is left exactly
+// alone, reported `present` as before.
+//
+// MOVED 2026-10-03: `prompt.glytch.ai` is retired for `app.viewable.one`
+// (lib/mcpjson.mjs says why a redirect is not enough). An entry at the
+// retired address counts as ours, and wherever a merge keeps an entry of ours
+// (a `board` renamed to `glytch`, or an existing `glytch`) its `url` is
+// replaced with the current one, other fields kept. A `glytch` entry at any
+// other url is left alone.
+import { mkdir, readFile, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { parse as parseToml, stringify } from "smol-toml";
+import { parse as parseJsonc, modify, applyEdits } from "jsonc-parser";
+import { BOARD_MCP_URL, CODEX_TOOL_TIMEOUT_SEC, RETIRED_BOARD_MCP_URLS, entryIsAtRetiredUrl, isLegacyBoardCommand, moveRetiredUrl } from "./mcpjson.mjs";
+import { writeFileAtomic } from "./atomic.mjs";
+
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+export async function readOptional(path) {
+  try { return await readFile(path, "utf8"); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+/** Every server name already on disk for this agent, newest first, so sign-out
+ * can reach each credential before its entry is removed (#2196, #2328). */
+export async function projectMcpServerKeys(root, agent) {
+  if (!root) return [];
+  try {
+    let servers;
+    if (agent === "codex") {
+      servers = parseToml(await readOptional(join(root, ".codex/config.toml")) ?? "").mcp_servers;
+    } else if (agent === "opencode") {
+      const text = await readOptional(join(root, "opencode.jsonc")) ?? await readOptional(join(root, "opencode.json"));
+      servers = parseJsonc(text ?? "{}")?.mcp;
+    } else {
+      servers = JSON.parse(await readOptional(join(root, ".mcp.json")) ?? "{}").mcpServers;
+    }
+    // "glytch" is the compatibility read: keep existing MCP names.
+    return ["viewable", "glytch"].filter((name) => Object.hasOwn(servers ?? {}, name));
+  } catch { /* The writer reports malformed configs; sign-in must not rewrite them. */ }
+  return [];
+}
+
+/** Use the name already on disk for sign-in, including pre-Viewable installs (#2196).
+ * Reuse the same readers/parsers as the config writers below. */
+export async function projectMcpServerKey(root, agent, fallback = "viewable") {
+  return (await projectMcpServerKeys(root, agent))[0] ?? fallback;
+}
+
+/** Remove a TOML table by its exact header - e.g. `"mcp_servers.board"` or
+ * `"mcp_servers.glytch"` - and any of its own sub-tables (`header.*`, e.g.
+ * the old `.env` table carrying `PM_BOARD_ROOT`), stopping at the next
+ * top-level table header or end of file. Returns null when no such header
+ * is found, so a caller never silently no-ops a rewrite it could not
+ * locate.
+ *
+ * This is a TEXT splice rather than a round trip through the TOML parser on
+ * purpose: smol-toml can stringify a whole document but not patch one line
+ * in place while keeping someone else's comments, which is the same reason
+ * `mergeCodexBoard` below always re-parses and checks the result before
+ * trusting it. Used here to remove a `board` table recognised as OURS
+ * (`boardEntryIsOurs` below, covering both the retired command shape and a
+ * `board` entry already at our hosted URL) - a hand-written custom entry
+ * never reaches this.
+ *
+ * EXPORTED (brief 31 review, 2026-09-12), parameterised on `header`, so
+ * lib/uninstall-project.mjs can remove `[mcp_servers.glytch]` with the exact
+ * same splice rather than keeping its own byte-identical copy. */
+export function withoutTomlTable(text, header) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l.trim() === `[${header}]`);
+  if (start === -1) return null;
+  let end = start + 1;
+  while (end < lines.length) {
+    const trimmed = lines[end].trim();
+    if (trimmed.startsWith("[") && !trimmed.startsWith(`[${header}.`)) break;
+    end++;
+  }
+  let from = start;
+  if (from > 0 && lines[from - 1].trim() === "") from--;
+  return [...lines.slice(0, from), ...lines.slice(end)].join("\n");
+}
+
+/** Replace the retired `url` inside one TOML table with the current one, as a
+ * TEXT edit of that single line (same reason as `withoutTomlTable`: keep
+ * someone else's comments and layout). Only the table's own key lines are
+ * searched - up to the next header of any kind. Returns null when the line
+ * cannot be located (an inline table, dotted keys), so the caller refuses
+ * rather than guesses. */
+function withMovedTomlUrl(text, header, to) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l.trim() === `[${header}]`);
+  if (start === -1) return null;
+  const pattern = new RegExp(`^(\\s*url\\s*=\\s*)(["'])(?:${RETIRED_BOARD_MCP_URLS.map(url => url.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\2`);
+  for (let i = start + 1; i < lines.length && !lines[i].trim().startsWith("["); i++) {
+    if (pattern.test(lines[i])) {
+      lines[i] = lines[i].replace(pattern, (_all, lead, quote) => `${lead}${quote}${to}${quote}`);
+      return lines.join("\n");
+    }
+  }
+  return null;
+}
+
+/** Is this Codex `board` table ours - the retired spawned-command shape, or
+ * a `board` entry already sitting at our hosted URL from before this
+ * rename? Mirrors `boardEntryIsOurs` in lib/mcpjson.mjs; kept as its own
+ * function here because the TOML shape (`{url}`, no `type`) is Codex's own.
+ *
+ * EXPORTED (brief 31 review, 2026-09-12) for the same reuse reason as
+ * `withoutTomlTable` above. */
+export function boardEntryIsOurs(entry, env) {
+  if (!object(entry)) return false;
+  if (isLegacyBoardCommand(entry.command, entry.args)) return true;
+  return typeof entry.url === "string" && (entry.url === BOARD_MCP_URL(env) || RETIRED_BOARD_MCP_URLS.includes(entry.url));
+}
+
+/** opencode's own shape: a `command` ARRAY rather than separate
+ * `command`/`args` strings, plus `{type, url}` for the hosted shape. Kept as
+ * its own function (rather than reusing `boardEntryIsOurs` above) because
+ * opencode's `command` field is an array where Codex's and `.mcp.json`'s are
+ * separate `command`/`args` strings - EXPORTED for the same reuse reason as
+ * `withoutTomlTable` and `boardEntryIsOurs` above: lib/uninstall-project.mjs
+ * used to keep a byte-identical copy of exactly this check. */
+export function opencodeBoardEntryIsOurs(entry, env) {
+  if (!object(entry)) return false;
+  if (Array.isArray(entry.command) && isLegacyBoardCommand(entry.command[0], entry.command.slice(1))) return true;
+  return typeof entry.url === "string" && (entry.url === BOARD_MCP_URL(env) || RETIRED_BOARD_MCP_URLS.includes(entry.url));
+}
+
+export function mergeCodexBoard(existing, env = process.env) {
+  try {
+    const parsed = parseToml(existing ?? "");
+    if (parsed.mcp_servers !== undefined && !object(parsed.mcp_servers)) return { kind: "unreadable" };
+    const servers = parsed.mcp_servers ?? {};
+    // Compatibility: keep existing names; only fresh entries use viewable (#2196).
+    if (Object.hasOwn(servers, "viewable")) return { kind: "present" };
+    // A fresh entry gets the tool timeout (see CODEX_TOOL_TIMEOUT_SEC); an
+    // entry already there keeps its own settings.
+    const server = { url: BOARD_MCP_URL(env), tool_timeout_sec: CODEX_TOOL_TIMEOUT_SEC };
+    const boardEntry = servers.board;
+    const boardIsOurs = boardEntryIsOurs(boardEntry, env);
+
+    if (!Object.hasOwn(servers, "glytch")) {
+      if (!Object.hasOwn(servers, "board")) {
+        const added = stringify({ mcp_servers: { viewable: server } });
+        const text = `${existing ?? ""}\n${added}\n`;
+        // Inline tables cannot be extended. Refuse rather than rewrite
+        // someone's entire config and lose comments or alter unrelated
+        // settings.
+        parseToml(text);
+        return { kind: existing === null ? "create" : "add", text };
+      }
+      if (!boardIsOurs) return { kind: "present" };
+      const stripped = withoutTomlTable(existing ?? "", "mcp_servers.board");
+      // Could not safely locate the old table's textual span (a hand-edited
+      // inline table, say) - never guess at a splice, leave it exactly as
+      // the presence rule always has.
+      if (stripped === null) return { kind: "present" };
+      const glytchValue = isLegacyBoardCommand(boardEntry.command, boardEntry.args) ? server : moveRetiredUrl(boardEntry, env);
+      const added = stringify({ mcp_servers: { glytch: glytchValue } });
+      const text = `${stripped}\n${added}\n`;
+      const check = parseToml(text);
+      if (JSON.stringify(check.mcp_servers?.glytch) !== JSON.stringify(glytchValue)) return { kind: "unreadable" };
+      return { kind: "legacy", ...(entryIsAtRetiredUrl(boardEntry, env) ? { moved: true } : {}), text };
+    }
+
+    // `glytch` is already there. Drop a leftover `board` table that is ours;
+    // leave everything else, including a stranger's own "board", untouched.
+    // A `glytch` table at the retired address is ours too: its `url` line is
+    // replaced in place.
+    const glytchMoved = entryIsAtRetiredUrl(servers.glytch, env);
+    if (!boardIsOurs && !glytchMoved) return { kind: "present" };
+    let text = existing ?? "";
+    if (boardIsOurs) {
+      const stripped = withoutTomlTable(text, "mcp_servers.board");
+      if (stripped === null) return { kind: "present" };
+      text = stripped;
+    }
+    if (glytchMoved) {
+      // Not locatable as a plain `url = "..."` line: say so rather than
+      // report a dead address as an entry that is kept.
+      const moved = withMovedTomlUrl(text, "mcp_servers.glytch", BOARD_MCP_URL(env));
+      if (moved === null) return { kind: "unreadable" };
+      text = moved;
+    }
+    const check = parseToml(text);
+    if (!object(check.mcp_servers) || !Object.hasOwn(check.mcp_servers, "glytch")) return { kind: "unreadable" };
+    if (glytchMoved && check.mcp_servers.glytch?.url !== BOARD_MCP_URL(env)) return { kind: "unreadable" };
+    return { kind: "legacy", ...(glytchMoved ? { moved: true } : {}), text };
+  } catch { return { kind: "unreadable" }; }
+}
+
+export function mergeOpencodeBoard(existing, env = process.env) {
+  const text = existing ?? "{}\n";
+  const errors = [];
+  const parsed = parseJsonc(text, errors, { allowTrailingComma: true });
+  if (errors.length || !object(parsed) || (parsed.mcp !== undefined && !object(parsed.mcp))) return { kind: "unreadable" };
+  if (Object.hasOwn(parsed.mcp ?? {}, "viewable")) return { kind: "present" };
+  const glytchPresent = Object.hasOwn(parsed.mcp ?? {}, "glytch");
+  const boardPresent = Object.hasOwn(parsed.mcp ?? {}, "board");
+  const existingBoard = parsed.mcp?.board;
+  const boardIsOurs = boardPresent && opencodeBoardEntryIsOurs(existingBoard, env);
+  const legacyCommand = boardIsOurs && object(existingBoard) && Array.isArray(existingBoard.command) &&
+    isLegacyBoardCommand(existingBoard.command[0], existingBoard.command.slice(1));
+  const server = { type: "remote", url: BOARD_MCP_URL(env), enabled: true };
+  const formattingOptions = { insertSpaces: true, tabSize: 2, eol: text.includes("\r\n") ? "\r\n" : "\n" };
+
+  if (!glytchPresent) {
+    if (boardPresent && !boardIsOurs) return { kind: "present" };
+    if (!boardPresent) {
+      const updated = applyEdits(text, modify(text, ["mcp", "viewable"], server, { formattingOptions }));
+      const updatedErrors = [];
+      const checked = parseJsonc(updated, updatedErrors, { allowTrailingComma: true });
+      if (updatedErrors.length || JSON.stringify(checked?.mcp?.viewable) !== JSON.stringify(server)) {
+        return { kind: "unreadable" };
+      }
+      return { kind: existing === null ? "create" : "add", text: updated };
+    }
+    // A `board` entry recognised as ours: move it to `glytch` and remove
+    // `board`. A legacy command entry is replaced with the canonical
+    // remote-server value; a url-match entry (already ours, just under the
+    // old key) keeps its own value untouched.
+    const glytchValue = legacyCommand ? server : moveRetiredUrl(existingBoard, env);
+    const edits = [
+      ...modify(text, ["mcp", "glytch"], glytchValue, { formattingOptions }),
+    ];
+    const afterGlytch = applyEdits(text, edits);
+    const removed = applyEdits(afterGlytch, modify(afterGlytch, ["mcp", "board"], undefined, { formattingOptions }));
+    const updatedErrors = [];
+    const checked = parseJsonc(removed, updatedErrors, { allowTrailingComma: true });
+    if (updatedErrors.length || JSON.stringify(checked?.mcp?.glytch) !== JSON.stringify(glytchValue) || Object.hasOwn(checked?.mcp ?? {}, "board")) {
+      return { kind: "unreadable" };
+    }
+    return { kind: "legacy", ...(entryIsAtRetiredUrl(existingBoard, env) ? { moved: true } : {}), text: removed };
+  }
+
+  // `glytch` is already there. Drop a leftover `board` entry that is ours;
+  // leave everything else, including a stranger's own "board", untouched.
+  // A `glytch` entry at the retired address is ours too: its `url` moves.
+  const glytchMoved = entryIsAtRetiredUrl(parsed.mcp?.glytch, env);
+  if (!boardIsOurs && !glytchMoved) return { kind: "present" };
+  let updated = text;
+  if (boardIsOurs) updated = applyEdits(updated, modify(updated, ["mcp", "board"], undefined, { formattingOptions }));
+  if (glytchMoved) updated = applyEdits(updated, modify(updated, ["mcp", "glytch", "url"], BOARD_MCP_URL(env), { formattingOptions }));
+  const updatedErrors = [];
+  const checked = parseJsonc(updated, updatedErrors, { allowTrailingComma: true });
+  if (updatedErrors.length || (boardIsOurs && Object.hasOwn(checked?.mcp ?? {}, "board"))) return { kind: "unreadable" };
+  if (glytchMoved && checked?.mcp?.glytch?.url !== BOARD_MCP_URL(env)) return { kind: "unreadable" };
+  return { kind: "legacy", ...(glytchMoved ? { moved: true } : {}), text: updated };
+}
+
+export async function syncProjectMcp(root, agent, { write = true, env = process.env } = {}) {
+  let relative = agent === "codex" ? ".codex/config.toml" : "opencode.json";
+  // OpenCode gives JSONC precedence; extend that file if it exists.
+  if (agent === "opencode" && await readOptional(join(root, "opencode.jsonc")) !== null) relative = "opencode.jsonc";
+  const path = join(root, relative);
+  const existing = await readOptional(path);
+  const merge = (agent === "codex" ? mergeCodexBoard : mergeOpencodeBoard)(existing, env);
+  const row = (ok, state, detail) => ({ key: agent, label: `${agent} Viewable server`, ok, state, detail });
+  if (merge.kind === "present") return row(true, "present", `${relative}: existing board connection kept`);
+  if (merge.kind === "unreadable") return row(false, "unreadable", `${relative} could not be safely extended; fix its config and run viewable init again. Nothing was overwritten.`);
+  if (!write) {
+    return merge.kind === "legacy"
+      ? row(false, "legacy-command", merge.moved
+        ? `${relative} still names the retired board address - run viewable init to move it to app.viewable.one`
+        : `${relative} still names the retired local MCP server - run viewable init to switch it to the hosted board URL`)
+      : row(false, "missing", `${relative} needs the viewable entry - run: viewable init`);
+  }
+  await mkdir(dirname(path), { recursive: true });
+  // Atomic replacement creates a new inode: carry forward private config
+  // permissions instead of reverting to the process's default creation mode.
+  const mode = existing === null ? 0o600 : (await stat(path)).mode & 0o777;
+  await writeFileAtomic(path, merge.text, "utf8", { mode });
+  return merge.kind === "legacy"
+    ? row(true, "upgraded", merge.moved
+      ? `${relative}: glytch entry moved to app.viewable.one`
+      : `${relative}: glytch entry upgraded from the old command shape to the hosted URL`)
+    : row(true, merge.kind, `${relative}: viewable entry registered for this project`);
+}

package/lib/projectPaths.mjs

@@ -0,0 +1,31 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+/** Refuse symlinks below a linked root, including dangling links. The root
+ * itself may be an OS alias (for example macOS /var). Missing descendants
+ * are permitted for worktrees that have not yet been created. */
+export function staysInProject(root, target) {
+  const base = resolve(root);
+  const path = resolve(root, target);
+  const rel = relative(base, path);
+  if (isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`) || resolve(base, rel) !== path) return false;
+  let current = base;
+  for (const part of rel.split(sep).filter(Boolean)) {
+    current = resolve(current, part);
+    try {
+      if (lstatSync(current).isSymbolicLink()) return false;
+    } catch (error) {
+      if (error.code !== "ENOENT") return false;
+    }
+  }
+  return true;
+}
+
+/** One spelling per directory, for comparing two paths. The native realpath
+ * expands Windows 8.3 short names (`RUNNER~1`, as `os.tmpdir()` returns) to
+ * the long form Git prints, where the JS one keeps them. Windows paths are
+ * case-insensitive, so they are folded there. */
+export function canonicalPath(path) {
+  const real = realpathSync.native(path);
+  return process.platform === "win32" ? real.toLowerCase() : real;
+}

package/lib/refusal.mjs

@@ -0,0 +1,70 @@
+// Refusing a call HERE rather than letting the app refuse the file THERE.
+//
+// The failure this exists to stop, observed twice on 2026-08-25: a session
+// called report with a 74-character title, this bridge cheerfully wrote the
+// ops file and returned success, and the APP refused the whole file - so the
+// session believed it had reported, not one circle existed, and the error
+// landed as a red panel on the user's screen instead of in the transcript of
+// the session that could have fixed it in one turn.
+//
+// Two rules come out of that, and both are enforced by this module's shape:
+//
+// 1. EVERY constraint the bridge states, the bridge checks - before it writes
+//    anything. A documented rule nothing enforces is worse than no rule: it
+//    reads as a guarantee and behaves as a wish.
+// 2. EVERY violation is reported at once. Fixing item 4 and then discovering
+//    item 7 is two more round trips and two more chances for a doomed file to
+//    reach him.
+//
+// Refusing is never truncating. Standing ruling (INBOX_OPS.md, "Reporting"):
+// longer is refused, never shortened. Truncation is what produced a report
+// ending mid-word with an ellipsis, and silently editing a session's headline
+// is worse than making it write a shorter one.
+
+/** A call refused before anything was written, carrying every reason. */
+export class Refusal extends Error {
+  constructor(problems, what) {
+    super(formatProblems(problems, what));
+    this.name = "Refusal";
+    this.problems = problems;
+    this.what = what;
+  }
+}
+
+export const isRefusal = (error) => error instanceof Refusal;
+
+/** Collect problems, keep going, refuse once with all of them.
+ *
+ * A caller stops its pass early only when there is genuinely nothing left to
+ * learn - a `did` that is not an array has no items to walk. Everything
+ * per-item keeps walking, which is the whole point. */
+export function problems() {
+  const found = [];
+  return {
+    note: (message) => found.push(message),
+    get list() {
+      return found;
+    },
+    get any() {
+      return found.length > 0;
+    },
+    /** Throw one Refusal carrying all of them, or return the value unchanged. */
+    settle(what, value) {
+      if (found.length > 0) throw new Refusal(found, what);
+      return value;
+    },
+  };
+}
+
+/** The refusal a session reads. Same voice as the app's own failures
+ * (src/inboxOps.ts, src/boardApi.ts): name the field, the offending index,
+ * the actual number, the cap, and what to do instead. */
+export function formatProblems(list, what = "call") {
+  const nothing = `Nothing was written: no file reached inbox/ops/, so nothing is half-landed on the board. Fix and call again.`;
+  if (list.length === 1) return `This ${what} was refused. ${list[0]}\n${nothing}`;
+  return [
+    `This ${what} was refused: ${list.length} things to fix.`,
+    ...list.map((message, i) => `  ${i + 1}. ${message}`),
+    `${nothing} All ${list.length} are listed because the app stops at the FIRST one and refuses the whole file - and that refusal lands on the user's screen, not here.`,
+  ].join("\n");
+}

package/lib/registry.mjs

@@ -0,0 +1,204 @@
+// WHICH FOLDERS THIS MACHINE WATCHES: ~/.glytch/folders.json, a JSON list of
+// absolute paths.
+//
+// The daemon that brief 19 installs runs ONCE per machine and not once per
+// project, so something has to say which projects it is for. That is this
+// file, and it is a list of paths and nothing else: no per-folder settings, no
+// state, no cache. A folder is in it or it is not, and `glytch init` /
+// `glytch forget` are the only two things that write it.
+//
+// GLYTCH_HOME EXISTS FOR THE TESTS, and only for them. Every path in this
+// package that would otherwise land in the real ~/.glytch goes through
+// glytchHome(), so a test suite that sets GLYTCH_HOME to a temp directory
+// cannot touch the machine it runs on - which matters more here than usual,
+// because the other half of this feature loads a LaunchAgent.
+
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { writeFileAtomic } from "./atomic.mjs";
+import { acquireAdmission } from "./admission.mjs";
+
+/** ~/.glytch, or GLYTCH_HOME when set. */
+export const glytchHome = (env = process.env) =>
+  (env.VIEWABLE_HOME ?? env.GLYTCH_HOME)?.trim() || join(homedir(), ".glytch");
+
+export const registryPath = (env = process.env) => join(glytchHome(env), "folders.json");
+
+// Restore and Remove run in different processes. Reuse admission's exclusive
+// file lock and dead-owner recovery, in a directory separate from run claims.
+export async function withRegistryLock(fn, env = process.env) {
+  const deadline = Date.now() + 10_000;
+  for (;;) {
+    const held = await acquireAdmission(glytchHome(env), { directory: join(glytchHome(env), "registry") });
+    if (held.ok) {
+      try { return await fn(); }
+      finally { await held.release(); }
+    }
+    if (Date.now() >= deadline) throw new Error(held.detail);
+    await new Promise(resolve => setTimeout(resolve, 25));
+  }
+}
+
+const restorePath = (folder, env) => join(glytchHome(env), "registry", `${createHash("sha256").update(resolve(folder)).digest("hex")}.restore`);
+
+export async function folderRestoreGeneration(folder, env = process.env) {
+  try { return await readFile(restorePath(folder, env), "utf8"); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+/** Called under the registry lock BEFORE init restores the hosted row, so a
+ * failed local write cannot leave a successful restore exposed to old ops. */
+export async function markFolderRestore(folder, env = process.env) {
+  await writeFileAtomic(restorePath(folder, env), randomUUID());
+}
+
+// TEMPORARY FOLDERS ARE NEVER REGISTERED (QA 2026-10-01, ticket e7). An agent
+// once started a runner from its scratchpad, and "proof-project
+// (/private/tmp/claude-501/...)" sat in Settings > Connection for days. A
+// folder under the OS temp dir (or /tmp, /private/tmp, /var/folders) is
+// somebody's scratch work, not a project. The exception is a SCRATCH HOME:
+// when GLYTCH_HOME itself lives under a temp root this is a test or a verifier
+// (see the header), and its temp folders are the whole point.
+const tempRoots = () => [tmpdir(), "/tmp", "/private/tmp", "/var/folders", "/private/var/folders"].map((p) => resolve(p));
+const underTemp = (path) => tempRoots().some((root) => path === root || path.startsWith(`${root}${sep}`));
+export const isScratchFolder = (folder, env = process.env) =>
+  underTemp(resolve(folder)) && !underTemp(resolve(glytchHome(env)));
+
+/** The folders with no git repo, for the presence body (QA 2026-10-01,
+ * ticket e2). Such a folder runs IN PLACE - `makeWorktree` finds no repo - so
+ * the prompt editor says so instead of promising "Isolated". A `.git` entry
+ * (the directory, or the file a worktree has) in the folder or any parent is
+ * a repo; a plain stat walk, because this runs on every beat. */
+export function foldersWithoutGit(folders) {
+  return folders.filter((folder) => {
+    for (let dir = resolve(folder); ; dir = dirname(dir)) {
+      if (existsSync(join(dir, ".git"))) return false;
+      if (dirname(dir) === dir) return true;
+    }
+  });
+}
+
+const isDir = async (path) => {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+/** The registered folders, absolute and de-duplicated, oldest first.
+ *
+ * A missing file is an empty list, never an error: a machine that has never
+ * run `init` is not broken, it is new. A file that is not JSON, or is JSON of
+ * the wrong shape, is also an empty list rather than a throw - the daemon
+ * reads this on every start, and a corrupt registry must not be the reason
+ * nothing watches. `init` rewrites it either way. */
+export async function readRegistry(env = process.env) {
+  return (await readRegistryChecked(env)).folders;
+}
+
+/** The same list, and whether the file could actually be read as one.
+ *
+ * `readRegistry` collapses "missing", "not JSON" and "genuinely empty" into
+ * one empty list, which is right for a one-shot read at start and wrong for
+ * the daemon's RE-read (lib/multiwatch.mjs, 2026-09-06): reading an
+ * unreadable registry as "every folder was just removed" would stop every
+ * watcher on the machine over a file someone was half-way through editing.
+ * `ok: false` means "this is not news - keep the last good list".
+ *
+ * A file that is not there is `ok: false` for the same reason. The only
+ * writer in this package is writeFileAtomic, which renames a whole file into
+ * place, so a registry that has gone missing is something outside taking it
+ * away, and the daemon fails toward keeping what it already watches. A
+ * first-ever start is unaffected: it reads through `readRegistry`, gets the
+ * empty list, and still says to run `viewable init`. */
+export async function readRegistryChecked(env = process.env) {
+  const none = { folders: [], ok: false };
+  let raw;
+  try {
+    raw = await readFile(registryPath(env), "utf8");
+  } catch {
+    return none;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return none;
+  }
+  if (!Array.isArray(parsed)) return none;
+  const seen = new Set();
+  const out = [];
+  for (const entry of parsed) {
+    if (typeof entry !== "string" || entry.trim() === "") continue;
+    const path = resolve(entry.trim());
+    if (seen.has(path)) continue;
+    seen.add(path);
+    out.push(path);
+  }
+  return { folders: out, ok: true };
+}
+
+async function writeRegistry(folders, env = process.env) {
+  await mkdir(glytchHome(env), { recursive: true });
+  await writeFileAtomic(registryPath(env), `${JSON.stringify(folders, null, 2)}\n`);
+}
+
+/** Add a folder. Idempotent by absolute path: running `init` twice in one
+ * folder leaves one entry, and the second run is not an error. Returns
+ * {folders, added}. */
+export async function addFolder(folder, env = process.env) {
+  const path = resolve(folder);
+  if (isScratchFolder(path, env)) throw new Error(`${path} is a temporary folder, and those are never registered. Run viewable init in the project folder itself.`);
+  const folders = await readRegistry(env);
+  if (folders.includes(path)) return { folders, added: false };
+  const next = [...folders, path];
+  await writeRegistry(next, env);
+  return { folders: next, added: true };
+}
+
+/** Write the folder list back unchanged. The running daemon reads a rewrite
+ * as a request for one beat from every folder it watches (multiwatch.mjs),
+ * which is how `viewable init` in a folder already watched gets the fresh beat
+ * it waits for (#813 review). A registry that is not there stays absent. */
+export async function touchRegistry(env = process.env) {
+  const { folders, ok } = await readRegistryChecked(env);
+  if (!ok || folders.length === 0) return false;
+  await writeRegistry(folders, env);
+  return true;
+}
+
+/** Remove a folder. Returns {folders, removed}. Forgetting a folder that was
+ * never registered is not an error either - the end state is what was asked
+ * for. */
+export async function removeFolder(folder, env = process.env) {
+  const path = resolve(folder);
+  const folders = await readRegistry(env);
+  if (!folders.includes(path)) return { folders, removed: false };
+  const next = folders.filter((f) => f !== path);
+  await writeRegistry(next, env);
+  return { folders: next, removed: true };
+}
+
+/** Drop entries whose folder no longer exists. Returns the paths dropped, so
+ * the caller can log one line each (the sweep does). A folder that is gone is
+ * gone: nothing here creates it back, and nothing exits over it. */
+export async function pruneMissing(env = process.env) {
+  const folders = await readRegistry(env);
+  const kept = [];
+  const dropped = [];
+  for (const folder of folders) {
+    if (await isDir(folder)) kept.push(folder);
+    else dropped.push(folder);
+  }
+  if (dropped.length > 0) await writeRegistry(kept, env);
+  return { kept, dropped };
+}
+
+/** Forget everything. Only the tests and an uninstall would want this. */
+export async function clearRegistry(env = process.env) {
+  await rm(registryPath(env), { force: true }).catch(() => {});
+}