viewable-one 0.0.0-stage → 0.12.1

package/lib/runnerCompletion.mjs

@@ -0,0 +1,406 @@
+// Finalize an exited child, over rows (brief 30 Move 2, 2026-09-11).
+//
+// Same job the file-based `completeRequest` had: log the child, decide what
+// happens to the worktree, tell the board what happened, and settle the run
+// - just none of it through `.glytch/inbox/spawn/` any more. The ONE thing
+// this version does NOT do that the old one did is write anything itself:
+// `result` is write-once server-side, so every field that used to be a
+// separate file write (`<id>.log`'s final authoritative write,
+// `<id>.session.json`, `<id>.server`, `<id>.result.txt`) is instead handed
+// back to the caller as ONE `patch` object, and `runner.mjs` makes exactly
+// one `runnerApi.update({runId, patch})` call with it - a run settles once,
+// not in four separate writes racing whatever else might be reading the row.
+import { cleanWorktree, isGitCheckout, worktreeSummary } from "./worktree.mjs";
+import { readWorktreeRecord } from "./devserver.mjs";
+import { reportOutcomeOnBoard, formatVerdict } from "./boardside.mjs";
+import { promoteLateRows } from "./rowsAnswers.mjs";
+import { housekeeping } from "./runnerMaintenance.mjs";
+import { classifyExit } from "./exitClass.mjs";
+import { readUsageLimit } from "./usageLimit.mjs";
+
+const defaultServices = {
+  cleanWorktree, worktreeSummary, readWorktreeRecord,
+  reportOutcomeOnBoard, promoteLateRows, housekeeping, isGitCheckout,
+};
+
+// The tools that write a file, by the names the app's run log already
+// sorts on (src/components/run/runWords.ts): Claude's Write/Edit, Codex's
+// normalised Edit, an ACP title such as "Edit index.html".
+const EDITING_TOOL = /^(write|create|edit|multiedit|notebookedit|patch|apply_patch|update)/i;
+// A shell can write anything, so any shell call counts as a change, failed
+// or not: Claude's Bash, Codex's commandExecution (named Bash), ACP shells.
+const SHELL_TOOL = /^(bash|shell|local_shell|exec|run|terminal|command)/i;
+
+/** Might the run have changed files in its folder? It warns that Throw away
+ *  cannot undo them (#483), so a doubt reads as yes (#735 review): any shell
+ *  call, an edit with no error result (denied or failed edits change
+ *  nothing; one with no result yet may have), and a log whose middle was
+ *  cut (`dropped` characters), since the cut events cannot be checked.
+ *  A file the ACP client wrote for the agent (fs/write_text_file) logs its
+ *  own `file_write` line, which counts too. */
+export function mayHaveChangedFiles(log, { dropped = 0 } = {}) {
+  if (dropped > 0) return true;
+  const edits = [];
+  const failed = new Set();
+  for (const line of String(log ?? "").split("\n")) {
+    if (!line.includes('"tool_use"') && !line.includes('"tool_result"') && !line.includes('"file_write"')) continue;
+    let event;
+    try { event = JSON.parse(line); } catch { continue; }
+    if (event?.type === "system" && event.subtype === "file_write") return true;
+    const content = event?.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (event.type === "assistant" && block?.type === "tool_use") {
+        const name = String(block.name ?? "");
+        if (SHELL_TOOL.test(name)) return true;
+        if (EDITING_TOOL.test(name)) edits.push(block.id);
+      } else if (event.type === "user" && block?.type === "tool_result" && block.is_error === true) {
+        failed.add(block.tool_use_id);
+      }
+    }
+  }
+  return edits.some((id) => id == null || !failed.has(id));
+}
+
+
+/** A run's result without its Before and After pictures. */
+const withoutPictures = ({ before, after, changed, ...rest }) => rest;
+
+/** Called only after the child and its live log timer have stopped.
+ *
+ * `context`: `{root, id, outcome, made, isPersistent, isChat, sessionIdSource,
+ * from, session, maxMs, readStopRequested, resumeTreeGone,
+ * resumeNotFound, request, log, rowsPoll, hostedCallTool, hostedEnv,
+ * resumeFn}`. `resumeFn`
+ * is `runnerApi.resume` (or a test stub) - the row equivalent of
+ * `promoteReplyToRequest`, passed as `promoteLateRows`'s `promote` override
+ * so a late answer/message becomes a new APPROVED child run row instead of
+ * a new request FILE.
+ *
+ * Returns `{id, state, patch, detail}` - `patch` is what the caller sends
+ * through `runnerApi.update`; nothing here calls it. */
+export async function completeRequest(context, services = defaultServices) {
+  const {
+    root, id, outcome, made, isPersistent, isChat, sessionIdSource,
+    from, session, maxMs, readStopRequested, resumeTreeGone,
+    resumeNotFound, request, log, rowsPoll, hostedCallTool, hostedEnv, resumeFn,
+  } = context;
+  const {
+    cleanWorktree, worktreeSummary, readWorktreeRecord,
+    reportOutcomeOnBoard, promoteLateRows, housekeeping, isGitCheckout: inGit,
+  } = services;
+
+  // THE DEV SERVER THE SESSION LEFT RUNNING ON PURPOSE (2026-09-06, his
+  // ruling A), mirrored into the run row's own `server` column instead of
+  // `<id>.server` - read-only from the session's own worktree artifact
+  // (`.glytch-server.json`, unaffected by Move 2: the SESSION writes it, not
+  // the mailbox), before `cleanWorktree` runs below and can remove the tree
+  // it lives in.
+  let server = null;
+  try {
+    const record = await readWorktreeRecord(made.path ?? made.cwd);
+    if (record) {
+      server = { ...record, worktreePath: made.path ?? made.cwd, mirroredAt: new Date().toISOString() };
+      log(`[${id}] a detached dev server was left running: pid ${server.pid}, port ${server.port ?? "unknown"}`);
+    }
+  } catch (error) {
+    log(`[${id}] could not record the session's dev server: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const claudeSessionId = extractSessionIdFromLog(sessionIdSource ?? outcome.log ?? "");
+
+  // A CHILD THAT NEVER RAN KEEPS NOTHING "FOR SESSION RESUME" (2026-09-20).
+  // `outcome.spawnError` means `child.on("error")` fired in child.mjs -
+  // this machine could not even start the binary (spawn ENOENT, most often)
+  // - so the worktree `made` names was never touched: no commits, no
+  // uncommitted changes, nothing a resume could possibly continue. Before
+  // this, `isPersistent` alone decided the branch below, and a request that
+  // carries a sessionId/resumeSessionId (every board-spawned session does)
+  // took the "KEPT for session resume" literal unconditionally - so a run
+  // that failed to start still held its worktree forever, and the very next
+  // request on the same prompt was refused as "already has an active
+  // session" against a tree with nothing in it. `cleanWorktree` is safe to
+  // call here even though it is NOT normally called for a persistent
+  // request: it inspects the tree's own git status before removing anything
+  // (worktree.mjs's `cleanWorktreeImpl`), so a request that also happened to
+  // fail AFTER doing real work is still `spawnError`-free by definition
+  // (the child ran, so this branch is not reached) and never hits this path.
+  const neverStarted = Boolean(outcome.spawnError);
+  const cleaned = neverStarted
+    ? await cleanWorktree(root, made, log, [])
+    : isPersistent
+      ? { removed: false, detail: `${made.detail}\nKEPT for session resume (persistent session).` }
+      : await cleanWorktree(root, made, log, []);
+
+  const treeKept = !cleaned.removed && made.isolated && made.path;
+  let sidecar;
+  // The branch and the count of files it touched, for the reply's figures
+  // line and its links. Null for a chat turn and for a tree nobody kept.
+  let summary = null;
+  // THE SIDECAR IS WRITTEN FOR EVERY CHAT TURN, NOT ONLY A PERSISTENT ONE.
+  // A first message carries no session id to resume, so `isPersistent` is
+  // false for it and `treeKept` is false too (a chat turn's `made` is never
+  // `isolated`) - without `isChat` here that first message would write no
+  // sidecar at all, and the room would have no way to learn which
+  // conversation it just opened (`claudeSessionId`) or where it lives
+  // (`worktreePath`, equal to the cwd). No sidecar, no second turn.
+  if (isPersistent || treeKept || isChat) {
+    // Only a copy has a branch to summarise. A chat turn ran in the room's
+    // own directory; a run in place ran in the person's own checkout, whose
+    // branch and uncommitted files are theirs, not the run's (#735: a run
+    // told to change nothing read "branch main, 1 file").
+    if (made.isolated && !isChat) {
+      try {
+        summary = await worktreeSummary(made.path ?? made.cwd, root);
+      } catch { /* non-fatal */ }
+    }
+    sidecar = {
+      ...(claudeSessionId ? { claudeSessionId } : {}),
+      ...(outcome.codexThreadId ? { codexThreadId: outcome.codexThreadId } : {}),
+      // NEVER A PATH THAT WAS JUST DELETED (2026-09-20). `cleaned.removed`
+      // is only ever true when `cleanWorktree` actually ran and the tree is
+      // gone - the app reads `sidecar.worktreePath` to decide whether to
+      // show Merge/Delete on this run's card, and a path it cannot act on
+      // is worse than no path at all.
+      //
+      // AND NEVER THE LINKED FOLDER ITSELF (2026-09-26, live run
+      // spawn-muipo5wp-7706dc in a folder that is not a git repo): a
+      // persistent session that ran IN PLACE (`made.isolated` false - no
+      // worktree could be made, or the idea turned it off) has no tree of
+      // its own, yet `made.cwd` is the checkout root, and recording it here
+      // put Keep changes and Throw away over the person's own folder.
+      // A chat turn is the one non-isolated case that still needs the path:
+      // it IS the room's cwd, and the next turn is sent back there.
+      ...(cleaned.removed || (!made.isolated && !isChat) ? {} : { worktreePath: made.path ?? made.cwd }),
+      ...(from ? { fromId: from } : {}),
+      expired: isPersistent ? (!claudeSessionId || outcome.ok !== true) : undefined,
+      ...(summary?.line ? { worktreeSummary: summary.line } : {}),
+      ...(outcome.envelope?.total_cost_usd !== undefined ? { costUsd: outcome.envelope.total_cost_usd } : {}),
+      ...(outcome.envelope?.cost_source !== undefined ? { costSource: outcome.envelope.cost_source } : {}),
+      ...(outcome.envelope?.num_turns !== undefined ? { numTurns: outcome.envelope.num_turns } : {}),
+      ...(outcome.contextFill !== null && outcome.contextFill !== undefined ? { contextFill: outcome.contextFill } : {}),
+    };
+    log(`[${id}] sidecar: claudeSessionId=${claudeSessionId ?? "none"}, worktree=${treeKept ? "kept" : "persistent"}${summary?.line ? `, summary=${summary.line}` : ""}`);
+  }
+
+  // A COMMENT ON THE RUN'S OWN IDEA, BEFORE THE ROW SETTLES - the fix for
+  // "done with nothing said about how it went" carries over unchanged, only
+  // the door moved: `propose` under the run's session key instead of an
+  // `addComment` ops file. `frameId` is simply `from` now (fromIdOf(request))
+  // since there is no separate run-record id to have diverged from it.
+  const wasStopped = outcome.stoppedByUser === true || readStopRequested();
+  // No copy, so no Throw away; the reply says why (#483), but only for a
+  // folder that is not a git checkout and only when the run may have
+  // changed files there (#735). A chat turn and a read-only plan change nothing.
+  const changedNonGitFolder = async () => {
+    if (made.isolated || isChat || made.detail?.startsWith("Read-only planning")) return false;
+    if (!mayHaveChangedFiles(outcome.log, { dropped: outcome.dropped })) return false;
+    try { return !(await inGit(made.cwd)); } catch { return false; }
+  };
+  try {
+    await reportOutcomeOnBoard(session, outcome, from, {
+      callTool: hostedCallTool,
+      env: hostedEnv,
+      request,
+      stopped: wasStopped,
+      worktree: summary ? { branch: summary.branch, files: summary.files } : undefined,
+      inPlace: await changedNonGitFolder(),
+      preview: Number.isFinite(Number(server?.port)) ? `http://localhost:${Number(server.port)}` : undefined,
+    });
+  } catch (error) {
+    log(`[${id}] could not comment the outcome onto the board: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const resumeNote = resumeTreeGone
+    ? `THE EARLIER CONVERSATION COULD NOT BE RESUMED: ITS WORKTREE IS GONE.\n` +
+      `${request.worktreePath} no longer exists (merged and deleted, swept, or pruned), ` +
+      `and Claude Code keeps conversations per working directory - so session ` +
+      `${String(request.resumeSessionId).trim()} could not be reached from anywhere this ` +
+      `session could run. This ran as a FRESH session in a new worktree instead, and was told so ` +
+      `in one line. The sidecar records the NEW session id, so the next run of this idea resumes ` +
+      `THIS session rather than the one that is gone.\n\n`
+    : resumeNotFound
+      ? `THE EARLIER CONVERSATION COULD NOT BE RESUMED: CLAUDE CODE HAD NO RECORD OF IT.\n` +
+        `The worktree was still here and was reused, but ` +
+        `--resume ${String(request.resumeSessionId).trim()} came back with ` +
+        `"No conversation found" at 0 turns and $0.00. Nothing was spent and nothing was done, so ` +
+        `this ran ONCE more as a fresh session in that same worktree - the one retry the ` +
+        `"exactly once" rule allows, because the first attempt did not happen. The sidecar records ` +
+        `the NEW session id.\n\n`
+      : "";
+  const detail = `${resumeNote}${describeOutcome(outcome, maxMs, from, { stopped: wasStopped })}\n\n${cleaned.detail}`;
+  // STOPPED OUTRANKS ok. The row's own `status` check constraint carries a
+  // distinct 'stopped' value the file-based runner had no room for (it only
+  // ever wrote `stopped: true` as an annotation beside a two-state "done"),
+  // so a run the human clicked Stop on settles as 'stopped' whether or not
+  // its exit happened to read as ok - "you stopped it" is worth keeping
+  // separate from "it finished" even when the two exits look alike.
+  const status = wasStopped ? "stopped" : outcome.ok === true ? "done" : "error";
+  const patch = {
+    status,
+    result: `${outcome.ok === true ? "OK" : "ERROR"}\n\n${detail}\n`,
+    finished_at: new Date().toISOString(),
+    // Completion owns the final metadata, including clearing an early path
+    // when cleanup removed the worktree. Failures before completion have no
+    // final sidecar and may retain their early workspace receipt instead.
+    // The pictures ride on the closing reply only: two of them on every run
+    // row would weigh down each list of runs (#2194).
+    sidecar: { ...(sidecar ?? {}), ...(outcome.result ? { result: withoutPictures(outcome.result) } : {}), ...(status === "error" ? agentErrorOf(outcome) : {}) },
+    ...(server ? { server } : {}),
+  };
+
+  // THE ROW EQUIVALENT OF THE LATE-REPLY SWEEP, ONE MORE `collect_session`
+  // CALL (brief 30, W2b, carried into Move 2 unchanged): only when the run
+  // ever had a bearer to send in the first place. `resumeFn` (runnerApi's
+  // `resume`) replaces `promoteReplyToRequest`'s file write with one op the
+  // function does server-side.
+  if (rowsPoll) {
+    try {
+      const { filed: filedRows, dropped } = await promoteLateRows(
+        root, id,
+        {
+          poller: rowsPoll, callTool: hostedCallTool, sessionKey: session.key, env: hostedEnv,
+          promote: async (_root, targetId, reply, _log, promotionId) => {
+            // IMAGES, item 6: `reply.images` is the late row's own images
+            // (rowsAnswers.mjs's `promoteLateRows`), carried into `resume`
+            // exactly as a reply file's `images` used to ride
+            // `promoteReplyToRequest`.
+            const out = await resumeFn({ runId: targetId, message: reply.attributed ?? reply.text, images: reply.images }, { env: hostedEnv });
+            if (!out.ok) return null;
+            void promotionId; // resume's own idempotency is server-side (Move 2 contract)
+            return out.id ?? null;
+          },
+        },
+        log,
+      );
+      if (filedRows.length > 0) log(`[${id}] ${filedRows.length} late row(s) became run(s): ${filedRows.join(", ")}`);
+      // WHAT NEVER REACHED THE SESSION (round 4 item 75) rides the final
+      // sidecar; the app marks the matching note "did not reach the session".
+      if (dropped.length > 0) patch.sidecar = { ...patch.sidecar, undelivered: dropped };
+    } catch (error) {
+      log(`[${id}] late-row sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  try { await housekeeping(root, log); }
+  catch (error) { log(`[${id}] post-session housekeeping failed: ${error?.message ?? error}`); }
+
+  return { id, state: status === "done" ? "done" : "failed", patch, detail };
+}
+
+/** WHAT THE AGENT ITSELF SAID WENT WRONG (#482), for the app's "Claude
+ *  sent back an error: <error>." `agentError` is its first line, short;
+ *  `usageLimit` is set when that was the plan running out (usageLimit.mjs),
+ *  with the time it comes back when the agent said one. A stall, a timeout
+ *  or a binary that never started has no words of the agent's to keep. */
+export function agentErrorOf(outcome) {
+  if (outcome.spawnError || outcome.stalled || outcome.timedOut) return {};
+  const env = outcome.envelope ?? {};
+  const said = [
+    env.is_error === true && typeof env.result === "string" ? env.result : "",
+    typeof env.error === "string" ? env.error : "",
+    ...(Array.isArray(env.errors) ? env.errors.filter((e) => typeof e === "string") : []),
+    typeof outcome.stderr === "string" ? outcome.stderr.slice(-2000) : "",
+  ].map((t) => t.trim()).filter(Boolean);
+  if (said.length === 0) return {};
+  const first = said[0].split("\n").map((l) => l.trim()).find(Boolean) ?? "";
+  const limit = said.map((t) => readUsageLimit(t)).find((r) => r !== null);
+  return {
+    agentError: first.length > 200 ? `${first.slice(0, 199).trimEnd()}…` : first,
+    ...(limit ? { usageLimit: limit } : {}),
+  };
+}
+
+function describeOutcome(outcome, maxMs, frameId, { stopped } = {}) {
+  const verdict = formatVerdict(outcome);
+  const verdictLine = verdict ? `${verdict}\n\n` : "";
+  const retriedNote = outcome.retried ? `\nRetried once after ${outcome.firstCrashClass} before any output.` : "";
+  const where = `${frameId ? `The run's record is on the board (${frameId}). ` : "This run has no idea on the board. "}` +
+    `Its row is the record now - there is nothing left for them to accept or reject.\n` +
+    `The child's output is this run's events.${retriedNote}`;
+  if (outcome.spawnError) {
+    return (
+      `Could not start the session: ${outcome.spawnError}\n\n` +
+      `That is your computer failing to run the binary, not the session failing.\n${where}`
+    );
+  }
+  if (outcome.finished && !outcome.finishedWithError) {
+    const envelope = `The session finished its work: its final result envelope is at the end of the events.`;
+    if (stopped || outcome.timedOut || outcome.code !== 0) {
+      const closedBy = stopped ? "a stop" : `the wall clock of ${Math.round(maxMs / 60_000)} minutes`;
+      return `${verdictLine}${envelope} The child was closed by ${closedBy} after finishing; nothing was cut short.\n${where}`;
+    }
+    return (
+      `${verdictLine}${envelope} The session finished and exited on its own once the envelope landed. ` +
+      `The worktree stays, and the session can be resumed from the board (Continue).\n${where}`
+    );
+  }
+  if (outcome.finishedWithError) {
+    return (
+      `${verdictLine}The session ended its last turn with an ERROR result envelope: the engine ` +
+      `itself said the run went wrong (a refusal, an internal error). The envelope ` +
+      `is at the end of the events.\n${where}`
+    );
+  }
+  if (outcome.stalled) {
+    return (
+      `${verdictLine}Stopped responding.\n\n` +
+      `No output for ${Math.round((outcome.stallMs || 0) / 60_000)}m with a turn open. ` +
+      `The session was sent SIGTERM. Whatever it had not finished is not finished.\n${where}`
+    );
+  }
+  if (stopped) {
+    return (
+      `${verdictLine}Stopped by user request.\n\n` +
+      `The session was sent SIGTERM because the human clicked Stop. ` +
+      `Whatever it had not finished is not finished.\n${where}`
+    );
+  }
+  if (outcome.timedOut) {
+    return (
+      `${verdictLine}Killed at its wall clock of ${Math.round(maxMs / 60_000)} minutes.\n\n` +
+      `The board says "done", because the board carries two states and this is an ` +
+      `ending like any other. What actually happened is here: it ran out of time, so ` +
+      `whatever it had not finished is not finished.\n${where}`
+    );
+  }
+  if (outcome.code === 0) return `${verdictLine}The session finished cleanly (exit 0).\n\n${where}`;
+  const reason = outcome.stderr?.trim();
+  const why = reason ? `\n\nIt printed this on stderr before exiting:\n${reason.slice(-800)}` : "";
+  const cut =
+    outcome.dropped > 0
+      ? `\nThe live log was capped: ${outcome.dropped} characters dropped. The full transcript is this run's events.`
+      : "";
+  const cls = classifyExit(outcome.code, outcome.signal);
+  const ended = cls.isCrash
+    ? `The session crashed: ${cls.description}.${outcome.retried ? "" : " Not retried: it had already produced output, and a retry would duplicate it."}`
+    : `The session exited ${outcome.code}${outcome.signal ? ` on ${outcome.signal}` : ""}.`;
+  return (
+    `${verdictLine}${ended}${why}\n\n` +
+    `Nothing retries it. Whatever it managed to put on the board is there and is theirs to ` +
+    `keep or reject.${cut}\n${where}`
+  );
+}
+
+/** Extract the Claude session id from a stream-json log. Every event carries
+ * a `sessionID` field (verified on CLI 2.1.34); the first one found is the
+ * session's own id. Unchanged from the file-based runner. */
+function extractSessionIdFromLog(text) {
+  if (!text || text.trim() === "") return null;
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || !line.startsWith("{")) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed !== null && typeof parsed === "object") {
+        const id = typeof parsed.sessionID === "string" && parsed.sessionID.trim() !== ""
+          ? parsed.sessionID
+          : typeof parsed.session_id === "string" && parsed.session_id.trim() !== ""
+            ? parsed.session_id
+            : null;
+        if (id !== null) return id;
+      }
+    } catch { continue; }
+  }
+  return null;
+}

