viewable-one 0.0.0-stage → 0.12.1

package/lib/runner.mjs

@@ -0,0 +1,1569 @@
+import { serviceComputerApps, flushComputerApps } from "./computerApps.mjs";
+// The spawn runner, over rows (brief 30 Move 2/2b, 2026-09-11). bridge/
+// SPAWN.md is still the contract for the ENGINE half - the worktree, the
+// wall clock, the resume/retry rules, the money bounds - and the brief's
+// "Move 2 contract" section is the contract for everything this file reads
+// and writes through instead of `.glytch/`: `bridge/lib/runnerApi.mjs`.
+//
+// One claimed row becomes, in this order and no other:
+//
+//   register this machine's projects  ->  claim (exactly once, atomically,
+//   server-side)  ->  spawn the child, streaming its output as events  ->
+//   persist a terminal receipt -> retry its idempotent `update` until acknowledged
+//
+// Claiming the hosted run row is the start receipt; no file acknowledgement.
+//
+// TWO STATES on the board (ruling q-mt9as5a0, unchanged): running, then
+// done (or error, or stopped - the row's own `status` check constraint).
+// Claimed sessions carry renewable ownership leases. Lost ownership stops
+// local execution; expired leases become recoverable errors on the server.
+//
+// MOVE 2b (2026-09-11) FINISHES WHAT MOVE 2 LEFT: a chat-turn row now runs
+// (`isChat`, the per-room lock `activeChatTurnForRoomRows`, the long-lived
+// chat worktree mint - `worktree.mjs`'s `makeChatWorktree`/`resolveChatCwd`,
+// unchanged); `heartbeat`'s `ops` are serviced for `kind:"relaunch"` too
+// (`serviceRowOps`, reading the record off the run row's own `server`
+// column) and `kind:"preview"` (`sharedPreview.mjs`'s
+// `createSharedPreviewService`, tracked across beats from `watch()`'s own
+// loop, since a preview - unlike the other three op kinds - is not
+// one-shot).
+//
+// ONE DEVIATION REMAINS, confirmed rather than merely carried forward:
+// `askedAndNeverReported` (the "asked N questions and reported nothing"
+// line) has no rows equivalent - there is no op that answers "what did this
+// run itself write to the board", only `collect_session`'s "what came
+// back" - and is dropped; see `boardside.mjs`'s own header.
+
+import { randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { access, mkdir, rm, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import * as runnerApiModule from "./runnerApi.mjs";
+import { callTool as hostedCallToolDefault, callRunnerTool } from "./hosted.mjs";
+import { runnerMcpUrlFrom } from "./mcpjson.mjs";
+import { hostedConfig, hostedToken } from "./auth.mjs";
+import { folderRestoreGeneration, removeFolder, withRegistryLock } from "./registry.mjs";
+import { createRowsAnswerPoll } from "./rowsAnswers.mjs";
+import { createPermissionAsker } from "./permissionAsk.mjs";
+import { makeRowEventStreamer } from "./rowsEvents.mjs";
+import {
+  acceptsMessages,
+  agentFor,
+  AGENTS,
+  commandFor,
+  isCodingCli,
+  isPersistentRequest,
+  prepareWorkspace,
+  preambleFor,
+  runnerFor,
+} from "./agents.mjs";
+import { knownBinDirs, resolveAgentBinary } from "./detect.mjs";
+import { getRepoMap, formatRepoPrimer } from "./repomap.mjs";
+import { buildAttemptsSectionFromRows } from "./compose.mjs";
+import { classifyExit } from "./exitClass.mjs";
+import { DEFAULTS, childEnv, runChild, runStreamingChild } from "./child.mjs";
+export { DEFAULTS, childEnv, runChild, runStreamingChild };
+// The runner's own settings, read off the environment - runnerSettings.mjs.
+export { settingsFromEnv } from "./runnerSettings.mjs";
+import { BOARD_DIR } from "./paths.mjs";
+import { imageAttachments, imageInspectionInstruction } from "./imageAttachments.mjs";
+import { claimOne } from "./runnerAdmission.mjs";
+import { checkRequest, isChatTurn, isSignIn, titleFor, wallClockFor } from "./spawn.mjs";
+import { codexLogin } from "./signIn.mjs";
+// Registration and presence (ticket e8 moved them out of this file).
+import { presenceBody, registerAndFindProject } from "./runnerRegister.mjs";
+export { registerAndFindProject };
+import { commentOnAnchor, fromIdOf, formatVerdict } from "./boardside.mjs";
+export { commentOnAnchor, fromIdOf, formatVerdict };
+import { createRunnerPerformance } from "./runnerPerformance.mjs";
+import { completeRequest } from "./runnerCompletion.mjs";
+import { runCodingChecks } from "./codingChecks.mjs";
+import { beforePicture, checkPage } from "./pagePictures.mjs";
+import { startRunLease } from "./runnerLease.mjs";
+import { liveRuns, restartPass, RESTART_RECHECK_MS } from "./restartPass.mjs";
+import { flushCompletions, prepareCompletionStore, settleMeasuredRun, settleFailedRun, isMissingConversation } from "./runnerSettlement.mjs";
+import { IN_PLACE_WORKPLACE, prepareRequestWorkspace } from "./runnerWorkspace.mjs";
+import { chatBoardOf, makeBoardCwd } from "./glytchFolder.mjs";
+import { changedFiles, defaultBranchOf, deleteWorktree, git, makeChatWorktree, mergeWorktree, resolveChatCwd, worktreeBranch, worktreePath, worktreeSummary } from "./worktree.mjs";
+import { relaunchServer, readWorktreeRecord } from "./devserver.mjs";
+import { SERVER_SWEEP_INTERVAL_MS, sweepDetachedServers } from "./serverSweep.mjs";
+import { createSharedPreviewService } from "./sharedPreview.mjs";
+import { createMemberPreviewTunnel } from "./memberPreview.mjs";
+import { beatPace, claimPace, makeHeartbeatHub, makeRegistrar, REGISTER_REFRESH_MS, sleep } from "./runnerPace.mjs";
+import { beatBaseMs } from "./runnerRealtime.mjs";
+// COMPATIBILITY RE-EXPORTS. Nothing under this file's own rows path calls
+// these any more; they stay re-exported because `bridge/test/`'s own tests
+// still reach them through `runner.mjs`, exactly as before Move 2b.
+import { housekeeping } from "./runnerMaintenance.mjs";
+export { housekeeping };
+
+export const newRunnerId = () => `r-${Date.now().toString(36)}-${randomBytes(2).toString("hex")}`;
+
+/** THE session key, minted in exactly one place - unchanged reasoning from
+ * the file-based runner: a run's own row id IS the key `report()`'s
+ * `PM_SESSION_KEY` and `X-Glytch-Session` both use. */
+export const sessionKeyFor = (runId) => String(runId);
+
+export function sessionRecord(runId, request) {
+  return { requestId: runId, key: sessionKeyFor(runId), title: titleFor(request) };
+}
+
+export { isMissingConversation } from "./runnerSettlement.mjs";
+
+// ---------- the per-prompt lock, over rows ----------
+
+const exists = async (path) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Is an unmerged worktree already serving this prompt? Admission reads
+ * this project's run rows, then checks the expected worktree path and the
+ * branch's relationship to main before treating that run as a lock. */
+/** ONE PATH, WHATEVER SPELLING (round 3 item 69): Windows hands a temp dir
+ *  out as an 8.3 short name and the app may send the long one, so the
+ *  worktree comparisons below resolve both sides first. */
+export function samePath(a, b) {
+  const norm = (p) => { try { return realpathSync.native(p); } catch { return resolve(p); } };
+  return typeof a === "string" && typeof b === "string" && a !== "" && b !== "" && norm(a) === norm(b);
+}
+
+/** Besides the lock, `trees` lists every existing worktree a run of this
+ *  prompt made, held or not (an empty error tree, a merged one): a request
+ *  may reuse one of ITS OWN trees only (round 3 item 67). */
+export async function activeWorktreeForPromptRows(root, projectId, promptNodeId, settings, log = () => {}) {
+  const trees = [];
+  if (!promptNodeId) return { locked: false, trees };
+  const runnerApi = settings.runnerApi ?? runnerApiModule;
+  const listed = await runnerApi.runs({ projectIds: [projectId] }, { env: settings.env, fetchImpl: settings.fetchImpl });
+  if (!listed.ok) throw new Error(`Cannot verify prompt ownership: ${listed.error}`);
+  for (const run of listed.runs ?? []) {
+    if (fromIdOf(run.request) !== promptNodeId) continue;
+    const title = titleFor(run.request);
+    const expectedPath = worktreePath(root, run.id, title);
+    if (!(await exists(expectedPath))) continue;
+    trees.push(expectedPath);
+    const branch = worktreeBranch(run.id, title);
+    const resolved = await git(["rev-parse", "--verify", branch], root);
+    if (!resolved.ok) continue;
+    // A RUN THAT NEVER GOT PAST "COULD NOT START" HAS NOTHING TO LOSE
+    // (2026-09-20). `runnerCompletion.mjs` removes a spawn-failed run's
+    // worktree outright; this guard is the backstop for a row written before
+    // that fix, or a removal that failed: an ERROR run whose tree carries
+    // zero commits and zero changed files must not hold the NEXT request on
+    // this prompt hostage (spawn-mua51lhf-96f76b, "spawn claude ENOENT",
+    // kept a "0 commits, 0 files touched" tree and the follow-up was refused).
+    //
+    // 0/0 IS NOT "EMPTY" BY ITSELF (2026-09-21, review): `worktreeSummary`
+    // counts uncommitted edits too (#482), but a git read that failed also
+    // reads as 0, so the same porcelain check `cleanWorktreeImpl` runs
+    // decides before the lock goes; a porcelain check that fails to run is
+    // not evidence the tree is empty.
+    if (run.status === "error") {
+      const summary = await worktreeSummary(expectedPath, root).catch(() => null);
+      if (summary && summary.commits === 0 && summary.files === 0) {
+        const dirty = await git(["status", "--porcelain"], expectedPath);
+        const clean = dirty.ok && dirty.stdout.trim() === "";
+        if (clean) continue;
+      }
+    }
+    // SAME HELPER worktree.mjs's base-selection and merge op use
+    // (defaultBranchOf, 2026-09-21): a master-only repo asks about master.
+    const mainBranch = (await defaultBranchOf(root)) ?? "main";
+    const branchInMain = await git(["merge-base", "--is-ancestor", branch, mainBranch], root);
+    const mainInBranch = await git(["merge-base", "--is-ancestor", mainBranch, branch], root);
+    if (branchInMain.ok && !mainInBranch.ok) continue; // merged into the default branch
+    log(`[lock] prompt ${promptNodeId} is held by worktree ${expectedPath} on branch ${branch}`);
+    return { locked: true, worktreePath: expectedPath, branch, requestId: run.id, trees };
+  }
+  return { locked: false, trees };
+}
+
+/** ROWS VERSION of the file-based `activeChatTurnForRoom` (`spawn.mjs`,
+ * retired brief 30 Move 2b): is a chat turn already live in this room, on
+ * this project? Same question (one live turn per room, because two would
+ * otherwise resume the same Claude Code conversation in the same directory
+ * at once), `runnerApi.runs({..., status:'running'})` in place of scanning
+ * `runningRequests` for an unreceipted claim. `exceptId` is the caller's own
+ * run, which has usually just claimed itself. */
+export async function activeChatTurnForRoomRows(projectId, roomId, exceptId, settings) {
+  const wanted = typeof roomId === "string" ? roomId.trim() : "";
+  if (wanted === "") return null;
+  const runnerApi = settings.runnerApi ?? runnerApiModule;
+  const listed = await runnerApi.runs({ projectIds: [projectId], status: "running" }, { env: settings.env, fetchImpl: settings.fetchImpl });
+  if (!listed.ok) throw new Error(`Cannot verify active chat turns: ${listed.error}`);
+  for (const run of listed.runs ?? []) {
+    if (run.id === exceptId) continue;
+    if (!isChatTurn(run.request)) continue;
+    const its = typeof run.request?.roomId === "string" ? run.request.roomId.trim() : "";
+    if (its === wanted) return { requestId: run.id, roomId: wanted };
+  }
+  return null;
+}
+
+// ---------- the daily spend cap, over rows (item 3) ----------
+
+// ---------- one claimed row, start to finish ----------
+
+/** Claim, spawn, settle - one `runnerApi.update` at the end.
+ *
+ * `project`: `{id, path}`. `run`: the row `claim` handed back - `{id,
+ * request, session_key}`. `settings.enabled` is not consulted here, on
+ * purpose: the caller has to have decided already. */
+export async function runRequest(project, run, settings, log = () => {}) {
+  if (settings.enabled !== true) {
+    throw new Error(
+      "runRequest was called with the runner switched off. Nothing spawns unless PM_SPAWN_RUNNER=on AND a person typed the watch/run command; see bridge/SPAWN.md, \"Money\".",
+    );
+  }
+  if (settings.depth > 0) {
+    throw new Error(
+      `This process was itself spawned by a runner (PM_SPAWN_DEPTH=${settings.depth}), so it may not spawn.`,
+    );
+  }
+
+  const timing = createRunnerPerformance(run);
+  const receipt = { sidecar: { ...run.sidecar } };
+  const lease = startRunLease(project, run, settings, { api: settings.runnerApi ?? runnerApiModule, log });
+  // This process is running it, so the restart pass must never take it for
+  // an orphan (restartPass.mjs).
+  liveRuns.add(run.id);
+  // A claimed run always gets a terminal receipt, including preparation errors.
+  try {
+    await lease.ready;
+    await prepareCompletionStore(project, settings);
+    return await executeRequest(project, run, settings, log, timing, receipt);
+  } catch (error) {
+    if (error.terminalReceipt) throw error;
+    if (settings.leaseLost?.has(run.id)) return { id: run.id, state: "waiting" };
+    log(`[${run.id}] failed: ${error.message}`);
+    return settleFailedRun(project, run.id, error, settings, log, timing, receipt);
+  } finally { lease.stop(); liveRuns.delete(run.id); }
+}
+
+async function executeRequest(project, run, settings, log, timing, receipt) {
+
+  const root = project.path;
+  const id = run.id;
+  const request = run.request ?? {};
+  const runnerApi = settings.runnerApi ?? runnerApiModule;
+  const hostedEnv = settings.env ?? process.env;
+  const rowsOpts = { env: hostedEnv, fetchImpl: settings.fetchImpl };
+  const session = { key: run.session_key ?? sessionKeyFor(id), title: titleFor(request), requestId: id };
+  // CLAIMED, LOGGED (2026-09-21, the claim-to-spawn gap). `runRequest` runs
+  // immediately after `claimOne` hands back a claimed row, in both `watch`'s
+  // loop and `pollOnce` - so this is the earliest point in this file that
+  // can say a run was claimed at all, and `claimedAt` below is what the
+  // "spawning" line's elapsed-time note (`prepareRequestWorkspace`) is
+  // measured against. Before this, everything between the network claim and
+  // the first line `prepareRequestWorkspace` logs was silent - a run seen
+  // claimed at 11:35:57 and "spawning" only at 11:37:00, nothing between.
+  const claimedAt = Date.now();
+  log(`[${id}] claimed: agent ${request.agent ?? "claude"}, project ${root}`);
+  // THE RUN'S OWN BOARD (2026-09-21, board reporting fix). `run` is the row
+  // `claim` handed back (board-runner/store.mjs's `claimOldest`, `select("*")`
+  // on `runs`), which already carries `board_id` - src/runs/api.ts's
+  // RunRequestRow is what wrote it. Sent on to the spawned agent's MCP server
+  // config as `X-Glytch-Board`, next to `X-Glytch-Session`, so board-mcp's
+  // `report` (and every other board_id-less tool) lands on THIS board
+  // instead of guessing the account's most recently touched one
+  // (board-mcp/tools.mjs's `boardFor`). Absent on an older row or a chat
+  // turn with none recorded - `commandFor`/`prepareWorkspace`/`codexBoardArgs`
+  // all treat an empty string the same as "no header", today's behaviour.
+  const boardId = typeof run.board_id === "string" ? run.board_id : "";
+
+  const finish = (patch) => {
+    // Completion rebuilds the sidecar (including removal of a deleted copy).
+    // Retain the capability marker without restoring stale workspace fields.
+    if (receipt.sidecar.restartable === true && patch.sidecar) {
+      patch = { ...patch, sidecar: { ...patch.sidecar, restartable: true } };
+    }
+    return settings.leaseLost?.has(id)
+      ? { id, state: "waiting" }
+      : settleMeasuredRun(project, id, patch, settings, log, timing, receipt);
+  };
+
+  // A CHAT TURN IS A DIFFERENT KIND OF REQUEST (brief 25, ported onto rows
+  // brief 30 Move 2b, 2026-09-11). Absent `kind` means "session", so
+  // everything below this line that is not explicitly guarded by `isChat` is
+  // what it has always been. The five differences, and no others, are
+  // marked `chat turn:` where they happen; bridge/SPAWN.md, "Chat turns", is
+  // the contract - only the DOOR each one reaches through changed (a run row
+  // and its `runnerApi` calls, not a signal file).
+  const isChat = isChatTurn(request);
+
+  const problems = checkRequest(request);
+  if (problems.length > 0) {
+    return finish({ status: "error", result: `ERROR\n\nRefused: ${problems.join("\n")}\n`, finished_at: new Date().toISOString() });
+  }
+
+  // SIGN IN TO CODEX (#482, lib/signIn.mjs): `codex login` opens the sign-in
+  // page in this computer's browser. Then the agents are probed again, so the
+  // app's sign-in box goes as soon as Codex says it is signed in rather than
+  // on the probe's own five-minute clock.
+  if (isSignIn(request)) {
+    log(`[${id}] signing in to ${request.agent}`);
+    const signedIn = await (settings.codexLogin ?? codexLogin)({ env: settings.baseEnv ?? process.env });
+    await settings.refreshAgents?.();
+    return finish({ status: signedIn.ok ? "done" : "error", result: `${signedIn.ok ? "OK" : "ERROR"}\n\n${signedIn.detail}\n`, finished_at: new Date().toISOString() });
+  }
+
+  // A PROJECT FOLDER THAT IS GONE (brief 52 round 1, item 17): one fixed
+  // sentence the app matches for its Pick a folder chip (sessionReplies.ts
+  // FOLDER_GONE); otherwise the spawn fails in a folder that is not there
+  // and the person reads "not installed", the wrong cause.
+  if (!isChat && !(await stat(root).then((s) => s.isDirectory(), () => false))) {
+    log(`[${id}] refused: the project folder ${root} is not on this computer`);
+    return finish({ status: "error", result: `ERROR\n\nNOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\nThe project folder is not on this computer.\n${root}\n`, finished_at: new Date().toISOString() });
+  }
+
+  let referenceImages;
+  try {
+    referenceImages = imageAttachments(request.images);
+  } catch (error) {
+    return finish({ status: "error", result: `ERROR\n\nNOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\n${error.message}\n`, finished_at: new Date().toISOString() });
+  }
+
+  if (request.planMode === "execute") {
+    // ONE LIST QUERY covers both checks below: the matching draft (contract
+    // point 3/5) and single-use consumption (point 4), so a request already
+    // seeded with everything runs() returns pays for one round trip rather
+    // than two.
+    const projectRuns = (await runnerApi.runs({ projectIds: [project.id] }, rowsOpts).catch(() => null))?.runs ?? [];
+    const source = projectRuns.find((r) => r.id === request.approvedPlanFrom);
+    // ENGINE IS PART OF THE BOUND SCOPE (contract point 3/5): absent means
+    // "claude" on both sides, the same default agentFor and checkRequest
+    // already use, so a draft and an execute that both left `agent` unset
+    // still match.
+    const sourceAgent = source?.request?.agent ?? "claude";
+    const requestAgent = request.agent ?? "claude";
+    const samePrompt = source?.request?.planMode === "draft" &&
+      sourceAgent === requestAgent &&
+      fromIdOf(source.request) === fromIdOf(request);
+    if (!samePrompt || source?.status !== "done") {
+      return finish({ status: "error", result: "ERROR\n\nRefused: implementation requires a successful draft run for this same prompt and the same engine.\n", finished_at: new Date().toISOString() });
+    }
+    // SINGLE-USE (contract point 4). The draft's approval is bound to AT
+    // MOST ONE implementation, ever - a duplicate click, a copied execute
+    // request, or a fresh run row spelling the same `approvedPlanFrom` must
+    // all lose to whichever execute run against this draft already got this
+    // far. There is no exclusive-create over rows the way
+    // `<id>.plan-consumed` was on disk (brief 30 Move 2 retired the file
+    // contract this bound to), so this is a scan for an earlier claimed row
+    // rather than a race-proof claim of its own - the same trade-off
+    // `activeChatTurnForRoomRows` above already accepts for its per-room
+    // lock, and for the same reason: the window between the scan and this
+    // run's own claim is a process's worth of code, not a poll interval.
+    const already = projectRuns.find((r) => {
+      // Continued/recovered segments carry on the same approved implementation.
+      // `continues` keeps its root session key across resumes; derived run ids
+      // also identify ancestors when an older request lacks that chain key.
+      const sameChain = (typeof request.continues === "string" && request.continues.length > 0 &&
+        (request.continues === r.id || request.continues === r.session_key || request.continues === r.request?.continues)) ||
+        id.startsWith(`${r.id}-r`);
+      return r.id !== id && !sameChain && r.request?.planMode === "execute" &&
+        r.request?.approvedPlanFrom === request.approvedPlanFrom &&
+        (r.claimed_by != null || r.status !== "pending");
+    });
+    if (already) {
+      return finish({ status: "error", result: "ERROR\n\nRefused: this approved plan has already started an implementation. Draft and approve a new plan to try again.\n", finished_at: new Date().toISOString() });
+    }
+  }
+
+  // ---------- chat turn: the things only the disk (or the room) can answer ----------
+  // checkRequest (pure) has said `cwd` and `roomId` are there. Each check
+  // here refuses in words a person reads in the run's result, never throws.
+  let chatCwd = null;
+  if (isChat) {
+    // WHERE IT RUNS: refused if it escapes the folder (Write, Edit and Bash).
+    const resolvedCwd = resolveChatCwd(root, request.cwd);
+    if (!resolvedCwd.ok) {
+      const detail =
+        `NOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\n` +
+        `This chat turn names ${String(request.cwd ?? "").trim()} as the directory to ` +
+        `run in, and ${resolvedCwd.reason}`;
+      log(`[${id}] refused: the chat turn's cwd ${String(request.cwd ?? "").trim()} is outside ${root}`);
+      return finish({ status: "error", result: `ERROR\n\n${detail}\n`, finished_at: new Date().toISOString() });
+    }
+    // A BOARD'S SUBFOLDER (glytchFolder.mjs) is made inside the chat tree.
+    const board = request.boardFolder === undefined ? null : chatBoardOf(root, resolvedCwd.path, request.boardFolder);
+    chatCwd = board?.tree ?? resolvedCwd.path;
+    // THE DIRECTORY IS THE CONVERSATION (brief 25 difference 2): no worktree
+    // PER MESSAGE and no fallback to the linked checkout. `mintIfMissing`
+    // (ruling 1) cuts the folder's one long-lived chat worktree, once.
+    let isDir = false;
+    try { isDir = (await stat(chatCwd)).isDirectory(); } catch { isDir = false; }
+    if (!isDir && request.mintIfMissing === true) {
+      const minted = await makeChatWorktree(root, chatCwd, log);
+      if (!minted.ok) {
+        const detail = `NOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\n${minted.reason}`;
+        log(`[${id}] refused: the chat worktree ${chatCwd} could not be made`);
+        return finish({ status: "error", result: `ERROR\n\n${detail}\n`, finished_at: new Date().toISOString() });
+      }
+      log(`[${id}] ${minted.detail}`);
+      isDir = true;
+    }
+    if (!isDir) {
+      const detail =
+        `NOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\n` +
+        `This chat turn names ${chatCwd} as the directory to run in, and there is no ` +
+        `directory there. A chat turn never mints a worktree: the directory IS which ` +
+        `conversation this is, and falling back to the linked folder would put a chat agent ` +
+        `in the checkout you are working in.\n\n` +
+        `Make the directory (the chat worktree for this agent) and send the message again.`;
+      log(`[${id}] refused: the chat turn's cwd ${chatCwd} is not a directory`);
+      return finish({ status: "error", result: `ERROR\n\n${detail}\n`, finished_at: new Date().toISOString() });
+    }
+    if (board) {
+      const sub = await makeBoardCwd(root, chatCwd, board.name);
+      if (!sub.ok) {
+        log(`[${id}] refused: ${sub.reason}`);
+        return finish({ status: "error", result: `ERROR\n\nNOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\n${sub.reason}\n`, finished_at: new Date().toISOString() });
+      }
+      chatCwd = sub.path;
+    }
+    // AND THE ENGINE HAS TO BE A CODING CLI THIS BRIDGE RUNS (agents.mjs).
+    if (request.agent !== undefined && !isCodingCli(request.agent)) {
+      const detail =
+        `NOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\n` +
+        `This chat turn names the engine "${request.agent}", and this bridge has no such ` +
+        `coding CLI. Answering on another engine would tell you that you are talking to ` +
+        `"${request.agent}" when you are not.`;
+      log(`[${id}] refused: "${request.agent}" is not a coding CLI this bridge runs`);
+      return finish({ status: "error", result: `ERROR\n\n${detail}\n`, finished_at: new Date().toISOString() });
+    }
+    // difference 4: THE PER-ROOM LOCK, not the per-prompt one below.
+    const roomId = String(request.roomId).trim();
+    const live = await activeChatTurnForRoomRows(project.id, roomId, id, settings);
+    if (live) {
+      const detail =
+        `NOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\n` +
+        `A chat turn is already running in room ${roomId} (run ${live.requestId}). ` +
+        `One live turn per room: both would resume the same Claude Code conversation in the ` +
+        `same directory at the same time, and a conversation is one thread.\n\n` +
+        `Wait for that turn to finish, or stop it, then send this message again.`;
+      log(`[${id}] refused: room ${roomId} already has a live turn (${live.requestId})`);
+      return finish({ status: "error", result: `ERROR\n\n${detail}\n`, finished_at: new Date().toISOString() });
+    }
+  }
+
+  const isResume = typeof request.resumeSessionId === "string" && request.resumeSessionId.trim() !== "";
+  // chat turn, difference 4 (cont.): no idea behind it, so no per-prompt lock.
+  const from = isChat ? undefined : fromIdOf(request);
+  // THE ONE TREE A REQUEST MAY NAME: one of this idea's own (round 3 item 67).
+  let ownTreePath = null;
+  if (from) {
+    const lock = await activeWorktreeForPromptRows(root, project.id, from, settings, log);
+    // The tree's own spelling goes down (round 4 item 70): reuseWorktree
+    // compares text, and the request may say /var for a /private/var tree.
+    ownTreePath = lock.trees.find((tree) => samePath(tree, request.worktreePath)) ?? null;
+    if (lock.locked) {
+      // A resume, or a new session (Codex, opencode) naming the kept tree
+      // (review 2026-10-04, D7): both run IN that tree, so neither is a second one.
+      const isOwnTree = samePath(request.worktreePath, lock.worktreePath);
+      if (!isOwnTree) {
+        const detail =
+          `Refused: this prompt already has an active session.\n\n` +
+          `Worktree ${lock.worktreePath} on branch ${lock.branch} (run ${lock.requestId}) ` +
+          `is still in progress for prompt ${from}. Only one session per prompt is allowed ` +
+          `while a worktree exists and its branch is not merged into main.\n\n` +
+          `Merge or delete the existing worktree first, then file a new request.`;
+        log(`[${id}] refused: prompt ${from} is locked by ${lock.worktreePath}`);
+        return finish({ status: "error", result: `ERROR\n\n${detail}\n`, finished_at: new Date().toISOString() });
+      }
+      log(`[${id}] ${isResume ? "resume" : "new session"} into own worktree ${lock.worktreePath}, lock exempted`);
+    }
+  }
+
+  const agent = agentFor(request.agent);
+
+  // CAN THIS ENGINE EVEN BE SPAWNED ON THIS MACHINE, settled BEFORE a
+  // worktree is minted (2026-09-20): the daemon runs with its service's
+  // PATH, so a `claude` that answers from Terminal can still ENOENT here.
+  // `resolveAgentBinary` (detect.mjs, what `glytch doctor` probes through)
+  // tries the daemon's PATH, the well-known install directories, then a
+  // login shell's `command -v`, and only then refuses in words a person can
+  // act on, before prepareRequestWorkspace has minted anything.
+  // SKIPPED WHEN `settings.claudeBin` IS SET: the test/CI override already
+  // names a known-runnable binary (runner.test.mjs sets process.execPath).
+  let resolvedBinPath;
+  if (settings.claudeBin === undefined) {
+    const spec = AGENTS[agent];
+    const env = settings.env ?? process.env;
+    const platform = settings.platform ?? process.platform;
+    const wantedBin = env[spec.binEnv]?.trim() || spec.bin;
+    const resolvedBin = await resolveAgentBinary(wantedBin, { env, platform });
+    if (!resolvedBin.found) {
+      const machine = settings.host ?? "your computer";
+      const detail =
+        `NOTHING WAS SPAWNED AND NOTHING WAS BILLED.\n\n` +
+        `${spec.label} is not installed on ${machine}, or the runner cannot find it.\n\n` +
+        `Open a terminal and run \`${wantedBin} --version\`; if that works, restart the runner: ` +
+        `\`viewable stop\`, then \`viewable init --yes\` in the project folder. This lookup is ` +
+        `remembered until the runner restarts, so installing ${spec.label} after this refusal ` +
+        `changes nothing until you do.\n\n` +
+        `[Technical: spawn ${wantedBin} ENOENT. Searched this process's own PATH, ` +
+        `${knownBinDirs({ env, platform }).join(", ") || "no known install directories on this platform"}` +
+        `${env.SHELL ? `, and a login shell (${env.SHELL} -lc 'command -v ${wantedBin}')` : ", and no login shell ($SHELL is not set in this environment)"}.]`;
+      log(`[${id}] refused: could not resolve ${wantedBin} to a runnable path on your computer`);
+      return finish({ status: "error", result: `ERROR\n\n${detail}\n`, finished_at: new Date().toISOString() });
+    }
+    resolvedBinPath = resolvedBin.path;
+  }
+
+  const hostedBoard = await hostedConfig({ env: hostedEnv });
+  const childMcpUrl = runnerMcpUrlFrom(hostedBoard, hostedEnv);
+  // The runner's permission checks and collect_session (including the final
+  // sweep) use the same direct endpoint as its child. Keep the hosted
+  // transport's refresh/deadline/cancellation logic; only reroute MCP posts,
+  // never OAuth discovery or refresh requests made through the same fetch.
+  const hostedCallTool = settings.hostedCallTool ?? ((name, args, options) => hostedCallToolDefault(name, args, {
+    ...options,
+    mcpUrl: childMcpUrl, fetchImpl: settings.fetchImpl,
+  }));
+  const boardToken = await hostedToken({ env: hostedEnv, log });
+  if (!boardToken) {
+    log(`[${id}] not signed in to the hosted board (viewable login) and no VIEWABLE_BOARD_TOKEN - this session's board tools will have nothing to authenticate with`);
+  }
+  const isPersistent = isPersistentRequest(request);
+  const useStreaming = request.planMode !== "draft" && acceptsMessages(request);
+  const maxMs = wallClockFor(request);
+  const otherRunningCount = async () => {
+    const listed = await runnerApi.runs({ projectIds: [project.id], status: "running" }, rowsOpts);
+    if (!listed.ok) throw new Error(`Cannot verify competing runs: ${listed.error}`);
+    return (listed.runs ?? []).filter((r) => r.id !== id).length;
+  };
+  const workspace = await prepareRequestWorkspace({
+    root, id, request, isResume, session, from, log, isChat, chatCwd, claimedAt, ownTreePath,
+    otherRunningCount,
+    updateSidecarEarly: (sidecar) => {
+      // Settlement replaces the hosted JSON column; preserve workspace controls
+      // even if setup later throws or Stop arrives before the child launches.
+      receipt.sidecar = { ...receipt.sidecar, ...sidecar };
+      if (agentFor(request.agent) === "claude") {
+        receipt.sidecar.claudeSessionId = request.resumeSessionId ?? request.sessionId;
+        receipt.sidecar.restartable = true;
+      }
+      return runnerApi.update({ runId: id, patch: { sidecar: receipt.sidecar } }, rowsOpts);
+    },
+  });
+  if (!workspace.ok) return finish(workspace.patch);
+  const { made, resumeTreeGone, resumeSessionId } = workspace;
+
+  const TREE_GONE_NOTE =
+    `[From the runner] The earlier conversation for this prompt could not be resumed: ` +
+    `the worktree it lived in (${request.worktreePath}) is gone, and Claude Code keeps ` +
+    `conversations per working directory. This is a FRESH session in a new worktree, with ` +
+    `none of that history. Work from the prompt above and from the repository.`;
+  const NOT_FOUND_NOTE =
+    `[From the runner] The earlier conversation for this prompt could not be resumed: its ` +
+    `worktree is still here, but Claude Code has no record of session ` +
+    `${String(request.resumeSessionId ?? "").trim()} in it. This is a FRESH session in that ` +
+    `same worktree, with none of that history. Work from the prompt above, and from what is ` +
+    `already committed on this branch.`;
+  if (resumeTreeGone) {
+    log(`[${id}] the recorded worktree ${request.worktreePath} is gone; starting a FRESH session instead of resuming ${String(request.resumeSessionId).trim()}`);
+  }
+
+  const planRun = async ({ resumeId, note, fixing = false }) => {
+    const fresh = resumeId === "";
+    // chat turn, difference 3: NEITHER, EVER. Both the primer and the
+    // attempts log exist to save a FRESH session from rediscovering what an
+    // earlier one already learned; a chat turn is either the first message
+    // of a conversation or a resume of one, and there is no idea
+    // behind it to have attempted anything.
+    const repoMap = fresh && !isChat ? await getRepoMap(root, log) : null;
+    const attemptsSection = fresh && !isChat && from
+      ? await buildAttemptsSectionFromRows(project.id, from, id, { runnerApi, env: hostedEnv, log })
+      : null;
+    const repoPrimer = formatRepoPrimer(repoMap, attemptsSection ? attemptsSection.length : 0);
+    // chat turn, difference 1: NO PREAMBLE. Every sentence of it is about an
+    // idea on the board he is not looking at - "call report before you
+    // finish" - and a chat turn has neither: what it is told is the app's to
+    // compose (persona, the room's context, his message).
+    let text = request.planMode === "draft"
+      ? `Investigate the request using read-only research, then return an actionable implementation plan in your final response. Structure the response as a report: keep resolved or contextual findings in their own sections; put actionable work under a \`## Implementation plan\` heading with one \`### Step N: ...\` or \`### Issue X: ...\` heading per top-level item; put numbered substeps under a \`**Steps:**\` label; and label checks and open decisions clearly. Do not implement anything, use tools to modify files, or ask for permission to implement. The human will edit and approve or reject your final plan on the board.\n\n${String(request.prompt)}`
+      : `${isChat ? "" : preambleFor(agent, { ...(made.isolated ? {} : { workplace: IN_PLACE_WORKPLACE }), computerApps: request.computerApps === true })}${String(request.prompt)}`;
+    if (request.planMode === "execute") text += `\n\nHUMAN-APPROVED IMPLEMENTATION PLAN\nFollow this exact plan, including the human's edits. Ask the human about any material scope change before implementing it.\n\n${request.approvedPlan}`;
+    if (note) text = `${text}\n\n${note}`;
+    if (repoPrimer) text = `${text}\n\n${repoPrimer}`;
+    if (attemptsSection) text = `${text}\n\n${attemptsSection}`;
+    if (referenceImages.length > 0) {
+      text = `${imageInspectionInstruction(referenceImages.length, request.planMode).trim()}\n\n${text}`;
+    }
+    const resolved = commandFor(agent, settings.env ?? process.env, {
+      planMode: request.planMode,
+      model: request.model,
+      effort: request.effort,
+      sessionId: fixing ? undefined : request.sessionId,
+      resumeSessionId: resumeId,
+      streaming: useStreaming,
+      // ASK IN THE IDEA (#478): with a board to ask on, anything outside the
+      // usual list becomes a question in the idea instead of a silent refusal.
+      // Drafts are read-only; commandFor drops the ask for them.
+      askPermissions: Boolean(boardToken),
+      webSearch: request.webSearch === true,
+      boardUrl: childMcpUrl,
+      boardToken,
+      sessionKey: session.key,
+      boardId,
+      // The person's own apps (#481): only an explicit true from the app,
+      // which sends it when this person turned the switch on for this agent.
+      computerApps: request.computerApps === true,
+    });
+    const chosen = settings.claudeBin !== undefined
+      ? { ...resolved, bin: settings.claudeBin, args: request.planMode === "draft" ? resolved.args : settings.claudeArgs ?? resolved.args }
+      // THE RESOLVED PATH, NOT THE BARE NAME: the check above already found
+      // where this binary actually runs FROM - `spec.bin` unchanged when it
+      // was already on this process's own PATH, an absolute path when it
+      // took a known install directory or a login shell to find. Handing
+      // `spawn` the resolved path means it never repeats a PATH search this
+      // process's own (possibly narrower) PATH would have failed anyway.
+      : { ...resolved, bin: resolvedBinPath ?? resolved.bin };
+    for (const what of chosen.ignored ?? []) log(`[${id}] ignoring ${what}`);
+    // `brief` is what the person typed, on its own - the adapters echo it
+    // into the transcript instead of the preamble-wrapped `prompt`.
+    return { prompt: text, brief: String(request.prompt), chosen, args: chosen.args.map((a) => a.replaceAll("{prompt}", () => text)) };
+  };
+
+  const plan = await planRun({ resumeId: resumeSessionId, note: resumeTreeGone ? TREE_GONE_NOTE : null });
+  const { prompt, chosen, args } = plan;
+  let resumeNotFound = false;
+
+  let prepared = { wrote: null };
+  try {
+    prepared = await prepareWorkspace(agent, { mcpUrl: childMcpUrl, token: boardToken, sessionKey: session.key, boardId });
+  } catch (error) {
+    log(`[${id}] could not prepare the board config: ${error?.message ?? error}`);
+  }
+
+  // LOG STREAMING, over run_events (item 3). Uncapped live; the cap shows up
+  // in the final flush - see rowsEvents.mjs's own header for why.
+  const streamer = makeRowEventStreamer({
+    send: (events) => runnerApi.events({ runId: id, events }, rowsOpts),
+    log,
+  });
+  const flushTimer = setInterval(() => void streamer.tick(), settings.logFlushMs ?? 3000);
+  if (flushTimer.unref) flushTimer.unref();
+  let imagesDir = null;
+  let rowsPoll = null;
+  try {
+  const onChunk = (chunk) => { if (chunk.length > 0) timing.output(); streamer.onChunk(chunk); };
+
+  const childEnvObj = childEnv(settings.baseEnv ?? process.env, { root, session, depth: settings.depth, fromId: from });
+  if (boardToken) childEnvObj.PM_BOARD_TOKEN = boardToken;
+  Object.assign(childEnvObj, prepared.env ?? {});
+
+  // STOP, from the runner's own heartbeat beat (item 5: heartbeat's `stops`
+  // replaces the `.stop` file). `settings.stopped` is a Set the watch loop
+  // keeps current; a run started outside the watch loop (a test, `pollOnce`)
+  // simply never sees anything in it, which is the same as "never asked to
+  // stop".
+  const stopCheck = async () => Boolean(settings.stopped?.has(id));
+
+  rowsPoll = boardToken
+    ? createRowsAnswerPoll({ callTool: hostedCallTool, sessionKey: session.key, env: hostedEnv, log, realtime: settings.realtime })
+    : null;
+  const answerPoll = rowsPoll ? rowsPoll.poll : undefined;
+  // Who answers "can I do this?" for a run on this computer. Only for a run
+  // that can wait for a person: streaming Claude and non-draft Codex, with a
+  // board to file the question on. A draft never asks (it stays read-only).
+  const askPermission = boardToken && request.planMode !== "draft" && (useStreaming || agentFor(agent) === "codex")
+    ? createPermissionAsker({
+      folder: root, agentLabel: AGENTS[agentFor(agent)]?.label ?? "The agent", session, fromId: from, env: hostedEnv,
+      callTool: hostedCallTool, poll: rowsPoll, log: (message) => log(`[${id}] ${message}`),
+      pollMs: settings.permissionPollMs ?? 2000,
+    })
+    : undefined;
+
+  let imageSuffix = "";
+  const promptIsAnArgument = args.some((a) => typeof a === "string" && a.includes(prompt));
+  const protocolImages = useStreaming || ["acp", "codex-app-server"].includes(chosen.spec?.protocol);
+  if (referenceImages.length > 0 && !protocolImages) {
+    if (!promptIsAnArgument) {
+      clearInterval(flushTimer);
+      throw new Error("Reference images cannot be delivered by this command: it has no prompt argument or image transport. Restore the engine's standard command and try again.");
+    }
+    const imgDir = join(root, BOARD_DIR, "images", id);
+    imagesDir = imgDir;
+    try {
+      await mkdir(imgDir, { recursive: true });
+      const paths = [];
+      for (const [index, image] of referenceImages.entries()) {
+        const filePath = join(imgDir, `context-${index}.${image.extension}`);
+        await writeFile(filePath, image.bytes);
+        paths.push(filePath);
+      }
+      imageSuffix = `\n\n[${paths.length} screenshot${paths.length === 1 ? "" : "s"} from the idea's pictures, saved as files. Open each with your image-capable Read/view tool:${paths.map((p) => `\n  ${p}`).join("")}]`;
+      log(`[${id}] wrote all ${paths.length} reference image(s) to ${imgDir}`);
+    } catch (error) {
+      clearInterval(flushTimer);
+      throw new Error(`Reference images could not be prepared; no coding session was started: ${error.message}`);
+    }
+  }
+
+  const makeRunOpts = (p, extra = {}) => {
+    const renderedPrompt = p.prompt + imageSuffix;
+    const withImages = imageSuffix
+      ? p.args.map((a) => (typeof a === "string" && a.includes(p.prompt) ? a.replace(p.prompt, () => p.prompt + imageSuffix) : a))
+      : p.args;
+    const platform = settings.platform ?? process.platform;
+    const promptArgIndex = p.chosen.args.findIndex((arg, index) => arg === "{prompt}" && ["-p", "--print"].includes(p.chosen.args[index - 1]));
+    const promptOnStdin = platform === "win32" && agentFor(agent) === "claude" && !useStreaming && promptArgIndex >= 0;
+    const childArgs = promptOnStdin ? withImages.filter((_arg, index) => index !== promptArgIndex) : withImages;
+    const base = {
+      bin: p.chosen.bin,
+      args: childArgs,
+      brief: p.brief,
+      cwd: made.cwd,
+      env: childEnvObj,
+      maxMs,
+      maxLogBytes: settings.maxLogBytes ?? DEFAULTS.maxLogBytes,
+      killGraceMs: settings.killGraceMs ?? DEFAULTS.killGraceMs,
+      stallMs: settings.stallMs ?? DEFAULTS.stallMs,
+      onChunk,
+      onSession: async (threadId) => {
+        receipt.sidecar = { ...receipt.sidecar, codexThreadId: threadId, restartable: true };
+        try {
+          const saved = await runnerApi.update({ runId: id, patch: { sidecar: receipt.sidecar } }, rowsOpts);
+          if (!saved.ok) log(`[${id}] could not record the conversation: ${saved.error}`);
+        } catch (error) {
+          log(`[${id}] could not record the conversation: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      },
+      platform,
+      ...(promptOnStdin ? { input: renderedPrompt } : {}),
+      acp: p.chosen.acp ?? null,
+      codex: p.chosen.codex ?? null,
+      askPermission,
+      log: (message) => log(`[${id}] ${message}`),
+    };
+    return useStreaming
+      ? { ...base, prompt: renderedPrompt, images: request.images, stopCheck, answerPoll, answerPollMs: settings.rowsPollMs ?? 5000, ...extra }
+      : { ...base, prompt: renderedPrompt, images: request.images, stopCheck, ...extra };
+  };
+  const runOpts = makeRunOpts(plan);
+  const runFn = runnerFor(agent, useStreaming);
+
+  if (settings.stopped?.has(id)) return await finish({ status: "stopped", result: settings.leaseLost?.has(id) ? "STOPPED\n\nRunner connection expired before the process was started.\n" : "STOPPED\n\nStopped by user request before the process was started.\n", finished_at: new Date().toISOString() });
+  timing.launched();
+  const firstRunStartedAt = Date.now();
+  const firstTry = await runFn(runOpts);
+  if (request.recovery === true && (isMissingConversation(firstTry) || (!firstTry.ok && !firstTry.sawAssistant))) {
+    clearInterval(flushTimer);
+    await streamer.settle(firstTry.log ?? "", { dropped: firstTry.dropped ?? 0 });
+    return finish({ status: "error", result: "ERROR\n\nThe conversation could not carry on.\n", finished_at: new Date().toISOString(), sidecar: { ...receipt.sidecar, recoveryFailed: true } });
+  }
+  const exitClass = classifyExit(firstTry.code, firstTry.signal);
+  const remainingBudget = () => Math.max(1000, maxMs - (Date.now() - firstRunStartedAt));
+
+  let outcome;
+  let sessionIdSource = null;
+  if (resumeSessionId !== "" && isMissingConversation(firstTry)) {
+    log(`[${id}] the conversation ${resumeSessionId} was not found in ${made.cwd} ($0.00, 0 turns - nothing was spent); retrying once as a FRESH session there`);
+    resumeNotFound = true;
+    const freshPlan = await planRun({ resumeId: "", note: NOT_FOUND_NOTE });
+    const resumeLog = firstTry.log ?? "";
+    outcome = await runFn(makeRunOpts(freshPlan, { maxMs: remainingBudget() }));
+    sessionIdSource = outcome.log ?? "";
+    outcome.log = `=== Resume attempt (no conversation found; $0.00, 0 turns) ===\n${resumeLog}\n\n=== Fresh session in the same worktree ===\n${outcome.log ?? ""}`;
+    outcome.retried = true;
+    outcome.firstCrashClass = "the resumed conversation was not found";
+  } else if (exitClass.isCrash && !firstTry.sawAssistant && !firstTry.finished) {
+    log(`[${id}] first run ${exitClass.description}, no output streamed; retrying once`);
+    outcome = await runFn({ ...runOpts, maxMs: remainingBudget() });
+    if (firstTry.log) {
+      outcome.log = `=== First attempt (${exitClass.description}) ===\n${firstTry.log}\n\n=== Retry ===\n${outcome.log ?? ""}`;
+      outcome.retried = true;
+      outcome.firstCrashClass = exitClass.description;
+    }
+  } else {
+    outcome = firstTry;
+  }
+
+  // Checking is part of this run, before its one closing reply and cleanup.
+  // Drafts and chat turns must never start scripts or an automatic edit.
+  if (outcome.ok && !isChat && request.planMode !== "draft" && !await stopCheck()) {
+    const deadline = firstRunStartedAt + maxMs;
+    const checkOptions = {
+      cwd: made.cwd, env: childEnvObj, deadline, stopCheck,
+      platform: settings.platform ?? process.platform,
+      killGraceMs: settings.killGraceMs ?? DEFAULTS.killGraceMs,
+      onChunk,
+    };
+    // The page check and After come from the copy, only when the run changed
+    // a screen (#2194). A run with no copy has no list of what it changed.
+    const pageOptions = {
+      cwd: made.cwd, folder: root, env: childEnvObj, baseEnv: settings.baseEnv ?? process.env,
+      platform: checkOptions.platform, deadline, stopCheck, killGraceMs: checkOptions.killGraceMs,
+      ...(settings.browser !== undefined ? { browser: settings.browser } : {}),
+    };
+    const checkAll = async () => {
+      const ran = await runCodingChecks(checkOptions);
+      const paged = made.isolated && !ran.stopped && settings.pictures !== false
+        ? await checkPage({ ...pageOptions, files: await changedFiles(made.cwd, root) }) : null;
+      if (!paged) return { ...ran, paged };
+      return {
+        ...ran, paged, stopped: ran.stopped || Boolean(paged.stopped),
+        checks: [...ran.checks, paged.check],
+        failures: paged.failure ? [...ran.failures, paged.failure] : ran.failures,
+      };
+    };
+    let checked = await checkAll();
+    outcome.log = (outcome.log ?? "") + checked.log;
+    let fixAttempted = false;
+    if (checked.failures.length && !checked.stopped && !await stopCheck() && Date.now() < deadline) {
+      const fixPlan = await planRun({
+        resumeId: outcome.codexThreadId ?? outcome.envelope?.session_id ?? "",
+        fixing: true,
+        note: `The folder's checks failed after your work. Try ONE fix in this same folder. Reproduce the failed check, fix the cause without removing or weakening checks, and leave checking to the runner when you finish. Do not start another automatic attempt.\n\n${checked.failures.join("\n\n")}`,
+      });
+      if (!await stopCheck() && Date.now() < deadline) {
+        fixAttempted = true;
+        const step = `${JSON.stringify({ type: "assistant", message: { content: [{ type: "text", text: "Coding is trying one fix." }] } })}\n`;
+        onChunk(step);
+        outcome.log = (outcome.log ?? "") + step;
+        const fixed = await runFn(makeRunOpts(fixPlan, { maxMs: deadline - Date.now() }));
+        const combinedLog = (outcome.log ?? "") + (fixed.log ?? "");
+        // A repair failure is a failed check, not a crash of the finished run.
+        // Keep its closing reply, and always verify the files left behind.
+        if (fixed.ok) {
+          outcome = { ...outcome, ...fixed };
+          sessionIdSource = fixed.log ?? "";
+        }
+        outcome.log = combinedLog;
+        outcome.stoppedByUser ||= fixed.stoppedByUser;
+        const previous = checked.checks;
+        checked = await checkAll();
+        outcome.log += checked.log;
+        checked.checks = checked.checks.map((check) => check.status === "skipped" && previous.some((p) => p.kind === check.kind && p.status === "failed")
+          ? { ...check, status: "failed", failed: 1 } : check);
+      }
+    }
+    outcome.stoppedByUser ||= checked.stopped;
+    // Before is the folder's page, which the run has not touched yet.
+    const pictures = checked.paged?.after && !checked.stopped
+      ? await beforePicture({ ...pageOptions, page: checked.paged.page, after: checked.paged.after, browser: checked.paged.browser })
+      : {};
+    outcome.result = { checks: checked.checks, fixAttempted, ...pictures };
+    if (checked.paged?.note) outcome.picturesNote = checked.paged.note;
+  }
+
+  timing.exited();
+  clearInterval(flushTimer);
+  await streamer.settle(outcome.log ?? "", { dropped: outcome.dropped ?? 0 });
+  if (imagesDir) await rm(imagesDir, { recursive: true, force: true }).catch(() => {});
+
+  // A lease expiry is an interruption, not a human Stop or an ending.
+  // Leave result null for the reaper/restart pass, and keep the copy intact.
+  if (settings.leaseLost?.has(id)) return { id, state: "waiting" };
+
+  const completed = await completeRequest({
+    root, id, outcome, made, isPersistent, isChat, sessionIdSource, from, session, maxMs, agent,
+    readStopRequested: () => Boolean(settings.stopped?.has(id)) || outcome.stoppedByUser === true,
+    resumeTreeGone, resumeNotFound, request, log,
+    rowsPoll, hostedCallTool, hostedEnv,
+    resumeFn: (args, opts) => runnerApi.resume(args, { ...rowsOpts, ...opts }),
+  });
+  return await finish(completed.patch);
+  } finally {
+    rowsPoll?.close();
+    clearInterval(flushTimer);
+    if (imagesDir) await rm(imagesDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+// ---------- forget: this folder leaves the machine (2026-09-12, ruling 3) ----------
+
+/**
+ * Act on a `forget` op for THIS project, if this beat's heartbeat carried one.
+ * Returns true when it did, which tells `watch()` to stop beating: it has
+ * just unregistered the folder it was watching.
+ *
+ * The whole gesture is three steps and this is the middle one. A person
+ * clicks Remove on a row in the Project panel; the app raises `forgotten_at`
+ * on that `runner_projects` row, which hides it from the picker at once; the
+ * next heartbeat hands this daemon the op; and the row only actually goes
+ * once this call has acknowledged it. That ordering is what makes a forget
+ * survive a daemon that was asleep at the time - the signal is re-surfaced
+ * every beat until it is answered.
+ *
+ * IT IS NOT `opTake`n. There is no `run_ops` row to take: a forget belongs to
+ * a project, not to a run, and board-runner synthesises the op straight off
+ * the column (see supabase/functions/board-runner/store.mjs's
+ * `forgetSignals`). Acting and then acknowledging is the whole protocol.
+ *
+ * THE REGISTRY FIRST, THE ACK SECOND, and the order is load-bearing. Dropping
+ * the folder from `~/.glytch/folders.json` is what stops the NEXT beat's
+ * `registerAndFindProject` naming it again - register upserts on
+ * (user, host, path), so a row deleted while the folder is still registered
+ * would simply be recreated on the following beat, and the person's Remove
+ * would visibly undo itself. It is also what stops the watcher: multiwatch
+ * re-reads the registry (fs.watch, and a one-minute floor) and aborts the
+ * watcher of any folder that has left it.
+ *
+ * A FAILED ACK IS NOT A FAILED FORGET. The folder is already gone locally and
+ * the row is already invisible to the picker; the ack is what deletes the row
+ * for good, and an ack that did not land leaves a tombstone nobody can see.
+ * So it is logged and never thrown - the same posture every other beat-time
+ * call in this file keeps.
+ */
+export async function serviceForgetOps(root, project, ops, settings, log = () => {}) {
+  const mine = (ops ?? []).find((op) => op.kind === "forget" && op.project_id === project.id);
+  if (!mine) return false;
+
+  const runnerApi = settings.runnerApi ?? runnerApiModule;
+  const env = settings.env ?? process.env;
+
+  // Capture init's local generation BEFORE the confirmation request. init may
+  // restore after that request reads Remove but before its response arrives.
+  // Read under the lock too: never capture init's new generation while its
+  // hosted restore is still in flight and the server still reports Remove.
+  const generation = await withRegistryLock(() => folderRestoreGeneration(root, env), env);
+  const latest = await runnerApi.heartbeat({ projectIds: [project.id] }, { env, fetchImpl: settings.fetchImpl });
+  if (!latest.ok) throw new Error(latest.error ?? "Could not confirm folder removal.");
+  if (!(latest.ops ?? []).some((op) => op.kind === "forget" && op.project_id === project.id)) return false;
+
+  return withRegistryLock(async () => {
+    // The compare, local removal and acknowledgement share init's restore lock:
+    // no restore can slip between this check and either destructive operation.
+    if (await folderRestoreGeneration(root, env) !== generation) return false;
+    const { removed } = await removeFolder(root, env);
+    log(
+      removed
+        ? `forget: the board asked for ${root} to be removed - dropped it from the folder registry`
+        : `forget: the board asked for ${root} to be removed - it was not in the folder registry`,
+    );
+
+    const acked = await runnerApi.forget({ projectIds: [project.id] }, { env, fetchImpl: settings.fetchImpl });
+    if (!acked.ok) log(`forget: could not acknowledge it to the board: ${acked.error}`);
+    else if ((acked.kept ?? []).length > 0) {
+      log(`forget: ${root}'s row is kept as a tombstone - runs still reference it - and is hidden from the picker`);
+    }
+    return true;
+  }, env);
+}
+
+// ---------- ops: merge, delete and relaunch, over heartbeat/opTake/opResult (item 2/5) ----------
+
+/** Take and act on every merge/delete/relaunch op this beat's heartbeat
+ * surfaced. `preview` is NOT here: unlike the other three, it is not a
+ * one-shot op - it is a tunnel this process has to keep re-verifying and
+ * re-reporting on for as long as it stands, so it needs state across beats
+ * rather than one pass per op. `watch()`'s own beat loop owns a
+ * `createSharedPreviewService` instance for exactly that, feeding it this
+ * same untaken-ops list (`onOps`) and ticking it (`tick`) every beat
+ * alongside this function - see there. */
+/** Write an op's result back, CHECKED and RETRIED (2026-09-20).
+ *
+ * THIS IS THE OTHER HALF OF op-mua5l39p-0bdcf7's STUCK "Deleting...": even
+ * once `stopsAndOps` (board-runner/store.mjs) surfaces an op and `opTake`
+ * claims it, the git operation's own result used to be logged
+ * "succeeded"/"failed" and then fired at `opResult` with the return value
+ * never read - so a write-back that itself failed (a token mid-refresh, a
+ * dropped connection) left `taken_at` set, `result` still null, the op
+ * genuinely done on disk but invisible to the app, and the log line claiming
+ * an outcome the row never recorded. The caller's own "succeeded" log line
+ * now waits for THIS to report the write landed, not for the git command to
+ * finish.
+ *
+ * THREE TRIES, SHORT BACKOFF: a board-runner call is one HTTP request against
+ * a function this same beat already reached (the heartbeat that surfaced the
+ * op just answered), so a failure here is almost always a blip worth a
+ * second attempt, not a standing outage worth a long wait. If every attempt
+ * fails, the op is left exactly where the server-side reclaim window (see
+ * `takeOp` in board-runner/store.mjs) expects a stuck claim to be: taken,
+ * unresolved, and takeable again once it goes stale - so this failing loud
+ * is a log line, never a throw that would leave the beat itself looking
+ * broken. */
+async function writeOpResult(runnerApi, opId, result, rowsOpts, log, { attempts = 3, delayMs = 500 } = {}) {
+  let last = { ok: false, error: "never attempted" };
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    last = await runnerApi.opResult({ opId, result }, rowsOpts);
+    if (last.ok) return last;
+    if (attempt < attempts) {
+      log(`[${opId}] opResult write-back failed (attempt ${attempt}/${attempts}): ${last.error}; retrying`);
+      await new Promise((resolve) => setTimeout(resolve, delayMs * attempt));
+    }
+  }
+  log(
+    `[${opId}] opResult write-back did NOT land after ${attempts} attempt(s): ${last.error}. ` +
+    `The op stays taken with no result recorded - it becomes takeable again once the server's ` +
+    `reclaim window passes (see takeOp, board-runner/store.mjs).`,
+  );
+  return last;
+}
+
+export async function serviceRowOps(root, project, ops, settings, log = () => {}) {
+  const runnerApi = settings.runnerApi ?? runnerApiModule;
+  const rowsOpts = { env: settings.env, fetchImpl: settings.fetchImpl };
+  // OVERRIDABLE SO A TEST DOES NOT PAY FOR A REAL BACKOFF: every other
+  // timing knob in this file (`pollMs`, `beatMs`, `killGraceMs`, ...) already
+  // rides `settings`, and a write-back retry belongs beside them rather than
+  // being the one delay a test cannot shorten.
+  const retryOpts = { attempts: settings.opResultAttempts ?? 3, delayMs: settings.opResultRetryMs ?? 500 };
+  let ok = await flushComputerApps(root, project, runnerApi, rowsOpts);
+  for (const op of ops ?? []) {
+    if (op.kind === "computer-apps") {
+      ok = await serviceComputerApps(root, project, op, runnerApi, rowsOpts, settings.lookForComputerApps) && ok;
+      continue;
+    }
+    if (op.kind === "merge" || op.kind === "delete") {
+      const taken = await runnerApi.opTake({ opId: op.id }, rowsOpts);
+      if (!taken.ok) ok = false;
+      if (!taken.ok || !taken.op) continue; // already taken, gone, or not ours
+      const opWorktreePath = taken.op.payload?.worktreePath;
+      if (!opWorktreePath) {
+        ok = false;
+        await writeOpResult(runnerApi, op.id, { ok: false, detail: "No worktreePath on this op." }, rowsOpts, log, retryOpts);
+        continue;
+      }
+      log(`[${op.id}] ${op.kind} requested for ${opWorktreePath}`);
+      const result = op.kind === "merge"
+        ? await mergeWorktree(root, opWorktreePath, log)
+        : await deleteWorktree(root, opWorktreePath, log);
+      // THE CONFLICT TRAVELS WITH THE RESULT (#483): the app reads `conflict`
+      // and `files` and sends Coding back to fit its changes around the
+      // person's. No question is filed here any more: Coding starts the fix,
+      // not the person, so a failed Keep is never a "Retry merge?" ask.
+      const written = await writeOpResult(
+        runnerApi,
+        op.id,
+        {
+          ok: result.ok,
+          detail: result.detail,
+          ...(result.conflict ? { conflict: true, files: result.files ?? [] } : {}),
+          ...(result.ok && typeof result.files === "number" ? { files: result.files } : {}),
+        },
+        rowsOpts,
+        log,
+        retryOpts,
+      );
+      if (!result.ok || !written.ok) ok = false;
+      if (written.ok) log(`[${op.id}] ${op.kind} ${result.ok ? "succeeded" : "failed"}: ${result.detail}`);
+      continue;
+    }
+    if (op.kind === "relaunch") {
+      const taken = await runnerApi.opTake({ opId: op.id }, rowsOpts);
+      if (!taken.ok) ok = false;
+      if (!taken.ok || !taken.op) continue;
+      // THE RECORD: the owning run's own `server` column (mirrored there by
+      // `runnerCompletion.mjs` when the child exits), or the hinted
+      // worktree's own live `.glytch-server.json` file when the row has
+      // none yet - the row equivalent of the file version's
+      // `<id>.server`-then-`.glytch-server.json` fallback chain.
+      const listed = await runnerApi.runs({ projectIds: [project.id] }, rowsOpts);
+      if (!listed.ok) ok = false;
+      const owner = listed.ok ? listed.runs?.find((r) => r.id === op.run_id) : null;
+      const hinted = taken.op.payload?.worktreePath;
+      const record = owner?.server ?? (hinted ? await readWorktreeRecord(hinted) : null);
+      const outcome = await relaunchServer(record, { root });
+      const written = await writeOpResult(runnerApi, op.id, { ok: outcome.ok, detail: outcome.detail }, rowsOpts, log, retryOpts);
+      if (!outcome.ok || !written.ok) ok = false;
+      if (written.ok) log(`[${op.id}] relaunch ${outcome.ok ? "ok" : "refused"}: ${outcome.detail}`);
+      // THE FRESH RECORD LANDS ON THE RUN ROW, the row equivalent of the
+      // file version's second write to `<id>.server` - a later relaunch (or
+      // lib/serverSweep.mjs) reads the SAME copy this one just wrote.
+      if (outcome.ok && outcome.record && owner) {
+        const updated = await runnerApi.update({ runId: owner.id, patch: { server: outcome.record } }, rowsOpts);
+        if (!updated.ok) ok = false;
+      }
+    }
+  }
+  if (!ok) log("Operation results remain pending; retained Look answers will retry on heartbeat.");
+  return { ok };
+}
+
+// ---------- the loop ----------
+
+/** The sessions THIS process has started and not yet seen finish. Unchanged
+ * from the file-based runner - per-process, not persisted, because what
+ * survives a restart is the CLAIM (server-side now), and inventing a second
+ * durable record of the same fact is how the two would start disagreeing. */
+export function makePool() {
+  const active = new Map();
+  return {
+    ids: () => [...active.keys()],
+    size: () => active.size,
+    add(id, promise) {
+      const done = Promise.resolve(promise).finally(() => active.delete(id));
+      active.set(id, done);
+      return done;
+    },
+    drain: () => Promise.allSettled([...active.values()]),
+  };
+}
+
+/** One pass, waited out - for tests and for a person asking for a single
+ * pass with an answer at the end of it. */
+export async function pollOnce(root, settings, log = () => {}) {
+  const reg = await registerAndFindProject(root, settings);
+  if (!reg.ok || !reg.myProjectId) return { ran: [], skipped: [{ reason: reg.error ?? "could not register this project" }] };
+  const project = { id: reg.myProjectId, path: root };
+  if (!(await flushCompletions(project, settings, log))) return { ran: [], skipped: [{ reason: "Saved completions are waiting to sync." }] };
+  const attempt = await claimOne(root, project, settings, log);
+  if (!attempt.claimed) return { ran: [], skipped: [{ reason: attempt.detail }] };
+  const result = await runRequest(project, attempt.run, settings, log);
+  return { ran: [result] };
+}
+
+/** Poll until stopped by `signal` or until this folder is removed. */
+export async function watch(root, settings, { signal, log = () => {}, startPreviewTransport } = {}) {
+  if (settings.enabled !== true) {
+    throw new Error('The runner is off. Set PM_SPAWN_RUNNER=on and run the watch command by hand.');
+  }
+  log(`watching ${root}: ${settings.maxConcurrent === Infinity ? "any number at once" : `up to ${settings.maxConcurrent} at once`}, binary "${settings.claudeBin ?? "per request"}"`);
+
+  const pool = makePool();
+  const stopped = settings.stopped ?? new Set();
+  settings.stopped = stopped;
+  let project = null;
+  // ONE HEARTBEAT AND ONE REGISTER FOR THE WHOLE PROCESS (#616). multiwatch
+  // hands every folder the same hub and registrar; a lone watch gets its own.
+  const beatMs = settings.beatMs ?? DEFAULTS.beatMs;
+  // PUSH (#813): `settings.realtime` is the process's channel
+  // (lib/runnerRealtime.mjs). While it is joined the beat is every 5 minutes
+  // and events bring the claim, the Stop and the ops forward; while it is not,
+  // or with none, the beat is every 10 s as before.
+  const realtime = settings.realtime ?? null;
+  const beatBase = () => beatBaseMs(realtime, beatMs, settings.pushBeatMs);
+  // A failed answer is kept only as long as a 10 s beat would, never the
+  // 5 minutes a joined success lives, so a retry really asks (#813 review).
+  const heartbeats = settings.heartbeats ??= makeHeartbeatHub({ ttlMs: () => 0.9 * beatBase(), failureTtlMs: 0.9 * beatMs });
+  settings.registrar ??= makeRegistrar({ ttlMs: REGISTER_REFRESH_MS, failureTtlMs: 0.9 * beatMs });
+  // WHETHER A RUN IS WAITING HERE (#616). The heartbeat's `pending` names the
+  // folders with an approved run nobody has claimed, so the claim loop only
+  // calls `claim` when this folder is among them. null: the function predates
+  // `pending`, and the loop polls `claim` as it always did.
+  let claimHint = null;
+  // Bumped whenever claimHint becomes true or null, so a hint that arrives
+  // while a claim or heartbeat is in flight is not overwritten by its
+  // older empty answer (#813 review, #1048).
+  let hintSeq = 0;
+  let nudge = null;
+  const nudged = () => (nudge ??= (() => {
+    let resolve;
+    const promise = new Promise((r) => { resolve = r; });
+    return { promise, resolve };
+  })()).promise;
+  const wake = () => {
+    nudge?.resolve();
+    nudge = null;
+  };
+  // A waiting run pushed to this folder ends the claim loop's wait too, not
+  // only its no-call wait above (#813).
+  let kick = null;
+  const kicked = () => (kick ??= (() => {
+    let resolve;
+    const promise = new Promise((r) => { resolve = r; });
+    return { promise, resolve };
+  })()).promise;
+  const kickClaim = () => {
+    kick?.resolve();
+    kick = null;
+  };
+  // Both CLI entry points and multiwatch arrive here. Always service preview
+  // rows through the member gateway; tests can replace the public transport,
+  // but the membership and target-ownership checks stay on this path. Missing
+  // access configuration becomes an error on the op, without exposing a port.
+  const previewService = createSharedPreviewService({
+    runnerApi: settings.runnerApi ?? runnerApiModule,
+    hostedCallTool: settings.hostedCallTool ?? callRunnerTool,
+    env: settings.env,
+    fetchImpl: settings.fetchImpl,
+    startTunnel: (origin, context) => createMemberPreviewTunnel(origin, context, {
+      env: settings.env, startTransport: startPreviewTransport,
+    }),
+  });
+  let previewClosing;
+  const closePreview = () => previewClosing ??= previewService.close().catch((error) => {
+    log(`preview shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
+  });
+  // Abort startup too: the preview worker may still be waiting for a tunnel URL.
+  const onAbort = () => { wake(); void closePreview(); };
+  signal?.addEventListener("abort", onAbort, { once: true });
+
+  // THIS FOLDER HAS BEEN FORGOTTEN (2026-09-12, ruling 3). Once a forget
+  // op has been serviced, this loop stops registering, stops beating and stops
+  // claiming and exits, so multiwatch can restart it if init re-adds it.
+  // Without it the beat would re-register the folder it just unregistered (`registerAndFindProject`
+  // falls back to `[root]` when the registry is empty, which is exactly the
+  // case after forgetting the last folder on a machine) and the person's
+  // Remove would undo itself. multiwatch aborts this watcher within the
+  // minute anyway - this is what holds the line until it does.
+  let forgotten = false;
+  // THE DETACHED DEV SERVERS this folder's finished runs left behind, checked
+  // once a day off the beat (lib/serverSweep.mjs). Rows, not files: the
+  // record lives on the run row since brief 30.
+  let serverSweptAt = 0;
+  const sweepServers = async () => {
+    if (Date.now() - serverSweptAt < (settings.serverSweepMs ?? SERVER_SWEEP_INTERVAL_MS)) return;
+    serverSweptAt = Date.now();
+    try {
+      await sweepDetachedServers(project, settings, { log });
+    } catch (error) {
+      log(`dev server sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  // Recheck periodically too: the same watcher may lose touch and recover
+  // more than once without restarting its own process (#1252).
+  let restartDueAt = 0;
+  let previewTick;
+  const tickPreview = () => {
+    if (previewTick || previewClosing) return;
+    // Download/connect can take minutes. The preview owns that wait; runner
+    // presence, Stop/forget delivery and first-run admission must keep moving.
+    previewTick = previewService.tick()
+      .catch((error) => log(`preview tick failed: ${error instanceof Error ? error.message : String(error)}`))
+      .finally(() => { previewTick = null; });
+  };
+
+  // Ownership misses (including a deleted id) use this exact refusal. After
+  // glytch login changes accounts, retry registration on the next beat without
+  // letting either shared cache hand back the old account's project id.
+  const clearRefusedProject = (answer) => {
+    if (!project || answer.ok !== false || answer.transient === true || answer.error !== "not yours") return;
+    heartbeats.leave(project.id);
+    realtime?.setFolder(project.id, false);
+    project = null;
+    claimHint = false;
+    settings.registrar.invalidate?.();
+  };
+
+  // The Retry-After of the last beat that failed, for the beat's own pace.
+  let beatRetryAfterMs;
+  const runBeat = async () => {
+    beatRetryAfterMs = undefined;
+    if (forgotten) return;
+    const registered = project !== null;
+    // A known folder must hear Remove before register can clear forgotten_at
+    // through its link RPC. Only startup needs register to obtain the id.
+    if (!registered) {
+      const reg = await registerAndFindProject(root, settings);
+      if (!reg.ok) {
+        log(`could not register with the board: ${reg.error}`);
+        beatRetryAfterMs = reg.retryAfterMs;
+        return reg.transient ? "failed" : "steady";
+      }
+      if (!reg.myProjectId) {
+        log(`this folder is not among the projects the board acknowledged; nothing will be claimed`);
+        return "steady";
+      }
+      project = { id: reg.myProjectId, path: root };
+      realtime?.setFolder(project.id, true);
+    }
+    const flushed = await flushCompletions(project, settings, log);
+    const runnerApi = settings.runnerApi ?? runnerApiModule;
+    const seen = hintSeq;
+    const beat = await heartbeats.beat(project.id, (projectIds) => runnerApi.heartbeat({ projectIds, presence: presenceBody(settings) }, { env: settings.env, fetchImpl: settings.fetchImpl }));
+    if (!beat.ok) {
+      clearRefusedProject(beat);
+      log(`heartbeat failed: ${beat.error}`);
+      beatRetryAfterMs = beat.retryAfterMs;
+      return beat.transient ? "failed" : "steady";
+    }
+    // The shared answer holds every folder's ops; keep this folder's. An op
+    // naming no project is only taken from an answer for this folder alone.
+    const alone = (beat.coveredProjectIds ?? [project.id]).every((id) => id === project.id);
+    const ops = (beat.ops ?? []).filter((op) => (op.project_id ? op.project_id === project.id : alone));
+    if (Array.isArray(beat.pending)) {
+      claimHint = beat.pending.includes(project.id) || hintSeq !== seen;
+      if (claimHint) hintSeq += 1, wake();
+    } else {
+      claimHint = null;
+      hintSeq += 1;
+      wake();
+    }
+    try { await settings.onHealthy?.(root); }
+    catch (error) { log(`Could not write local connection check: ${error.message}`); }
+    // Stops are run ids: another folder's in this set is never acted on.
+    for (const runId of beat.stops ?? []) stopped.add(runId);
+    let opsFailed = false;
+    if (ops.length > 0) {
+      // FIRST, and it returns early: there is no point merging a worktree or
+      // standing a preview up for a folder that is leaving this machine.
+      try {
+        if (await serviceForgetOps(root, project, ops, settings, log)) {
+          forgotten = true;
+          heartbeats.leave(project.id);
+          realtime?.setFolder(project.id, false);
+          wake();
+          await closePreview();
+          return "work";
+        }
+      } catch (error) {
+        opsFailed = true;
+        log(`forget failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    // Retry retained Look answers even though claimed requests are absent
+    // from later heartbeat operations. Forget above always takes priority.
+    try { opsFailed = !(await serviceRowOps(root, project, ops, settings, log)).ok || opsFailed; }
+    catch (error) {
+      opsFailed = true;
+      log(`ops sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (ops.length > 0) {
+      try { await previewService.onOps(ops, project.id); }
+      catch (error) {
+        opsFailed = true;
+        log(`preview claim failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    // The shared register names ALL folders. If another folder is leaving,
+    // let its watcher consume the same forget before refreshing that list.
+    // A failed heartbeat or forget never reaches a register that could erase it.
+    if (registered && !opsFailed && !(beat.ops ?? []).some((op) => op.kind === "forget")) {
+      const refreshSettings = {
+        ...settings,
+        registrar: {
+          register: (key, send) => settings.registrar.register(key, async () => {
+            // Row ops may have awaited a slow merge after the beat snapshot.
+            // Bypass the heartbeat cache, only when register is actually due.
+            // The remaining read/write gap is closed server-side by
+            // https://github.com/glytch-ai/glytch/issues/1065.
+            const rowsOpts = { env: settings.env, fetchImpl: settings.fetchImpl };
+            // The registrar key is the exact path list captured by send().
+            // Presence includes forgotten rows; scope to this register's host.
+            const listed = await runnerApi.presence({ paths: JSON.parse(key) }, rowsOpts);
+            if (!listed.ok) return listed;
+            const projectIds = (listed.projects ?? [])
+              .filter((p) => p.host === (settings.host ?? "local"))
+              .map((p) => p.id);
+            // New paths have no id yet and cannot have a pending forget.
+            // This bare heartbeat only bumps last_seen_at: it neither replaces
+            // presence nor claims, acknowledges or marks ops delivered.
+            const latest = projectIds.length > 0
+              ? await runnerApi.heartbeat({ projectIds }, rowsOpts)
+              : { ok: true, ops: [] };
+            if (!latest.ok) return latest;
+            if ((latest.ops ?? []).some((op) => op.kind === "forget")) {
+              return { ok: false, error: "Registration deferred: a folder removal is pending." };
+            }
+            return send();
+          }),
+        },
+      };
+      const reg = await registerAndFindProject(root, refreshSettings);
+      settings.noGit = refreshSettings.noGit;
+      if (!reg.ok) {
+        clearRefusedProject(reg);
+        log(`could not register with the board: ${reg.error}`);
+        beatRetryAfterMs = reg.retryAfterMs;
+        return reg.transient ? "failed" : "steady";
+      }
+      if (!reg.myProjectId) {
+        log(`this folder is not among the projects the board acknowledged; nothing will be claimed`);
+        return "steady";
+      }
+    }
+    // THE RESTART PASS (brief 52, ruling 7): sessions the last process left
+    // running pick up where they were. Only once receipts that were saved but
+    // not yet delivered have gone out, or a run that really finished would be
+    // continued over its own ending.
+    if (flushed && Date.now() >= restartDueAt) {
+      restartDueAt = Date.now() + (settings.restartRecheckMs ?? RESTART_RECHECK_MS);
+      try { await restartPass(project, settings, { log }); }
+      catch (error) { log(`restart pass failed: ${error instanceof Error ? error.message : String(error)}`); }
+    }
+    await sweepServers();
+    tickPreview();
+    // Use the existing failure backoff while an answer is waiting, rather
+    // than the five-minute idle cadence used with realtime connected.
+    return opsFailed ? "failed" : "work";
+  };
+  let beatInFlight;
+  let finished = false;
+  // THE PACE OF BOTH LOOPS (ticket e8, lib/runnerPace.mjs). The beat keeps
+  // its 10 s while the board answers and backs off to 60 s on 5xx or network
+  // failures; the claim loop does the same under errors. While the queue
+  // stays empty it makes no call at all when the beat carries `pending`, and
+  // slows to 30 s against an older function that does not (#616).
+  const beatPacer = beatPace(settings, DEFAULTS.beatMs);
+  const claimPacer = claimPace(settings);
+  // The claim loop's wait. A test passes `settings.sleep` to step the loop
+  // and read the waits it asks for, instead of timing them on a wall clock.
+  const wait = settings.sleep ?? sleep;
+  let beatDelay = beatPacer.work();
+  // A failed beat backs off from 10 s whatever the cadence; any other waits
+  // the cadence of the moment: 5 minutes while joined, 10 s while not.
+  const beat = () => {
+    if (forgotten || finished) return Promise.resolve();
+    // Serialize the row sweeps, independently of the long-lived preview work.
+    return beatInFlight ??= runBeat()
+      .then((outcome) => {
+        if (outcome === "failed") beatDelay = beatPacer.failed(beatRetryAfterMs);
+        else {
+          beatPacer.work();
+          beatDelay = beatBase();
+        }
+      }, (error) => {
+        beatPacer.steady();
+        beatDelay = beatBase();
+        throw error;
+      })
+      .finally(() => { beatInFlight = null; });
+  };
+  const beatFailed = (error) => log(`heartbeat failed: ${error instanceof Error ? error.message : String(error)}`);
+  // A chain of timeouts rather than an interval, so the wait after each beat
+  // can depend on how that beat went. One timer at most: every schedule
+  // replaces the last.
+  let beating;
+  let beatAgain = false;
+  const scheduleBeat = () => {
+    clearTimeout(beating);
+    if (forgotten || finished) return;
+    const delay = beatAgain ? 0 : beatDelay;
+    beatAgain = false;
+    beating = setTimeout(() => {
+      void beat().catch(beatFailed).finally(scheduleBeat);
+    }, delay);
+    beating.unref?.();
+  };
+  // A beat now, for an event: after the one in flight if there is one.
+  const beatNow = () => {
+    if (forgotten || finished) return;
+    if (beatInFlight) {
+      beatAgain = true;
+      return;
+    }
+    clearTimeout(beating);
+    void beat().catch(beatFailed).finally(scheduleBeat);
+  };
+
+  // WHAT THE CHANNEL SAYS (#813). Each event becomes the call this loop
+  // already makes; none of them claims or stops by itself.
+  //  - joined: one heartbeat now, the catch-up for whatever was sent while
+  //    the socket was down, then every 5 minutes
+  //  - left: back to every 10 s, from now
+  //  - pending (this folder): claim now, through claimOne (#364)
+  //  - stop: the run id joins `stopped`, which the session checks every 2 s
+  //  - op (this folder): a heartbeat now, which hands the op over
+  // `at` is the same for every folder, so the hub still sends one heartbeat
+  // for all of them.
+  const onPush = (event) => {
+    if (forgotten || finished) return;
+    const payload = event.payload ?? {};
+    const mine = () => project !== null && (payload.project_id ?? project.id) === project.id;
+    if (event.type === "joined") {
+      heartbeats.invalidate(event.at);
+      beatNow();
+    } else if (event.type === "left") {
+      heartbeats.invalidate(event.at);
+      beatDelay = beatBase();
+      if (!beatInFlight) scheduleBeat();
+    } else if (event.type === "pending" && mine()) {
+      claimHint = true;
+      hintSeq += 1;
+      wake();
+      kickClaim();
+    } else if (event.type === "stop" && typeof payload.run_id === "string") {
+      if (project === null || mine()) stopped.add(payload.run_id);
+    } else if (event.type === "op" && mine()) {
+      heartbeats.invalidate(event.at);
+      beatNow();
+    }
+  };
+  const unsubscribePush = realtime?.subscribe(onPush);
+  // `glytch init` asking for a fresh beat (multiwatch's beatRequests).
+  const unsubscribeBeatAsk = settings.beatRequests?.subscribe((at) => {
+    if (forgotten || finished) return;
+    heartbeats.invalidate(at);
+    beatNow();
+  });
+  // The preview keeps its own 10 s tick, whatever the beat: a tunnel that
+  // dropped restarts within seconds, not at the next 5-minute beat. With no
+  // preview open it makes no call.
+  const previewTimer = setInterval(tickPreview, beatMs);
+  previewTimer.unref?.();
+
+  // A bare nudge promise does not keep Node alive when the queue is empty.
+  // Own liveness here, independently of the unref'd heartbeat/backoff timers.
+  const keepAlive = setInterval(() => {}, 2 ** 30);
+  try {
+    if (signal?.aborted) return;
+    await beat();
+    scheduleBeat();
+    while (!signal?.aborted && !forgotten) {
+      // The base interval, without touching the pace's counts, when nothing
+      // was asked of the board this pass (no project yet, or forgotten).
+      let delay = settings.pollMs;
+      // `forgotten` gates the claim loop too: a folder on its way off this
+      // machine must not pick up one last run on the way out.
+      if (project && !forgotten && claimHint === false) {
+        // Nothing waits here: no call until a beat says otherwise (#616).
+        await nudged();
+        continue;
+      }
+      if (project && !forgotten) {
+        const seen = hintSeq;
+        try {
+          const attempt = await claimOne(root, project, settings);
+          if (attempt.claimed) {
+            const promise = pool.add(attempt.run.id, runRequest(project, attempt.run, settings, log).catch((error) => {
+              log(`[${attempt.run.id}] failed: ${error instanceof Error ? error.message : String(error)}`);
+              return { id: attempt.run.id, state: "failed", detail: error instanceof Error ? error.message : String(error) };
+            }));
+            // A slot is free: a run refused at the limit is claimed now, not
+            // at the next beat, which joined is 5 minutes away (#813 review).
+            void promise.finally(() => {
+              if (forgotten || finished) return;
+              if (claimHint !== null) claimHint = true;
+              hintSeq += 1;
+              wake();
+              kickClaim();
+            });
+            delay = claimPacer.work();
+          } else if (attempt.transient) {
+            delay = claimPacer.failed(attempt.retryAfterMs);
+            log(`waiting ${Math.round(delay / 1000)}s: ${attempt.detail}`);
+          } else if (attempt.idle) {
+            // Snap back to the base interval while a run is active here.
+            delay = pool.size() > 0 ? claimPacer.work() : claimPacer.idle();
+            // The run the beat saw went elsewhere: wait for the next one. The
+            // idle pace still applies first, so a row the beat keeps naming
+            // but claim never hands out is asked about at most every 30 s.
+            if (claimHint === true && hintSeq === seen) claimHint = false;
+          } else {
+            delay = claimPacer.steady();
+            if (attempt.detail) log(`waiting: ${attempt.detail}`);
+            if (claimHint === true && hintSeq === seen) claimHint = false;
+          }
+        } catch (error) {
+          log(`poll failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // A run pushed while this claim was in flight: ask again now.
+        if (hintSeq !== seen && !signal?.aborted) continue;
+      }
+      await Promise.race([wait(delay, signal), kicked()]);
+    }
+  } finally {
+    await closePreview();
+    try {
+      // Keep presence and stop delivery alive while already-running sessions
+      // finish, as before; the closed preview service cannot take new ops.
+      if (pool.size() > 0) {
+        log(`stopping: waiting for ${pool.size()} session(s) already running to finish.`);
+        await pool.drain();
+      }
+    } finally {
+      finished = true;
+      unsubscribePush?.();
+      unsubscribeBeatAsk?.();
+      clearInterval(keepAlive);
+      clearInterval(previewTimer);
+      clearTimeout(beating);
+      signal?.removeEventListener("abort", onAbort);
+      if (beatInFlight) await beatInFlight;
+      if (project) {
+        heartbeats.leave(project.id);
+        realtime?.setFolder(project.id, false);
+      }
+    }
+  }
+}