control board: stale registrations and a launch-test leak (#1504)

Two defects in 69f99323, reported by the professor session and verified.

The darkwing launch test's flock-contention spawn ran without the fixture
config, so launch.sh re-entered scripts/mosaic against the real data root
and wrote fixture records for darkwing, dewey and filbert there. That
spawn now names the fixture config, and both launch test files set
MOSAIC_CONFIG to a nonexistent path and clear MOSAIC_LAUNCH_REGISTERED
process-wide, so a spawn that forgets fails instead of polluting.

A registration is written before the launch script's own checks, so a
refused launch left a record with a dead pid that the board honoured. The
scanner now probes the recorded pid (pidAlive, signal 0); a gone pid makes
the record stale: still on the Registered line with alive false, derived
task, project and workspace win, index gains registrationStale, CLI
summary gains a stale count.

Fleet launchers marked not planned per Jason. Board 90/90, seat 15/15,
launch scripts 5/5. Sonnet review APPROVED.

Co-Authored-By: Claude Fable 5.1 <[email protected]>

packages/control-board/README.md

@@ -82,7 +82,7 @@ node --test packages/control-board/tests/
 
 ```
 <dataRoot>/board/
-  index.json                       # summary: counts, waiting-on-you, seen, registered, registrationErrors, all records
+  index.json                       # summary: counts, waiting-on-you, seen, registered, registrationStale, registrationErrors, all records
   seen.json                        # Jason's "seen" marks (see below)
   sessions/
     <project>/
@@ -126,6 +126,13 @@ in the record leaves the derived value in place. Rows with no registration
 are exactly as before. The board only reads `seats/`; `mosaic launch` and
 `mosaic seat task` are the only writers. A malformed record is listed in
 `registrationErrors` on the index (and on stderr for `scan`) and skipped.
+A record is written before the launch script's own checks run, so a refused
+launch leaves a record whose pid is gone. The scan probes the recorded pid
+on every pass; when it is gone the record is stale: the row keeps the
+Registered line (marked stale, `registered.alive` false) but the derived
+task, project and workspace win and the sources say so. Stale rows are
+listed under `registrationStale` on the index. A record with no pid is
+never stale.
 
 Marked rows are listed under a collapsed "Seen (N)" section on the page,
 each with an "Unsee" button, so nothing marked is ever out of reach. Each

packages/control-board/src/cli.mjs

@@ -59,7 +59,7 @@ async function main() {
       process.stdout.write(`${flag} ${s.state.padEnd(8)} ${s.project.padEnd(14)} ${s.agent.padEnd(16)} ${age.padStart(7)}  ${s.lastAssistantText ? s.lastAssistantText.slice(0, 80) : ""}\n`);
     }
   }
-  process.stdout.write(`board: ${boardDir} (${index.sessions.length} sessions, ${index.waitingOnYou.length} waiting on you, ${index.seen.length} seen, ${index.registered.length} registered)\n`);
+  process.stdout.write(`board: ${boardDir} (${index.sessions.length} sessions, ${index.waitingOnYou.length} waiting on you, ${index.seen.length} seen, ${index.registered.length} registered, ${index.registrationStale.length} stale)\n`);
 }
 
 main().catch((err) => {

packages/control-board/src/page.html

@@ -197,6 +197,7 @@
     if (reg.pid) parts.push("pid " + esc(reg.pid));
     if (reg.tmux && reg.tmux.session) parts.push("tmux " + esc(reg.tmux.session) + (reg.tmux.socket ? " (socket " + esc(reg.tmux.socket) + ")" : ""));
     if (reg.layout) parts.push(esc(reg.layout) + " layout");
+    if (reg.alive === false) parts.push("stale: pid " + esc(reg.pid) + " is gone, so the derived values are shown");
     return parts.join("; ");
   }
 

packages/control-board/src/scan.mjs

@@ -276,6 +276,18 @@ export function matchRegistration(spec, registrations) {
   return registrations.find((r) => r.sessionsDir && samePath(r.sessionsDir, spec.sessionsDir)) ?? null;
 }
 
+// True when a pid is running (a signal-0 probe; EPERM still means running),
+// false when it is gone, null when there is no pid to check.
+export function pidAlive(pid) {
+  if (!(Number.isInteger(pid) && pid > 0)) return null;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+
 // One agent -> one status record.
 //
 // Three fields answer "what is this seat doing, and where" (Gate A ask,
@@ -289,7 +301,11 @@ export function matchRegistration(spec, registrations) {
 //                 else the session log's cwd.
 //   activeProject registration.project, else the basename of the nearest git
 //                 repo root above the workspace.
-export function scanAgent(spec, { isAlive = tmuxInspect, now = () => new Date(), seen = {}, registration = null } = {}) {
+// A registration is written before the launch script's own checks run, so a
+// refused launch leaves a record whose pid is gone. Such a record is stale:
+// it is still reported under `registered` (with alive false) but the derived
+// values win, because the record describes a launch that is not running.
+export function scanAgent(spec, { isAlive = tmuxInspect, now = () => new Date(), seen = {}, registration = null, isPidAlive = pidAlive } = {}) {
   const live = liveness(isAlive(spec.tmux));
   const alive = live.alive;
   const file = findNewestSession(spec.sessionsDir);
@@ -301,7 +317,9 @@ export function scanAgent(spec, { isAlive = tmuxInspect, now = () => new Date(),
   const needsYou = state === "waiting" || state === "error";
   const isSeen = needsYou && lastActivity !== null && seen[seenKey(spec)] === lastActivity;
   const cwd = session?.cwd ?? null;
-  const reg = registration && typeof registration === "object" ? registration : null;
+  const record = registration && typeof registration === "object" ? registration : null;
+  const registeredAlive = record ? isPidAlive(record.pid) : null;
+  const reg = record && registeredAlive !== false ? record : null;
   const derivedWorkspace = live.workspace ?? cwd;
   const workspace = reg?.workspace ?? derivedWorkspace;
   const workspaceSource = reg?.workspace ? "registration" : live.workspace ? "tmux-pane" : cwd ? "session-cwd" : null;
@@ -329,8 +347,8 @@ export function scanAgent(spec, { isAlive = tmuxInspect, now = () => new Date(),
     workspaceSource,
     activeProject,
     activeProjectSource,
-    registered: reg
-      ? { startedAt: reg.startedAt, updatedAt: reg.updatedAt, harness: reg.harness, pid: reg.pid, tmux: reg.tmux, layout: reg.layout, launchScript: reg.launchScript }
+    registered: record
+      ? { startedAt: record.startedAt, updatedAt: record.updatedAt, harness: record.harness, pid: record.pid, alive: registeredAlive, tmux: record.tmux, layout: record.layout, launchScript: record.launchScript }
       : null,
     lastActivity,
     ageSeconds,
@@ -369,12 +387,12 @@ function writeAtomic(path, data) {
 
 // Scan every spec and write <boardDir>/sessions/<project>/<agent>.json plus index.json.
 // seatsDir (optional): where `mosaic launch` registrations live; read only.
-export function scan(specs, { boardDir, isAlive, now, seatsDir = null } = {}) {
+export function scan(specs, { boardDir, isAlive, now, seatsDir = null, isPidAlive } = {}) {
   if (!boardDir || !isAbsolute(boardDir)) throw new ConfigError("boardDir must be an absolute path");
   if (seatsDir !== null && (typeof seatsDir !== "string" || !isAbsolute(seatsDir))) throw new ConfigError("seatsDir must be an absolute path or null");
   const seen = loadSeen(boardDir);
   const { registrations, errors: registrationErrors } = loadRegistrations(seatsDir);
-  const records = specs.map((spec) => scanAgent(spec, { isAlive, now, seen, registration: matchRegistration(spec, registrations) }));
+  const records = specs.map((spec) => scanAgent(spec, { isAlive, now, seen, registration: matchRegistration(spec, registrations), isPidAlive }));
   for (const rec of records) {
     const dir = join(boardDir, "sessions", rec.project);
     mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -387,6 +405,7 @@ export function scan(specs, { boardDir, isAlive, now, seatsDir = null } = {}) {
     waitingOnYou: records.filter((r) => r.waitingOnYou).map(seenKey),
     seen: records.filter((r) => r.seen).map(seenKey),
     registered: records.filter((r) => r.registered).map(seenKey),
+    registrationStale: records.filter((r) => r.registered && r.registered.alive === false).map(seenKey),
     registrationErrors,
     sessions: records,
   };

packages/control-board/tests/scan.test.mjs

@@ -34,6 +34,7 @@ import {
   markSeen,
   loadRegistrations,
   matchRegistration,
+  pidAlive,
 } from "../src/scan.mjs";
 import { writeRegistration, makeRegistration } from "../../seat/src/seat.mjs";
 
@@ -444,7 +445,7 @@ test("registration: overrides task, project and workspace; every source says reg
     workspace: "/registered/workspace",
     harness: "pi",
     tmux: { socket: null, session: "a" },
-    pid: 4242,
+    pid: process.pid,
     now: () => new Date("2026-09-12T13:00:00Z"),
   });
 
@@ -459,7 +460,8 @@ test("registration: overrides task, project and workspace; every source says reg
   assert.ok(rec.registered, "registered must be non-null once a matching registration is passed");
   assert.equal(rec.registered.startedAt, registration.startedAt);
   assert.equal(rec.registered.harness, "pi");
-  assert.equal(rec.registered.pid, 4242);
+  assert.equal(rec.registered.pid, process.pid);
+  assert.equal(rec.registered.alive, true, "the default pid probe sees this test process");
   assert.deepEqual(rec.registered.tmux, { socket: null, session: "a" });
   assert.equal(rec.registered.layout, "repo");
   assert.equal(rec.registered.launchScript, join(root, "seat-dir", "launch.sh"));
@@ -501,6 +503,52 @@ test("registration: empty task and null project/workspace leave the derived valu
   assert.notEqual(rec.registered, null, "an empty task and null project/workspace still leave a registration attached");
 });
 
+test("registration: a record whose pid is gone is stale; derived values win, sources say derived, registered stays with alive false; a pid the probe cannot decide is not stale; pidAlive itself", () => {
+  const root = makeRoot();
+  const sessionsDir = join(root, "sessions");
+  writeSessionFile(sessionsDir, "s.jsonl", [
+    sessionLine({ id: "s1", timestamp: "2026-09-12T14:00:00Z", cwd: "/derived/cwd" }),
+    messageLine({ timestamp: "2026-09-12T14:00:01Z", role: "user", texts: ["derived task"] }),
+  ]);
+  const spec = { agent: "a", project: "p", sessionsDir, tmux: {} };
+  const registration = makeRegistration({
+    resolved: { seat: "a", project: "resolved-project", sessionsDir, seatDir: join(root, "seat-dir"), launchScript: join(root, "seat-dir", "launch.sh"), layout: "repo", defaultWorkspace: "/resolved/workspace" },
+    task: "registered task", project: "registered-project", workspace: "/registered/workspace", harness: "pi", pid: 4242,
+  });
+  const probed = [];
+  const rec = scanAgent(spec, { isAlive: () => ({ alive: true, workspace: null }), now: GATE_NOW, registration, isPidAlive: (pid) => { probed.push(pid); return false; } });
+  assert.deepEqual(probed, [4242], "the probe is asked about the recorded pid");
+  assert.equal(rec.task, "derived task");
+  assert.equal(rec.taskSource, "first-user-message");
+  assert.equal(rec.activeProject, null, "no git root above /derived/cwd");
+  assert.equal(rec.activeProjectSource, null);
+  assert.equal(rec.workspace, "/derived/cwd");
+  assert.equal(rec.workspaceSource, "session-cwd");
+  assert.ok(rec.registered, "a stale record is still reported, not hidden");
+  assert.equal(rec.registered.alive, false);
+  assert.equal(rec.registered.pid, 4242);
+  assert.equal(rec.registered.startedAt, registration.startedAt);
+
+  // null from the probe (no pid recorded) keeps the override.
+  const undecided = scanAgent(spec, { isAlive: () => true, now: GATE_NOW, registration, isPidAlive: () => null });
+  assert.equal(undecided.task, "registered task");
+  assert.equal(undecided.registered.alive, null);
+
+  // scan(): the stale row is listed under registrationStale and still under registered.
+  const boardDir = join(root, "board");
+  const seatsDir = join(root, "seats");
+  writeRegistration(seatsDir, registration);
+  const index = scan([spec], { boardDir, seatsDir, isAlive: () => true, now: GATE_NOW, isPidAlive: () => false });
+  assert.deepEqual(index.registered, ["p/a"]);
+  assert.deepEqual(index.registrationStale, ["p/a"]);
+  assert.equal(index.sessions[0].taskSource, "first-user-message");
+
+  assert.equal(pidAlive(process.pid), true);
+  assert.equal(pidAlive(null), null);
+  assert.equal(pidAlive(0), null);
+  assert.equal(pidAlive(-1), null);
+});
+
 test("registration: no registration leaves the Gate A fields exactly as before, and registered is null", () => {
   const root = makeRoot();
   const repo = join(root, "repo");
@@ -643,6 +691,7 @@ test("scan: writes the registration override to disk; index.json carries registe
   const spec = { agent: "a", project: "p", sessionsDir, tmux: {} };
   const index = scan([spec], { boardDir, seatsDir, isAlive: () => ({ alive: true, workspace: null }), now: GATE_NOW });
   assert.deepEqual(index.registered, ["p/a"]);
+  assert.deepEqual(index.registrationStale, [], "a record with pid null is never stale");
   assert.deepEqual(index.registrationErrors, []);
   const onDisk = JSON.parse(readFileSync(join(boardDir, "sessions", "p", "a.json"), "utf8"));
   assert.equal(onDisk.task, "registered task");

packages/control-board/tests/serve.test.mjs

@@ -567,7 +567,7 @@ test("CLI: scan --print marks a seen row with 's' and the summary line ends with
   const row = r.stdout.split("\n").find((l) => l.includes("agent1"));
   assert.ok(row, `expected an agent1 row in:\n${r.stdout}`);
   assert.equal(row[0], "s");
-  assert.match(r.stdout, /1 seen, 0 registered\)\s*$/m);
+  assert.match(r.stdout, /1 seen, 0 registered, 0 stale\)\s*$/m);
 });
 
 // ---------------------------------------------------------------------------