package/lib/runnerLease.mjs

@@ -0,0 +1,37 @@
+/** Lease renewal never restarts work. Losing ownership requests the same
+ * local stop as the human Stop action, including during run preparation. */
+export function startRunLease(project, run, settings, { api, log = () => {}, now = () => performance.now(), every = setInterval, clear = clearInterval } = {}) {
+  if (!run.lease_expires_at || !settings.runnerInstanceId) return { ready: Promise.resolve(), stop() {} };
+  settings.stopped ??= new Set();
+  let deadline = now() + 240_000;
+  let closed = false;
+  let pending = false;
+  const lose = () => {
+    if (!settings.stopped.has(run.id)) log(`[${run.id}] runner lease lost; stopping local execution`);
+    settings.stopped.add(run.id);
+    (settings.leaseLost ??= new Set()).add(run.id);
+  };
+  const tick = async (initial = false) => {
+    if (closed) return;
+    if (!Number.isFinite(deadline) || now() >= deadline) lose();
+    if (pending || settings.stopped.has(run.id)) return;
+    pending = true;
+    const sentAt = now();
+    try {
+      const response = await api.heartbeat({ projectIds: [project.id], runnerInstanceId: settings.runnerInstanceId, activeRunIds: [run.id] }, { env: settings.env, fetchImpl: settings.fetchImpl });
+      if (closed) return;
+      for (const id of response.stops ?? []) settings.stopped.add(id);
+      if (response.ok && Array.isArray(response.renewedRunIds)) {
+        if (!response.renewedRunIds.includes(run.id)) lose();
+        else if (Number.isFinite(response.leaseDurationMs) && response.leaseDurationMs > 60_000) deadline = sentAt + response.leaseDurationMs - 60_000;
+      } else if (initial) lose();
+    } catch { if (initial) lose(); }
+    finally { pending = false; }
+  };
+  // Check expiry independently of a potentially pending network request.
+  const expiry = every(() => { if (!closed && now() >= deadline) lose(); }, 1000);
+  const renewal = every(() => { void tick(); }, 30_000);
+  expiry.unref?.(); renewal.unref?.();
+  const ready = tick(true);
+  return { ready, stop() { closed = true; clear(expiry); clear(renewal); } };
+}

