viewable-one 0.0.0-stage → 0.12.1

package/lib/runnerRegister.mjs

@@ -0,0 +1,96 @@
+// Runner registration and presence, moved out of runner.mjs on 2026-10-03
+// (ticket e8) when `register` became one call per process per beat. The
+// watch loop in runner.mjs is the caller; runner.mjs re-exports
+// `registerAndFindProject` for the tests that reach it there.
+
+import { basename } from "node:path";
+
+import * as runnerApiModule from "./runnerApi.mjs";
+import { addFolder, foldersWithoutGit, isScratchFolder, markFolderRestore, readRegistry, withRegistryLock } from "./registry.mjs";
+import { platformMark } from "./platform.mjs";
+
+/** `register` every folder this machine knows about, plus `root` itself as
+ * a fallback for a single-folder invocation (PM_BOARD_ROOT) that was never
+ * added to `~/.glytch/folders.json`. A machine running several `watch()`
+ * loops (multiwatch.mjs, one per folder) shares one call per beat through
+ * `settings.registrar` (ticket e8). Returns `{ok, projects,
+ * myProjectId}` - `myProjectId` is `root`'s own id in the response, or
+ * undefined when registration failed. */
+/**
+ * WHAT THIS RUNNER SAYS ABOUT ITSELF, in one place (2026-09-13).
+ *
+ * `register` used to add `planApproval: true` and the heartbeat did not - and
+ * the heartbeat REPLACES `runner_projects.presence`, not merges into it. So
+ * the flag lived for one beat interval after each register and was then wiped,
+ * which the app reads as a runner that cannot do read-only planning. Every
+ * plan-mode run was refused with "Plan approval requires Claude Code or Codex,
+ * and an updated runner that supports read-only planning" on a runner that
+ * supports it perfectly well - found by driving it, because the server row
+ * DOES carry the flag for the second after a register and looks right to
+ * anyone who queries it at the wrong moment.
+ *
+ * Two writers of one body is how that happened, so there is one now.
+ */
+export const presenceBody = (settings) => {
+  const { platform: _platform, ...rest } = settings.markExtra?.() ?? {};
+  return { ...rest, planApproval: true, computerAppsLook: true, ...(settings.noGit?.length ? { noGit: settings.noGit } : {}) };
+};
+
+export async function registerAndFindProject(root, settings, { readd = false } = {}) {
+  if (!readd) return registerProject(root, settings);
+  const env = settings.env ?? process.env;
+  return withRegistryLock(async () => {
+    await markFolderRestore(root, env);
+    const out = await registerProject(root, settings, { readd: true });
+    // Publish the local entry before releasing the restore lock. syncRegistry
+    // in init remains idempotent, including when Remove won the lock first.
+    if (out.ok) await addFolder(root, env);
+    return out;
+  }, env);
+}
+
+async function registerProject(root, settings, { readd = false } = {}) {
+  const runnerApi = settings.runnerApi ?? runnerApiModule;
+  const env = settings.env ?? process.env;
+  const folders = await readRegistry(env);
+  // Init only owns this folder; a routine daemon register owns the full list.
+  const paths = readd ? [root] : folders.length > 0 ? folders : [root];
+  const list = paths.filter((path) => !isScratchFolder(path, env));
+  if (list.length === 0) return { ok: false, error: `${root} is a temporary folder, and those are never registered. Run the runner in a project folder.` };
+  // Only init opts in. Capture the removal it intends to undo before any
+  // register work; later folders in a slow routine register acquire no intent.
+  let readdForgottenAt;
+  let runnerId = settings.runnerId ?? "runner";
+  const version = readd ? (settings.markExtra?.() ?? {}).version : undefined;
+  const requestOptions = { env, fetchImpl: settings.fetchImpl,
+    ...(version ? { headers: { "User-Agent": `glytch/${version}` } } : {}),
+  };
+  if (readd) {
+    const before = await runnerApi.presence({ paths: [root] }, requestOptions);
+    if (!before.ok) return { ...before, readdRequired: false };
+    const existing = (before.projects ?? []).find(p => p.path === root && p.host === (settings.host ?? "local"));
+    readdForgottenAt = existing?.forgotten_at;
+    // Preserve the watcher identity so its eventual departure still matches.
+    runnerId = existing?.runner_id || runnerId;
+  }
+  settings.noGit = foldersWithoutGit(list);
+  const send = () => runnerApi.register(
+    {
+      runnerId,
+      host: settings.host ?? "local",
+      platform: (settings.markExtra?.() ?? {}).platform ?? platformMark().platform,
+      presence: presenceBody(settings),
+      projects: list.map((path) => ({ path, name: basename(path),
+        ...(path === root && readdForgottenAt ? { readdForgottenAt } : {}),
+      })),
+    },
+    requestOptions,
+  );
+  // ONE REGISTER PER PROCESS PER BEAT (ticket e8). multiwatch hands every
+  // folder the same `registrar`, so the folders that beat inside one window
+  // share one call for the same folder list instead of each sending it.
+  const out = settings.registrar ? await settings.registrar.register(JSON.stringify(list), send) : await send();
+  if (!out.ok) return { ok: false, error: out.error, ...(readd ? { readdRequired: Boolean(readdForgottenAt) } : {}), ...(out.transient ? { transient: true } : {}), ...(Number.isFinite(out.retryAfterMs) ? { retryAfterMs: out.retryAfterMs } : {}) };
+  const mine = (out.projects ?? []).find((p) => p.path === root);
+  return { ok: true, projects: out.projects ?? [], myProjectId: mine?.id };
+}

