Add mosaic launch <seat> with seat registration for the control board (#1504)

New package packages/seat and wrapper scripts/mosaic. `launch <seat>` writes
<dataRoot>/seats/<layout>/<seat>/registration.json and then execs the seat's
launch.sh unchanged; `seat task <seat> <text>` edits the task only. The board
reads registrations, matches by sessions directory, and lets a registered
task, project or workspace override the derived value with a source tag.
The four repository launch scripts register themselves unless already
registered or run with --check. Fleet launchers untouched; one-liner on the
plan page.

Review found the record path keyed by seat name alone (repo and fleet
"darkwing" would collide); fixed by keying on layout. Also: the Pi pin
refusal now names installed and required versions.

Tests: seat 15, control-board 89, launch scripts 5, registry 69, config 24.

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

packages/control-board/src/cli.mjs

@@ -40,8 +40,9 @@ async function main() {
   const specs = [...discoverRepoAgents(opts.repo), ...(opts.fleet === "none" ? [] : discoverFleetAgents(opts.fleet))];
   const isAlive = opts.liveness === "tmux" ? tmuxInspect : () => true;
   const boardDir = join(dataRoot, "board");
+  const seatsDir = join(dataRoot, "seats");
   if (opts.command === "serve") {
-    const server = await startServer({ host: opts.host, port: opts.port, specs, boardDir, isAlive });
+    const server = await startServer({ host: opts.host, port: opts.port, specs, boardDir, isAlive, seatsDir });
     const addr = server.address();
     process.stdout.write(`control board: http://${opts.host}:${addr.port}/  (${specs.length} agents; board files in ${boardDir}; Ctrl-C to stop)\n`);
     const stop = () => server.close(() => process.exit(0));
@@ -49,7 +50,8 @@ async function main() {
     process.on("SIGTERM", stop);
     return;
   }
-  const index = scan(specs, { boardDir, isAlive });
+  const index = scan(specs, { boardDir, isAlive, seatsDir });
+  for (const line of index.registrationErrors) process.stderr.write(`registration skipped: ${line}\n`);
   if (opts.print) {
     for (const s of index.sessions) {
       const flag = s.waitingOnYou ? "*" : s.seen ? "s" : " ";
@@ -57,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)\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`);
 }
 
 main().catch((err) => {

packages/control-board/src/page.html

@@ -65,6 +65,7 @@
   .msg-text,.msg-error{display:block;max-width:36ch;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
   .task-text{display:block;max-width:28ch;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
   .unknown{color:var(--muted);font-style:italic}
+  .source{color:var(--muted);font-size:.75em;margin-left:.35em;white-space:nowrap}
   .detail-row td{background:var(--raised)}
   .detail-list{display:grid;grid-template-columns:auto 1fr;gap:4px 14px;margin:0;font-size:.85rem;font-family:var(--mono)}
   .detail-list dt{color:var(--muted);font-family:var(--font)}
@@ -184,6 +185,21 @@
     return '<button type="button" class="seen-toggle" data-seen="true"' + attrs + ' title="I have read this; hide it from Waiting on you until the agent writes again">Seen</button>';
   }
 
+  var SOURCE_LABEL = { "registration": "registered", "first-user-message": "first message", "tmux-pane": "tmux pane", "session-cwd": "session cwd", "workspace-git-root": "git root" };
+  function sourceLabel(source) { return SOURCE_LABEL[source] || source; }
+  function sourceTag(source) { return source ? '<span class="source" title="source: ' + esc(source) + '">' + esc(sourceLabel(source)) + "</span>" : ""; }
+  function fromSource(source) { return source ? " (from " + esc(sourceLabel(source)) + ")" : ""; }
+  function registeredText(reg) {
+    if (!reg) return "no (not started through mosaic launch)";
+    var parts = ["started " + esc(reg.startedAt || "—")];
+    if (reg.updatedAt) parts.push("task updated " + esc(reg.updatedAt));
+    if (reg.harness) parts.push("harness " + esc(reg.harness));
+    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");
+    return parts.join("; ");
+  }
+
   function buildRowPair(rec, showProject) {
     var idx = rowIdx++;
     var key = (showProject ? "waiting:" : "group:") + [rec.project, rec.agent].join("/");
@@ -193,12 +209,14 @@
       ? '<span class="msg-error" title="' + esc(rec.lastError) + '">' + esc(rec.lastError) + "</span>"
       : '<span class="msg-text" title="' + esc(rec.lastAssistantText || "") + '">' + esc(rec.lastAssistantText || "—") + "</span>";
     var projectCell = showProject ? "<td>" + esc(rec.project) + "</td>" : "";
-    // Gate A fields: derived from the log and tmux, or "unknown". Never guessed.
+    // Gate A fields: from the seat's registration (mosaic launch), else derived
+    // from the log and tmux, else "unknown". Never guessed. The source tag on
+    // the row says which one is shown.
     var task = rec.task
-      ? '<span class="task-text" title="' + esc(rec.task) + '">' + esc(rec.task) + "</span>"
+      ? '<span class="task-text" title="' + esc(rec.task) + '">' + esc(rec.task) + "</span>" + sourceTag(rec.taskSource)
       : '<span class="unknown">unknown</span>';
     var activeProject = rec.activeProject
-      ? '<span title="' + esc(rec.workspace || "") + '">' + esc(rec.activeProject) + "</span>"
+      ? '<span title="' + esc(rec.workspace || "") + '">' + esc(rec.activeProject) + "</span>" + sourceTag(rec.activeProjectSource)
       : '<span class="unknown" title="' + esc(rec.workspace || "") + '">unknown</span>';
     var main =
       '<tr class="' + cls + '">' +
@@ -219,9 +237,10 @@
       '<dl class="detail-list">' +
       "<dt>Session ID</dt><dd>" + esc(rec.sessionId || "—") + "</dd>" +
       "<dt>Session file</dt><dd>" + esc(rec.sessionFile || "—") + "</dd>" +
-      "<dt>Task</dt><dd>" + (rec.task ? esc(rec.task) : "unknown") + "</dd>" +
-      "<dt>Active project</dt><dd>" + (rec.activeProject ? esc(rec.activeProject) : "unknown") + "</dd>" +
-      "<dt>Workspace</dt><dd>" + (rec.workspace ? esc(rec.workspace) : "unknown") + (rec.workspaceSource ? " (from " + esc(rec.workspaceSource) + ")" : "") + "</dd>" +
+      "<dt>Task</dt><dd>" + (rec.task ? esc(rec.task) : "unknown") + fromSource(rec.taskSource) + "</dd>" +
+      "<dt>Active project</dt><dd>" + (rec.activeProject ? esc(rec.activeProject) : "unknown") + fromSource(rec.activeProjectSource) + "</dd>" +
+      "<dt>Workspace</dt><dd>" + (rec.workspace ? esc(rec.workspace) : "unknown") + fromSource(rec.workspaceSource) + "</dd>" +
+      "<dt>Registered</dt><dd>" + registeredText(rec.registered) + "</dd>" +
       "<dt>Session cwd</dt><dd>" + esc(rec.cwd || "—") + "</dd>" +
       "<dt>Tmux session</dt><dd>" + tmux + "</dd>" +
       "<dt>Last activity</dt><dd>" + esc(rec.lastActivity || "—") + "</dd>" +

packages/control-board/src/scan.mjs

@@ -17,6 +17,7 @@ import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSy
 import { join, basename, isAbsolute, resolve } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
+import { readRegistration, samePath, SeatError, LAYOUTS } from "../../seat/src/seat.mjs";
 
 export const STATES = Object.freeze(["working", "waiting", "error", "offline", "idle", "unknown"]);
 const TEXT_LIMIT = 240;
@@ -243,15 +244,52 @@ function liveness(result) {
   return { alive: result ?? null, workspace: null };
 }
 
+// Registrations written by `mosaic launch <seat>` (packages/seat): one
+// record per seat under <dataRoot>/seats/<layout>/<seat>/registration.json. Returns
+// the readable records plus one error line per unreadable one; a bad record
+// must not take the whole board down, but it is not silently dropped either.
+export function loadRegistrations(seatsDir) {
+  const registrations = [];
+  const errors = [];
+  if (!seatsDir || !existsSync(seatsDir)) return { registrations, errors };
+  for (const layout of LAYOUTS) {
+    const layoutDir = join(seatsDir, layout);
+    if (!existsSync(layoutDir) || !statSync(layoutDir).isDirectory()) continue;
+    for (const seat of readdirSync(layoutDir).sort()) {
+      if (!statSync(join(layoutDir, seat)).isDirectory()) continue;
+      try {
+        const rec = readRegistration(seatsDir, seat, layout);
+        if (rec) registrations.push(rec);
+      } catch (err) {
+        if (!(err instanceof SeatError)) throw err;
+        errors.push(`seat ${layout}/${seat}: ${err.message}`);
+      }
+    }
+  }
+  return { registrations, errors };
+}
+
+// A registration belongs to a row when it names the same sessions directory.
+// Seat names alone are not enough: the repo and fleet layouts both have a
+// "darkwing", and they are different seats.
+export function matchRegistration(spec, registrations) {
+  return registrations.find((r) => r.sessionsDir && samePath(r.sessionsDir, spec.sessionsDir)) ?? null;
+}
+
 // One agent -> one status record.
 //
 // Three fields answer "what is this seat doing, and where" (Gate A ask,
-// 2026-09-12). Each is derived, never guessed; null means "unknown".
-//   task          the session's first user message. The log has no task
-//                 envelope entry, so this is the only assignment signal it holds.
-//   workspace     the live pane path from tmux, else the session log's cwd.
-//   activeProject basename of the nearest git repo root above the workspace.
-export function scanAgent(spec, { isAlive = tmuxInspect, now = () => new Date(), seen = {} } = {}) {
+// 2026-09-12). Each is derived, never guessed; null means "unknown". A seat
+// started through `mosaic launch` has a registration, and a registered task,
+// project or workspace wins over the derived value; the *Source field says
+// which one the row shows.
+//   task          registration.task, else the session's first user message
+//                 (the log has no task envelope entry).
+//   workspace     registration.workspace, else the live pane path from tmux,
+//                 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 } = {}) {
   const live = liveness(isAlive(spec.tmux));
   const alive = live.alive;
   const file = findNewestSession(spec.sessionsDir);
@@ -263,8 +301,17 @@ 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 workspace = live.workspace ?? cwd;
-  const repoRoot = workspace ? findRepoRoot(workspace) : null;
+  const reg = registration && typeof registration === "object" ? registration : null;
+  const derivedWorkspace = live.workspace ?? cwd;
+  const workspace = reg?.workspace ?? derivedWorkspace;
+  const workspaceSource = reg?.workspace ? "registration" : live.workspace ? "tmux-pane" : cwd ? "session-cwd" : null;
+  const repoRoot = derivedWorkspace ? findRepoRoot(derivedWorkspace) : null;
+  const derivedProject = repoRoot ? basename(repoRoot) : null;
+  const activeProject = reg?.project ?? derivedProject;
+  const activeProjectSource = reg?.project ? "registration" : derivedProject ? "workspace-git-root" : null;
+  const firstUserText = session?.firstUserText ?? null;
+  const task = reg?.task ? reg.task : firstUserText;
+  const taskSource = reg?.task ? "registration" : firstUserText ? "first-user-message" : null;
   return {
     agent: spec.agent,
     project: spec.project,
@@ -276,11 +323,15 @@ export function scanAgent(spec, { isAlive = tmuxInspect, now = () => new Date(),
     sessionFile: file,
     sessionId: session?.sessionId ?? null,
     cwd,
-    task: session?.firstUserText ?? null,
-    taskSource: session?.firstUserText ? "first-user-message" : null,
+    task,
+    taskSource,
     workspace,
-    workspaceSource: live.workspace ? "tmux-pane" : cwd ? "session-cwd" : null,
-    activeProject: repoRoot ? basename(repoRoot) : null,
+    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 }
+      : null,
     lastActivity,
     ageSeconds,
     lastAssistantText: session?.lastAssistantText ?? null,
@@ -317,10 +368,13 @@ function writeAtomic(path, data) {
 }
 
 // Scan every spec and write <boardDir>/sessions/<project>/<agent>.json plus index.json.
-export function scan(specs, { boardDir, isAlive, now } = {}) {
+// seatsDir (optional): where `mosaic launch` registrations live; read only.
+export function scan(specs, { boardDir, isAlive, now, seatsDir = null } = {}) {
   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 records = specs.map((spec) => scanAgent(spec, { isAlive, now, seen }));
+  const { registrations, errors: registrationErrors } = loadRegistrations(seatsDir);
+  const records = specs.map((spec) => scanAgent(spec, { isAlive, now, seen, registration: matchRegistration(spec, registrations) }));
   for (const rec of records) {
     const dir = join(boardDir, "sessions", rec.project);
     mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -332,6 +386,8 @@ export function scan(specs, { boardDir, isAlive, now } = {}) {
     counts: Object.fromEntries(STATES.map((s) => [s, records.filter((r) => r.state === s).length])),
     waitingOnYou: records.filter((r) => r.waitingOnYou).map(seenKey),
     seen: records.filter((r) => r.seen).map(seenKey),
+    registered: records.filter((r) => r.registered).map(seenKey),
+    registrationErrors,
     sessions: records,
   };
   mkdirSync(boardDir, { recursive: true, mode: 0o700 });

packages/control-board/src/serve.mjs

@@ -67,7 +67,7 @@ export function loadPage(path = join(import.meta.dirname, "page.html")) {
 }
 
 // specs: agent specs to scan on each request. boardDir: where scan writes.
-export function createServer({ specs, boardDir, isAlive, now, page = loadPage() }) {
+export function createServer({ specs, boardDir, isAlive, now, seatsDir = null, page = loadPage() }) {
   return createHttpServer((req, res) => {
     const url = new URL(req.url, "http://localhost");
     if (req.method === "POST" && url.pathname === "/api/seen") {
@@ -79,7 +79,7 @@ export function createServer({ specs, boardDir, isAlive, now, page = loadPage()
             return sendJson(res, 400, { error: err.message });
           }
           try {
-            sendJson(res, 200, scan(specs, { boardDir, isAlive, now }));
+            sendJson(res, 200, scan(specs, { boardDir, isAlive, now, seatsDir }));
           } catch (err) {
             sendJson(res, 500, { error: err.message });
           }
@@ -97,7 +97,7 @@ export function createServer({ specs, boardDir, isAlive, now, page = loadPage()
     if (url.pathname === "/api/board") {
       let index;
       try {
-        index = scan(specs, { boardDir, isAlive, now });
+        index = scan(specs, { boardDir, isAlive, now, seatsDir });
       } catch (err) {
         res.writeHead(500, { "content-type": "application/json", "cache-control": "no-store" });
         return res.end(JSON.stringify({ error: err.message }) + "\n");