package/lib/runnerMaintenance.mjs

@@ -0,0 +1,27 @@
+// Lifecycle maintenance is called by runner.mjs at its existing boundaries:
+// housekeeping at start/spawn/teardown. This module owns no timers, session
+// pool, or child processes.
+//
+// THE SIDECAR BACKFILL is retired too, for a different reason: it fixed up
+// a FILE sidecar (`<id>.session.json`) a crashed session left incomplete,
+// and a run's sidecar is a row column now (`runs.sidecar`, written whole by
+// one `runnerApi.update` at the end of `runRequest` - there is no partial
+// write over rows for a backfill to complete). `housekeeping`'s only
+// production caller (`runnerCompletion.mjs`) already called it with
+// `backfill: false` before this pass for exactly that reason - the option
+// is dropped rather than kept as a dead flag nobody could ever set to true
+// usefully again.
+import { reapOrphanedWorktreeProcesses } from "./worktree.mjs";
+
+/** The orphan-process sweep, run at the moments it can be useful and never
+ * on a timer (SPAWN.md, ruling q-mt9as5a0 - no reaper, no heartbeat,
+ * nothing inferred from silence on its own timer). Never throws: a failed
+ * sweep must not take a session down. */
+export async function housekeeping(root, log = () => {}, { reap = true } = {}) {
+  if (!reap) return;
+  try {
+    await reapOrphanedWorktreeProcesses(root, log);
+  } catch (error) {
+    log(`orphan sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}