package/lib/runnerSettings.mjs

@@ -0,0 +1,40 @@
+// THE RUNNER'S SETTINGS, READ OFF THE ENVIRONMENT (moved out of runner.mjs
+// on 2026-09-27, verbatim). The PM_SPAWN_* switches and their defaults; the
+// runner and every test that builds one import `settingsFromEnv` from
+// runner.mjs, which re-exports it from here.
+
+import { DEFAULTS } from "./child.mjs";
+
+const num = (value, fallback) => {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+export function settingsFromEnv(env = process.env) {
+  return {
+    enabled: env.PM_SPAWN_RUNNER === "on",
+    env,
+    claudeBin: env.PM_CLAUDE_BIN?.trim() || undefined,
+    claudeArgs: parseArgs(env.PM_CLAUDE_ARGS),
+    maxConcurrent: num(env.PM_SPAWN_MAX_CONCURRENT, DEFAULTS.maxConcurrent),
+    pollMs: num(env.PM_SPAWN_POLL_MS, DEFAULTS.pollMs),
+    beatMs: num(env.PM_SPAWN_BEAT_MS, DEFAULTS.beatMs),
+    stallMs: num(env.PM_SPAWN_STALL_MS, DEFAULTS.stallMs),
+    // How often a live streaming child's answers-and-messages poll asks
+    // collect_session while disconnected; joined polls use reply hints and a minute safety read.
+    rowsPollMs: num(env.PM_ROWS_POLL_MS, 5000),
+    // How often the live child log is flushed to `run_events` (item 3 of the
+    // Move 2 contract's runner section). Default 3000ms.
+    logFlushMs: num(env.PM_LOG_FLUSH_MS, 3000),
+    depth: Number(env.PM_SPAWN_DEPTH ?? 0) || 0,
+  };
+}
+
+function parseArgs(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return undefined;
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed) && parsed.every((a) => typeof a === "string")) return parsed;
+  } catch { /* fall through */ }
+  return undefined;
+}

package/lib/runnerSettlement.mjs

@@ -0,0 +1,138 @@
+/** Durable terminal receipts. Execution never repeats to repair a failed
+ * status write; watch/startup replay the same receipt until acknowledged. */
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readdir, readFile, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { glytchHome } from "./registry.mjs";
+import * as defaultApi from "./runnerApi.mjs";
+
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+export const completionDirectory = (project, settings) => join(glytchHome(settings.env), "run-completions", digest(`${project.id}\0${project.path}`));
+const memoryReceipts = new Map();
+const terminal = new Set(["done", "error", "stopped"]);
+
+export async function prepareCompletionStore(project, settings) {
+  const dir = completionDirectory(project, settings);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  // Prove writability before starting work whose receipt we must retain.
+  const probe = join(dir, `.probe-${randomUUID()}`);
+  const handle = await open(probe, "wx", 0o600);
+  await handle.close();
+  await unlink(probe);
+  return dir;
+}
+
+async function writeReceipt(project, runId, patch, settings) {
+  const dir = await prepareCompletionStore(project, settings);
+  const path = join(dir, `${digest(runId)}.json`);
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(JSON.stringify({ projectId: project.id, runId, patch }));
+    await handle.sync();
+  } finally { await handle.close(); }
+  try { await rename(temporary, path); }
+  finally { await unlink(temporary).catch(() => {}); }
+  return path;
+}
+
+const replaying = new Map();
+async function deliver(path, record, settings, log, attempts) {
+  if (replaying.has(path)) return replaying.get(path);
+  const task = (async () => {
+    const api = settings.runnerApi ?? defaultApi;
+    const options = { env: settings.env, fetchImpl: settings.fetchImpl };
+    let last;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      try { last = await api.update({ runId: record.runId, patch: record.patch }, options); }
+      catch (error) { last = { ok: false, error: error.message }; }
+      if (last?.ok) {
+        await unlink(path).catch(error => { if (error.code !== "ENOENT") log(`[${record.runId}] completion acknowledged; local cleanup will retry: ${error.message}`); });
+        return true;
+      }
+      if (attempt + 1 < attempts) await new Promise(resolve => setTimeout(resolve, (settings.completionRetryMs ?? 250) * (attempt + 1)));
+    }
+    log(`[${record.runId}] completion retained for retry: ${last?.error ?? "update was not acknowledged"}`);
+    return false;
+  })();
+  replaying.set(path, task);
+  try { return await task; } finally { replaying.delete(path); }
+}
+
+export async function settleRun(project, runId, patch, settings, log = () => {}) {
+  if (!terminal.has(patch.status)) throw new Error("A terminal receipt requires a terminal status.");
+  const record = { projectId: project.id, runId, patch };
+  const memoryKey = join(completionDirectory(project, settings), digest(runId));
+  memoryReceipts.set(memoryKey, record);
+  let path;
+  try { path = await writeReceipt(project, runId, patch, settings); }
+  catch (error) {
+    // Never replace a completed result with a generic execution error when
+    // local storage fails. Try the server while retaining the original patch.
+    const api = settings.runnerApi ?? defaultApi;
+    const result = await api.update({ runId, patch }, { env: settings.env, fetchImpl: settings.fetchImpl }).catch(() => null);
+    if (result?.ok) {
+      memoryReceipts.delete(memoryKey);
+      return { id: runId, state: patch.status === "done" ? "done" : "failed", patch };
+    }
+    log(`[${runId}] completion retained in memory; local storage is unavailable: ${error.message}`);
+    return { id: runId, state: "pending-sync", patch };
+
+  }
+  memoryReceipts.delete(memoryKey); // The atomically written disk receipt now owns retries.
+  const synced = await deliver(path, record, settings, log, 3);
+  return { id: runId, state: synced ? (patch.status === "done" ? "done" : "failed") : "pending-sync", patch };
+}
+
+export async function flushCompletions(project, settings, log = () => {}) {
+  const dir = completionDirectory(project, settings);
+  let complete = true;
+  for (const [key, record] of [...memoryReceipts]) {
+    if (key !== join(dir, digest(record.runId))) continue;
+    const result = await settleRun(project, record.runId, record.patch, settings, log);
+    if (result.state === "pending-sync") complete = false;
+  }
+  let names;
+  try { names = await readdir(dir); }
+  catch (error) { if (error.code === "ENOENT") return complete; throw error; }
+  for (const name of names.filter(name => /^[a-f0-9]{64}\.json$/.test(name))) {
+    const path = join(dir, name);
+    try {
+      const record = JSON.parse(await readFile(path, "utf8"));
+      if (record.projectId !== project.id || typeof record.runId !== "string" || `${digest(record.runId)}.json` !== name || !terminal.has(record.patch?.status)) throw new Error("Invalid saved completion receipt");
+      if (!(await deliver(path, record, settings, log, 1))) complete = false;
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      complete = false;
+      log(`completion replay deferred: ${error.message}`);
+    }
+  }
+  return complete;
+}
+
+/** Did this run end because `--resume` found no conversation, having done
+ * nothing at all? Unchanged pure function from the file-based runner. */
+export function isMissingConversation(result) {
+  const envelope = result?.envelope;
+  if (!envelope || envelope.is_error !== true) return false;
+  if (Number(envelope.num_turns ?? 0) !== 0) return false;
+  if (Number(envelope.total_cost_usd ?? 0) !== 0) return false;
+  const errors = Array.isArray(envelope.errors) ? envelope.errors : [];
+  return errors.some((e) => typeof e === "string" && e.includes("No conversation found"));
+}
+
+export async function settleMeasuredRun(project, id, patch, settings, log, timing, receipt) {
+  const measurement = timing.snapshot();
+  try { log(`runner.performance ${JSON.stringify(measurement)}`); } catch { /* Diagnostics never prevent settlement. */ }
+  const started = performance.now();
+  const result = await settleRun(project, id, { ...patch, sidecar: { ...(patch.sidecar ?? receipt.sidecar), performance: measurement } }, settings, log);
+  try { log(`runner.delivery ${JSON.stringify({ duration_ms: Math.max(0, Math.round(performance.now() - started)), outcome: result.state === "pending-sync" ? "pending" : "acknowledged" })}`); } catch { /* Optional diagnostics. */ }
+  return result;
+}
+
+export function settleFailedRun(project, id, error, settings, log, timing, receipt) {
+  return settleMeasuredRun(project, id, {
+    status: "error", result: `ERROR\n\nThe runner could not complete this run: ${error.message}\n`,
+    finished_at: new Date().toISOString(),
+  }, settings, log, timing, receipt);
+}

package/lib/runnerWorkspace.mjs

@@ -0,0 +1,162 @@
+// Select a run's working directory and derive resume from the tree that
+// survived. Called after claim and admission; never spawns a child.
+//
+// ROWS VERSION (brief 30 Move 2/2b, 2026-09-11). The file-based runner used
+// to wait for `startSessionOnBoard`'s receipt before this ran, and a refusal
+// here wrote a comment, filed an `endSession` op and a `.result.txt`
+// receipt. There is no more start-and-wait: `claim` IS the start (the run
+// row moves to `status:'running'` the moment it is claimed), so a refusal
+// here has nothing to "close" that was not already open - it writes a
+// comment (when the run has an idea at all) and hands the caller a result
+// whose `patch` flips the row straight to `status:'error'`.
+import { makeWorktree, reuseWorktree, resolveContainedCwd } from "./worktree.mjs";
+import { commentOnAnchor } from "./boardside.mjs";
+import { titleFor } from "./spawn.mjs";
+
+const defaultServices = { makeWorktree, reuseWorktree, commentOnAnchor, titleFor };
+
+/** The preamble's "where you work" sentence for a run that is NOT isolated
+ * (`preambleFor(agent, { workplace })`), the same for every engine.
+ *
+ * QA 2026-10-01 (ticket e2): a folder with no git repo runs IN PLACE
+ * (`makeWorktree` returns `isolated: false`), yet every session was told "You
+ * are in your own git worktree: commit your work on this branch". Claude Code
+ * wrote the file anyway; Codex asked "Where is the git worktree for this
+ * task?" and the run blocked until the person answered. An in-place run is
+ * told so, and told not to ask - there is nothing to find. */
+export const IN_PLACE_WORKPLACE =
+  "You are working directly in the person's folder, not in a git worktree of " +
+  "your own: this folder has no git repo, or isolation was turned off for this " +
+  "prompt. Make your changes in place, in the current directory. There is no " +
+  "worktree or branch to find, so do not ask where one is, and do not commit, " +
+  "merge or switch branches unless the prompt asks you to.\n\n";
+
+/** `context`: `{root, id, request, isResume, session, from, log,
+ * otherRunningCount, updateSidecarEarly, isChat, chatCwd}` - `root` is the
+ * claimed row's project path, `id` its run id. `otherRunningCount()` and
+ * `updateSidecarEarly(patch)` are injected rather than imported so this
+ * module stays free of `runnerApi` vocabulary, the way it was free of
+ * `spawn.mjs`'s file vocabulary before Move 2. `isChat`/`chatCwd` come from
+ * `runner.mjs`'s own chat-turn handling (cwd resolution, minting, the
+ * per-room lock) - this module's only job for one is to build `made` around
+ * the RESOLVED absolute `chatCwd` rather than a worktree (chat turn
+ * difference 2: no worktree is minted per message). Returns `{ok:true,
+ * made, resumeTreeGone, resumeSessionId}` or `{ok:false, patch}` - the
+ * caller writes `patch` through `runnerApi.update`. */
+export async function prepareRequestWorkspace(context, services = defaultServices) {
+  const { root, id, request, isResume, session, from, log, otherRunningCount, updateSidecarEarly, isChat, chatCwd, claimedAt, ownTreePath } = context;
+  const { makeWorktree, reuseWorktree, commentOnAnchor: comment, titleFor: title } = services;
+
+  // A NAMED cwd STAYS IN THE LINKED FOLDER (#324). A chat turn's was
+  // resolved and fenced by the caller (`chatCwd`); every other request's is
+  // fenced here, before anything is made or spawned, the same way.
+  let namedCwd = null;
+  if (!isChat && request.cwd !== undefined) {
+    const resolved = resolveContainedCwd(root, request.cwd);
+    if (!resolved.ok) {
+      const detail =
+        `NOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\n` +
+        `This request names ${String(request.cwd ?? "").trim()} as the directory to run in, and ${resolved.reason}`;
+      log(`[${id}] refused: the request's cwd ${String(request.cwd ?? "").trim()} is outside ${root}`);
+      return { ok: false, patch: { status: "error", result: `ERROR\n\n${detail}\n`, finished_at: new Date().toISOString() } };
+    }
+    namedCwd = resolved.path;
+  }
+
+  if (request.planMode === "draft") {
+    return {
+      ok: true,
+      made: { cwd: namedCwd ?? root, isolated: false, detail: "Read-only planning in the source checkout. No worktree created." },
+      resumeTreeGone: false,
+      resumeSessionId: "",
+    };
+  }
+
+  // THE RECORDED TREE, for a resume and for a new session that names it (a
+  // Codex or opencode note after a done session, review 2026-10-04 D7): the
+  // new session works on the kept branch. A tree that is gone mints a new one.
+  // ONLY THIS IDEA'S OWN TREE (round 3 item 67): `ownTreePath` is the tree
+  // a run of the request's idea made that resolves to the named path, in
+  // the tree's own spelling (runner.mjs, round 4 item 70); null when the
+  // request names another idea's tree or a path no row of this idea made.
+  const wantedRecordedTree = !isChat && !request.cwd && request.useWorktree !== false && Boolean(request.worktreePath);
+  const isOwnTree = wantedRecordedTree && typeof ownTreePath === "string" && ownTreePath !== "";
+  if (wantedRecordedTree && !isOwnTree) log(`[${id}] the named worktree ${request.worktreePath} is not this idea's own; not reused`);
+  const reusedTree = isOwnTree ? await reuseWorktree(root, ownTreePath, log) : null;
+  if (request.recovery === true && wantedRecordedTree && !reusedTree) {
+    return { ok: false, patch: { status: "error", result: "ERROR\n\nThe separate copy is gone.\n", finished_at: new Date().toISOString(), sidecar: { recoveryFailed: true } } };
+  }
+  if (wantedRecordedTree && !isResume && !reusedTree) log(`[${id}] the kept worktree ${request.worktreePath} is gone; this session gets a new one`);
+  const made = isChat
+    ? {
+        // THE RESOLVED ABSOLUTE PATH, never the field as written. The
+        // sidecar records this under `worktreePath` and the app sends it
+        // straight back as the next turn's `cwd`, so a relative first turn
+        // becomes an absolute second one and the conversation stays in one
+        // directory.
+        cwd: chatCwd,
+        isolated: false,
+        detail: `Chat turn: ran in ${chatCwd}, the agent's own chat worktree. No worktree was made for this message and none was reused.`,
+      }
+    : reusedTree
+    ? reusedTree
+    : namedCwd
+      ? { cwd: namedCwd, isolated: false, detail: `Ran in the cwd the request named, ${namedCwd}.` }
+      : request.useWorktree === false
+        ? { cwd: root, isolated: false, detail: `Ran in the linked folder per idea setting (worktree off).` }
+        : await makeWorktree(root, id, log, title(request));
+
+  const wantedIsolation = !isChat && !request.cwd && request.useWorktree !== false;
+  if (wantedIsolation && !made.isolated) {
+    const others = typeof otherRunningCount === "function" ? await otherRunningCount() : 0;
+    if (others > 0) {
+      const detail =
+        `NOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\n` +
+        `This session could not get its own worktree, and ${others} other ` +
+        `session${others === 1 ? " is" : "s are"} running. Falling back to the linked ` +
+        `folder would have put two agents in one working tree, editing the same files ` +
+        `with no branch between them.\n\n${made.detail}\n\n` +
+        `File the request again once they are done, or fix what stopped the worktree.`;
+      const frameId = typeof from === "string" ? from : undefined;
+      if (frameId) {
+        await comment(session, frameId, `Refused before spawning: no worktree, and another session is running\nNothing was spawned and nothing was billed. ${made.detail}`);
+      }
+      log(`[${id}] refused: no worktree while ${others} other session(s) run`);
+      return { ok: false, patch: { status: "error", result: `ERROR\n\n${detail}\n`, finished_at: new Date().toISOString() } };
+    }
+  }
+  // PREP TIME, NAMED (2026-09-21, the claim-to-spawn gap). `claimedAt` is
+  // `runner.mjs`'s own `Date.now()` from the moment `runRequest` started,
+  // right after `claimOne` returned - so this is everything between the
+  // claim and the worktree being ready: the hosted-token check, the repo
+  // lock, `git worktree add`, the node_modules symlink. One number, so the
+  // next silent multi-second gap shows up as a big one rather than nothing.
+  const prepSecs = Number.isFinite(claimedAt) ? ((Date.now() - claimedAt) / 1000).toFixed(1) : null;
+  log(`[${id}] ${made.isolated ? `worktree ${made.branch}` : "NO worktree"}; spawning${prepSecs !== null ? ` (prep ${prepSecs}s)` : ""}`);
+
+  // THE WORKTREE, VISIBLE WHILE THE SESSION IS STILL RUNNING (unchanged
+  // reasoning from the file-based runner, 2026-09-08 - see git history).
+  // Only for a tree that really is one: a run that fell back to the linked
+  // checkout has no worktree of its own, and recording the checkout under
+  // `sidecar.worktreePath` would put Merge and Delete over the linked
+  // folder itself.
+  if (made.isolated && made.path && typeof updateSidecarEarly === "function") {
+    try {
+      await updateSidecarEarly({ worktreePath: made.path, fromId: from });
+      log(`[${id}] early sidecar written: worktree=${made.path}`);
+    } catch (error) {
+      log(`[${id}] early sidecar write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  // A CHAT TURN NEVER ASKED FOR A RECORDED TREE EITHER. Its later requests
+  // DO carry `worktreePath` (the sidecar records the cwd under that name so
+  // the app can hand it straight back), but nothing above reused a tree for
+  // it - without `!isChat` in wantedRecordedTree every message after the first would read as
+  // "the recorded tree is gone" and the conversation would restart on every
+  // turn. Its directory was checked at the top of `runRequest`, which IS the
+  // "can this conversation be reached" question this line exists to ask.
+  const resumeTreeGone = isResume && wantedRecordedTree && !reusedTree;
+  const resumeSessionId = isResume && !resumeTreeGone ? String(request.resumeSessionId).trim() : "";
+  return { ok: true, made, resumeTreeGone, resumeSessionId };
+}

package/lib/serverSweep.mjs

@@ -0,0 +1,90 @@
+// THE DETACHED DEV SERVERS, stopped from ROWS.
+//
+// A browser-frame session starts its dev server detached so the frame on the
+// board outlives the session (2026-09-06, ruling A), and something has to
+// stop it later. Until brief 30 that was lib/sweep.mjs reading a
+// `<id>.server` file the runner mirrored into `.glytch/inbox/spawn/`. Brief 30
+// moved the record onto the run row's own `server` column
+// (runnerCompletion.mjs) and nothing wrote the file any more - so the sweep
+// found nothing, every day, and every detached server ran until the machine
+// rebooted. This module is the rows half that brief left owed
+// ("the sweep, once it moves onto rows", runner.mjs's relaunch comment).
+//
+// Two cases, the same two the file version had, and they are different
+// questions:
+//
+//   - the run FINISHED past the age: its frame is two weeks of history, so
+//     whatever it left listening is stopped with it;
+//   - the WORKTREE is gone but the record survives - the tree was merged or
+//     deleted, or a one-shot run cleaned it up - so the server is serving a
+//     directory that no longer exists. Stopped however young the run is.
+//
+// A run still running is never touched, whatever its age. The record is never
+// trusted on its own: stopRecordedServer refuses a pid whose process does not
+// match what the record describes, so a reused pid is logged and left alone.
+// Either way the row's `server` is cleared afterwards - it stopped, or the
+// process it names is not the one it describes any more, and a record kept in
+// the second case would be re-checked every day for ever.
+
+import { access } from "node:fs/promises";
+import * as runnerApiModule from "./runnerApi.mjs";
+import { stopRecordedServer } from "./devserver.mjs";
+
+/** How long a finished run's server is left listening. The same 14 days
+ * lib/sweep.mjs gives a finished request's files. */
+export const SERVER_SWEEP_AGE_MS = 14 * 86_400_000;
+/** How often a watching folder looks - once a day, like the file sweep. */
+export const SERVER_SWEEP_INTERVAL_MS = 86_400_000;
+
+const pathExists = (path) => access(path).then(() => true, () => false);
+
+/**
+ * Stop every detached dev server this project's finished runs left behind
+ * and no longer need. Returns `{ stopped, left, kept }` as run ids.
+ */
+export async function sweepDetachedServers(project, settings, {
+  now = Date.now(),
+  ageMs = SERVER_SWEEP_AGE_MS,
+  log = () => {},
+  stopServer = stopRecordedServer,
+  exists = pathExists,
+} = {}) {
+  const runnerApi = settings.runnerApi ?? runnerApiModule;
+  const rowsOpts = { env: settings.env, fetchImpl: settings.fetchImpl };
+  const stopped = [];
+  const left = [];
+  const kept = [];
+  const listed = await runnerApi.runs({ projectIds: [project.id] }, rowsOpts);
+  if (!listed.ok) throw new Error(`could not list runs: ${listed.error}`);
+  for (const run of listed.runs ?? []) {
+    const record = run.server;
+    if (!record || !Number.isFinite(Number(record.pid))) continue;
+    if (run.status === "running" || run.status === "pending") {
+      kept.push(run.id);
+      continue;
+    }
+    const finishedAt = typeof run.finished_at === "string" ? Date.parse(run.finished_at) : NaN;
+    const stale = Number.isFinite(finishedAt) && now - finishedAt > ageMs;
+    const treeGone = typeof record.worktreePath === "string" && record.worktreePath !== "" && !(await exists(record.worktreePath));
+    if (!stale && !treeGone) {
+      kept.push(run.id);
+      continue;
+    }
+    let outcome;
+    try {
+      outcome = await stopServer(record);
+    } catch (error) {
+      outcome = { stopped: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+    const why = stale ? "run finished past the age" : "worktree gone";
+    log(
+      outcome.stopped
+        ? `stopped the dev server for ${run.id} (pid ${record.pid}, port ${record.port ?? "unknown"}): ${why}, ${outcome.reason}`
+        : `left the dev server for ${run.id} (pid ${record.pid}) alone: ${outcome.reason}`,
+    );
+    (outcome.stopped ? stopped : left).push(run.id);
+    const cleared = await runnerApi.update({ runId: run.id, patch: { server: null } }, rowsOpts);
+    if (!cleared.ok) log(`[${run.id}] could not clear the dev server record: ${cleared.error}`);
+  }
+  return { stopped, left, kept };
+}