@davidbalzan/groundwork-console 0.1.0

package/dist/kitresolve.js

@@ -0,0 +1,79 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const REQUIRES = { seam: "^0.1.0", mcp: "^0.23.0", groundwork: "^0.3.0", playbook: "^0.5.0" };
+const which = (bin) => { try {
+    return execFileSync("which", [bin], { encoding: "utf8" }).trim() || null;
+}
+catch {
+    return null;
+} };
+export const hasKitCheckout = (kitPath) => existsSync(path.join(kitPath, "packages/groundwork/src/cli.mjs"));
+/** argv (for `node`) to run the groundwork CLI: kit checkout file, else the global `groundwork` bin (a JS file with a shebang). */
+export function groundworkCli(kitPath) {
+    const local = path.join(kitPath, "packages/groundwork/src/cli.mjs");
+    if (existsSync(local))
+        return local;
+    const g = which("groundwork");
+    return g ? realpathSync(g) : null;
+}
+export function playbookCli(kitPath) {
+    const local = path.join(kitPath, "packages/coord-playbook/bin/install.mjs");
+    if (existsSync(local))
+        return local;
+    const g = which("agent-coordination");
+    return g ? realpathSync(g) : null;
+}
+/** MCP server entry: kit checkout dist, else the global `agent-coord-mcp` bin (which is dist/server.js). */
+export function mcpServer(kitPath) {
+    const local = path.join(kitPath, "packages/coord-mcp/dist/server.js");
+    if (existsSync(local))
+        return local;
+    const g = which("agent-coord-mcp");
+    return g ? realpathSync(g) : null;
+}
+const pkgVersionNear = (file) => { if (!file)
+    return null; let d = path.dirname(file); for (let i = 0; i < 6; i++) {
+    const pj = path.join(d, "package.json");
+    if (existsSync(pj)) {
+        try {
+            return JSON.parse(readFileSync(pj, "utf8")).version ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    d = path.dirname(d);
+} return null; };
+/** Installed versions the console actually resolves to (seam from node_modules; the rest from wherever the CLIs came from). */
+export function installedVersions(kitPath) {
+    let seam = null;
+    try {
+        seam = pkgVersionNear(fileURLToPath(import.meta.resolve("@davidbalzan/groundwork-seam")));
+    }
+    catch { /* not installed */ }
+    const gw = groundworkCli(kitPath), pb = playbookCli(kitPath), mcp = mcpServer(kitPath);
+    return { seam, groundwork: pkgVersionNear(gw), playbook: pkgVersionNear(pb), mcp: pkgVersionNear(mcp), paths: { groundwork: gw, playbook: pb, mcp, kitCheckout: hasKitCheckout(kitPath) ? kitPath : null } };
+}
+/** Minimal caret-range check (^a.b.c): same major (or same minor when major is 0), and >= min. */
+export function satisfies(v, range) {
+    if (!v)
+        return null;
+    const m = range.match(/^\^(\d+)\.(\d+)\.(\d+)$/);
+    if (!m)
+        return null;
+    const [a, b, c] = v.split(".").map(Number);
+    const [x, y, z] = m.slice(1).map(Number);
+    if (a !== x)
+        return false;
+    if (x === 0 && b !== y)
+        return false;
+    return a > x || b > y || (b === y && c >= z);
+}
+export function requiresReport(kitPath) {
+    const inst = installedVersions(kitPath);
+    const check = (k) => ({ required: REQUIRES[k], installed: inst[k], ok: satisfies(inst[k], REQUIRES[k]) });
+    const r = { seam: check("seam"), mcp: check("mcp"), groundwork: check("groundwork"), playbook: check("playbook") };
+    return { ...r, paths: inst.paths, ok: Object.values(r).every((x) => x.ok !== false) };
+}

package/dist/knowledge.js

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+/* Global knowledge repo (cross-project ADRs + dated lessons) — the thing `groundwork knowledge` configures.
+   Resolution mirrors packages/groundwork/src/lib/config.mjs: $GROUNDWORK_KNOWLEDGE → ~/.config/groundwork/config.json knowledgeRepo → unset. */
+export function knowledgePath() {
+    if (process.env.GROUNDWORK_KNOWLEDGE)
+        return { path: process.env.GROUNDWORK_KNOWLEDGE, source: "env GROUNDWORK_KNOWLEDGE" };
+    const cfg = path.join(process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config"), "groundwork", "config.json");
+    try {
+        const j = JSON.parse(readFileSync(cfg, "utf8"));
+        if (j.knowledgeRepo)
+            return { path: j.knowledgeRepo, source: `groundwork config (${cfg})` };
+    }
+    catch { /* unset */ }
+    return { path: null, source: null };
+}
+/** ADRs from INDEX.md tables (id · [title](adr/file) · Enf · tags · date, grouped by the ## heading above), plus any adr/*.md not in the index. */
+export function knowledgeIndex() {
+    const { path: root, source } = knowledgePath();
+    if (!root || !existsSync(root))
+        return { path: root, source, exists: false, index: null, adrs: [], notes: [], sections: [] };
+    const indexFile = ["INDEX.md", "README.md"].find((f) => existsSync(path.join(root, f))) ?? null;
+    const adrs = [];
+    const sections = [];
+    if (indexFile) {
+        let section = null;
+        for (const line of readFileSync(path.join(root, indexFile), "utf8").split("\n")) {
+            const h = line.match(/^##\s+(.+)$/);
+            if (h) {
+                section = h[1].trim();
+                if (!sections.includes(section))
+                    sections.push(section);
+                continue;
+            }
+            const m = line.match(/^\|\s*(\d{3,4})\s*\|\s*\[([^\]]+)\]\(([^)]+)\)\s*\|\s*([^|]*)\|\s*([^|]*)\|\s*([^|]*)\|/);
+            if (m)
+                adrs.push({ id: m[1], title: m[2].trim(), file: m[3].trim(), enf: m[4].replace(/[*_`]/g, "").trim() || null, tags: m[5].split(",").map((t) => t.trim()).filter(Boolean), date: m[6].trim() || null, section });
+        }
+    }
+    const adrDir = path.join(root, "adr");
+    if (existsSync(adrDir))
+        for (const f of readdirSync(adrDir).filter((n) => n.endsWith(".md")).sort()) {
+            const rel = `adr/${f}`;
+            if (adrs.some((a) => a.file === rel))
+                continue;
+            const id = f.match(/^(\d{3,4})/)?.[1] ?? f;
+            const title = firstHeading(path.join(adrDir, f)) ?? f.replace(/^\d+-/, "").replace(/\.md$/, "").replace(/-/g, " ");
+            adrs.push({ id, title, file: rel, enf: null, tags: [], date: null, section: "(not in INDEX)" });
+        }
+    const notesDir = path.join(root, "notes");
+    const notes = existsSync(notesDir) ? readdirSync(notesDir).filter((n) => n.endsWith(".md") && !n.startsWith("_")).sort().map((f) => ({ file: `notes/${f}`, title: firstHeading(path.join(notesDir, f)), bytes: readFileSync(path.join(notesDir, f)).length })) : [];
+    return { path: root, source, exists: true, index: indexFile, adrs, notes, sections };
+}
+function firstHeading(file) { try {
+    return readFileSync(file, "utf8").split("\n").find((l) => /^#\s+/.test(l))?.replace(/^#\s+/, "").trim() ?? null;
+}
+catch {
+    return null;
+} }
+export function knowledgeDoc(rel) {
+    const { path: root } = knowledgePath();
+    if (!root)
+        return null;
+    const safe = path.normalize(rel).replace(/^(\.\.[/\\])+/, "").replace(/^[/\\]+/, "");
+    if (!safe.endsWith(".md"))
+        return null;
+    const full = path.resolve(root, safe);
+    if (!full.startsWith(path.resolve(root) + path.sep) || !existsSync(full))
+        return null;
+    return { path: safe, full, source: readFileSync(full, "utf8") };
+}

package/dist/mcp.js

@@ -0,0 +1,106 @@
+/* MCP clients for the coord bus. One stdio session per identity (the server binds identity per session):
+   - groundwork-console · role automation — no record authority, no transport; used for reads and rule-driven sends.
+   - david       · role human      — David's own voice (replies, decision locks); only when bus writes are on.
+   Bus writes are refused unless the runtime switch is on (init from GROUNDWORK_CONSOLE_BUS_WRITES=1). */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import path from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { mcpServer } from "./kitresolve.js";
+const IDENTITIES = {
+    "groundwork-console": { agentId: "groundwork-console", project: "groundwork-console", role: { roleId: "automation", displayName: "groundwork-console" } },
+    david: { agentId: "david", project: "groundwork-console", role: { roleId: "human", displayName: "David" } },
+};
+export const AGENT_ID = "groundwork-console";
+export const READ_ONLY_TOOLS = new Set(["doctor", "list_agents", "list_rooms", "list_scopes", "status", "ping", "read_messages", "retrieve_room_history", "retrieve_message", "list_work"]);
+export const WRITE_TOOLS_GATED = new Set(["send_message", "post_status", "prune", "force_unregister", "unregister", "join_room", "leave_room", "delete_room", "set_room_topic", "set_room_motd", "import_work", "export_work"]);
+const SWITCH_FILE = path.join(homedir(), ".groundwork-console", "switches.json");
+function loadSwitches() {
+    let saved = {};
+    try {
+        if (existsSync(SWITCH_FILE))
+            saved = JSON.parse(readFileSync(SWITCH_FILE, "utf8"));
+    }
+    catch { /* fresh */ }
+    const bus = saved.bus ?? { enabled: false, changedAt: 0, by: "default" };
+    const seam = saved.seam ?? { enabled: false, changedAt: 0, by: "default" };
+    if (process.env.GROUNDWORK_CONSOLE_BUS_WRITES === "1") {
+        bus.enabled = true;
+        bus.by = "env";
+    }
+    if (process.env.GROUNDWORK_CONSOLE_SEAM_WRITES === "1") {
+        seam.enabled = true;
+        seam.by = "env";
+    }
+    return { bus, seam };
+}
+const loaded = loadSwitches();
+export const busWrites = loaded.bus;
+export const seamWrites = loaded.seam;
+export const BUS_WRITES = busWrites.enabled; // legacy import
+export function saveSwitches() { mkdirSync(path.dirname(SWITCH_FILE), { recursive: true }); writeFileSync(SWITCH_FILE, JSON.stringify({ bus: busWrites, seam: seamWrites, file: SWITCH_FILE }, null, 2)); }
+export const SWITCHES_FILE = SWITCH_FILE;
+export class BusClient {
+    kitPath;
+    coordDir;
+    identity;
+    mcpPath;
+    client = null;
+    connecting = null;
+    constructor(kitPath, coordDir, identity = "groundwork-console", mcpPath) {
+        this.kitPath = kitPath;
+        this.coordDir = coordDir;
+        this.identity = identity;
+        this.mcpPath = mcpPath;
+    }
+    get serverPath() { return this.mcpPath ?? mcpServer(this.kitPath) ?? path.join(this.kitPath, "packages/coord-mcp/dist/server.js"); }
+    get agentId() { return IDENTITIES[this.identity].agentId; }
+    async connect(log) {
+        if (this.client)
+            return this.client;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = (async () => {
+            const server = this.serverPath;
+            const id = IDENTITIES[this.identity];
+            if (!existsSync(server))
+                throw new Error(`agent-coord-mcp not built at ${server}`);
+            log?.(`spawning ${server} as ${id.agentId} (${id.role.roleId})`);
+            const transport = new StdioClientTransport({ command: process.execPath, args: [server], env: { ...process.env, AGENT_COORD_DIR: this.coordDir, AGENT_COORD_ID: id.agentId }, stderr: "pipe" });
+            const client = new Client({ name: `groundwork-console/${id.agentId}`, version: "0.1.0" });
+            await client.connect(transport);
+            const reg = await client.callTool({ name: "register", arguments: { agentId: id.agentId, project: id.project, role: id.role, force: true } });
+            log?.(`register → ${JSON.stringify(reg.structuredContent ?? textOf(reg)).slice(0, 160)}`);
+            this.client = client;
+            return client;
+        })();
+        try {
+            return await this.connecting;
+        }
+        finally {
+            this.connecting = null;
+        }
+    }
+    async call(name, args, log) {
+        const isWrite = WRITE_TOOLS_GATED.has(name);
+        if (!READ_ONLY_TOOLS.has(name) && !isWrite)
+            throw new Error(`tool ${name} is not allow-listed`);
+        if (isWrite && !busWrites.enabled)
+            throw new Error(`bus writes are off (switch it on in the header, or GROUNDWORK_CONSOLE_BUS_WRITES=1)`);
+        const c = await this.connect(log);
+        log?.(`→ ${name} ${JSON.stringify(args).slice(0, 300)}`);
+        const res = await c.callTool({ name, arguments: { agentId: this.agentId, from: this.agentId, ...args } });
+        const out = res.structuredContent ?? parseText(textOf(res));
+        log?.(`← ${name} ok`);
+        return out;
+    }
+    async close() { await this.client?.close(); this.client = null; }
+}
+function textOf(r) { return (r.content ?? []).map((c) => c.text ?? "").join("\n"); }
+function parseText(t) { try {
+    return JSON.parse(t);
+}
+catch {
+    return t;
+} }

package/dist/notify.js

@@ -0,0 +1,85 @@
+/* Notifications: one feed of things worth David's attention, aggregated from what the API already watches.
+   Kinds: dm (new DM to david) · decision (DAVID_DECISION in a watched room) · blocker (BLOCKER in a watched room) · run.failed · run.side-effect (a side-effecting run finished) · rule.sent (engine really sent).
+   Watched rooms = rooms linked to configured projects. Ring buffer; SSE fan-out; the client keeps its own "seen" watermark. */
+import { roomMessages } from "./bus.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+const RING = 300;
+export class Notifier {
+    cfg;
+    runs;
+    events;
+    buffer = [];
+    listeners = new Set();
+    lastRoomTs = new Map();
+    seenDm = new Set();
+    seq = 0;
+    constructor(cfg, runs, events) {
+        this.cfg = cfg;
+        this.runs = runs;
+        this.events = events;
+    }
+    recent(limit = 100) { return this.buffer.slice(-limit).reverse(); }
+    subscribe(fn) { this.listeners.add(fn); return () => this.listeners.delete(fn); }
+    emit(n) { const full = { id: `n-${Date.now()}-${++this.seq}`, ...n }; this.buffer.push(full); if (this.buffer.length > RING)
+        this.buffer.shift(); for (const l of this.listeners)
+        l(full); }
+    start(intervalMs = 15_000) {
+        // baseline: remember current tails so we only notify on NEW items
+        this.pollRooms(true);
+        this.pollInbox(true);
+        setInterval(() => { this.pollRooms(false); this.pollInbox(false); }, intervalMs).unref();
+        this.runs.subscribe((r) => {
+            if (r.status === "failed")
+                this.emit({ ts: Date.now(), kind: "run.failed", title: `Run failed · ${r.label}`, body: r.error, project: r.project, link: `/runs?run=${r.id}`, urgent: true });
+            else if (r.status === "ok" && r.sideEffects)
+                this.emit({ ts: Date.now(), kind: "run.side-effect", title: `Done · ${r.label}`, project: r.project, link: `/runs?run=${r.id}`, urgent: false });
+        });
+        this.events.subscribe((e) => { for (const a of e.actions)
+            if (a.sent && !this.buffer.some((n) => n.link === `/runs?run=${a.runId}`))
+                this.emit({ ts: Date.now(), kind: "rule.sent", title: `Rule sent · ${a.ruleId}`, body: `${a.prefix ?? ""} ${a.text ?? ""} → ${a.to ?? "#" + a.room}`, project: e.project, link: `/runs?run=${a.runId}`, urgent: false }); });
+    }
+    pollRooms(baseline) {
+        for (const p of this.cfg.projects) {
+            if (!p.room)
+                continue;
+            const msgs = roomMessages(this.cfg.coordDir, p.room, 50);
+            const last = this.lastRoomTs.get(p.room) ?? 0;
+            const fresh = msgs.filter((m) => typeof m.ts === "number" && m.ts > last && !m.system);
+            const newest = Math.max(last, ...msgs.map((m) => (typeof m.ts === "number" ? m.ts : 0)));
+            this.lastRoomTs.set(p.room, newest);
+            if (baseline)
+                continue;
+            for (const m of fresh) {
+                const t = String(m.text ?? "");
+                if (/^DAVID_DECISION\b/.test(t))
+                    this.emit({ ts: m.ts, kind: "decision", title: `Needs David · ${p.name}`, body: t.replace(/^DAVID_DECISION:?\s*/, "").slice(0, 240), project: p.name, room: p.room, from: m.from, link: `/bus?room=${p.room}&msg=${m.id}`, urgent: true });
+                else if (/^BLOCKER\b/.test(t))
+                    this.emit({ ts: m.ts, kind: "blocker", title: `BLOCKER · #${p.room}`, body: t.replace(/^BLOCKER:?\s*/, "").slice(0, 240), project: p.name, room: p.room, from: m.from, link: `/bus?room=${p.room}&msg=${m.id}`, urgent: true });
+            }
+        }
+    }
+    pollInbox(baseline) {
+        const file = path.join(this.cfg.coordDir, "inbox", "david.jsonl");
+        if (!existsSync(file))
+            return;
+        const lines = readFileSync(file, "utf8").split("\n").filter(Boolean);
+        for (const l of lines) {
+            let m;
+            try {
+                m = JSON.parse(l);
+            }
+            catch {
+                continue;
+            }
+            const id = String(m.id ?? l.length);
+            if (this.seenDm.has(id))
+                continue;
+            this.seenDm.add(id);
+            if (baseline)
+                continue;
+            const t = String(m.text ?? "");
+            this.emit({ ts: m.ts ?? Date.now(), kind: "dm", title: `DM from ${m.from}`, body: t.slice(0, 240), from: m.from, link: `/bus?view=inbox`, urgent: /^(BLOCKER|DAVID_DECISION)\b/.test(t) });
+        }
+    }
+}

package/dist/provision.js

@@ -0,0 +1,124 @@
+/* Spawn an agent into tmux, the playbook way (coord-claude-layout.sh pattern):
+   window `fleet-<project>` (created if missing) → new pane cd'd to the repo → launch harness → wait → inject `<skill> --id=<agentId> [--lane]` + `/color` → wait for the agent to register on the bus.
+   This IS a side effect (processes + keystrokes into a pane the console just created). It never types into an existing agent's pane. */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+const run = promisify(execFile);
+const tmux = async (...args) => (await run("tmux", args, { timeout: 8_000 })).stdout.trim();
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const HARNESS_CMD = { claude: "claude --dangerously-skip-permissions", grok: "grok", codex: "codex", opencode: "opencode" };
+export const ROLE_SKILL = { coordinator: "/coordinator", worker: "/coord-worker", qa: "/coord-qa", ci: "/coord-ci", aide: "/coord-aide", audit: "/coord-audit" };
+export const ROLE_COLOR = { coordinator: "green", aide: "pink", qa: "yellow", ci: "orange", worker: "blue", audit: "magenta" };
+const CLAUDE_HARNESS_ONLY = new Set(["claude"]); // /color and slash-skills are Claude Code; other harnesses get the skill text as a plain instruction
+async function fleetWindow(project, startDir, log) {
+    const win = `fleet-${project}`;
+    const wins = (await tmux("list-windows", "-a", "-F", "#{session_name}:#{window_index}\t#{window_name}")).split("\n").filter(Boolean).map((l) => l.split("\t"));
+    const hit = wins.find(([, name]) => name === win);
+    if (hit) {
+        log(`window ${win} exists (${hit[0]})`);
+        return { target: hit[0], freshPane: null };
+    }
+    const session = (await tmux("list-sessions", "-F", "#{session_name}")).split("\n")[0];
+    const pane = await tmux("new-window", "-d", "-t", `${session}:`, "-n", win, "-c", startDir, "-P", "-F", "#{pane_id}");
+    log(`created window ${win} in session ${session} (first pane ${pane} reused for the first agent — no spare shell)`);
+    return { target: `${session}:${win}`, freshPane: pane };
+}
+export async function spawnAgent(req, isRegistered, log, isAttached = () => true) {
+    if (!/^[a-z0-9][a-z0-9-_]*$/i.test(req.agentId))
+        throw new Error("agentId: letters, digits, - _");
+    if (isRegistered(req.agentId))
+        throw new Error(`${req.agentId} is already registered on the bus`);
+    if (!existsSync(req.repoPath))
+        throw new Error("repo path missing");
+    const { target, freshPane } = await fleetWindow(req.project, req.repoPath, log);
+    // reuse the fresh window's first pane; otherwise split and tile so N agents fit
+    const paneId = freshPane ?? await tmux("split-window", "-t", target, "-c", req.repoPath, "-P", "-F", "#{pane_id}");
+    if (!freshPane)
+        await tmux("select-layout", "-t", target, "tiled");
+    await tmux("select-pane", "-t", paneId, "-T", req.agentId);
+    log(`pane ${paneId} in ${target} (cwd ${req.repoPath}), title ${req.agentId}`);
+    const cmd = HARNESS_CMD[req.harness];
+    await tmux("send-keys", "-t", paneId, "-l", cmd);
+    await tmux("send-keys", "-t", paneId, "C-m");
+    log(`launched: ${cmd}`);
+    const wait = Math.min(Math.max(req.waitSeconds ?? 8, 3), 60);
+    log(`waiting ${wait}s for the harness to start…`);
+    await sleep(wait * 1000);
+    const inject = async (line) => { await tmux("send-keys", "-t", paneId, "-l", line); await sleep(400); await tmux("send-keys", "-t", paneId, "C-m"); log(`injected: ${line}`); await sleep(600); };
+    if (req.model && CLAUDE_HARNESS_ONLY.has(req.harness))
+        await inject(`/model ${req.model}`);
+    if (CLAUDE_HARNESS_ONLY.has(req.harness))
+        await inject(`/color ${ROLE_COLOR[req.role]}`);
+    const skill = `${ROLE_SKILL[req.role]} --id=${req.agentId}${req.lane ? ` --lane=${req.lane}` : ""}${req.room ? ` --room=${req.room}` : ""}`;
+    await inject(CLAUDE_HARNESS_ONLY.has(req.harness) ? skill : `Act per the ${ROLE_SKILL[req.role].slice(1)} playbook card: ${skill}${req.note ? ". " + req.note : ""}`);
+    if (req.note && CLAUDE_HARNESS_ONLY.has(req.harness))
+        await inject(req.note);
+    // wait for registration
+    const deadline = Date.now() + 90_000;
+    let registered = false;
+    while (Date.now() < deadline) {
+        if (isRegistered(req.agentId)) {
+            registered = true;
+            break;
+        }
+        await sleep(2_000);
+    }
+    log(registered ? `✓ ${req.agentId} registered on the bus` : `⚠ ${req.agentId} not registered after 90s — check the pane`);
+    // transport: a registered-but-unattached agent cannot receive pushed DMs. Give it 30 s to attach itself (the role card says so); otherwise tell it — into the pane WE created.
+    let attached = false;
+    if (registered) {
+        const d2 = Date.now() + 30_000;
+        while (Date.now() < d2) {
+            if (isAttached(req.agentId)) {
+                attached = true;
+                break;
+            }
+            await sleep(2_000);
+        }
+        if (!attached) {
+            log(`⚠ not attached to tmux-push after 30 s — asking it to attach (typed into its own pane ${paneId})`);
+            await inject(`Attach yourself to the coord bus transport now: call attach_agent with agentId ${req.agentId}, tmuxTarget ${paneId} (tmux-push, includeRoom true). Without it, DMs will not reach this pane.`);
+            const d3 = Date.now() + 60_000;
+            while (Date.now() < d3) {
+                if (isAttached(req.agentId)) {
+                    attached = true;
+                    break;
+                }
+                await sleep(2_000);
+            }
+        }
+        log(attached ? `✓ ${req.agentId} attached (tmux-push) — DMs will land in ${paneId}` : `✗ ${req.agentId} still not attached — DMs will sit in its inbox until it attaches (Fleets shows "not attached")`);
+    }
+    return { agentId: req.agentId, pane: paneId, window: target, registered, attached };
+}
+export function suggestId(project, role, existing) {
+    const base = `${project}-${role}`;
+    if (role !== "worker")
+        return existing.includes(base) ? `${base}-2` : base;
+    let n = 1;
+    while (existing.includes(`${base}-${n}`))
+        n++;
+    return `${base}-${n}`;
+}
+export function readPresets(coordDir) { try {
+    return JSON.parse(readFileSync(path.join(coordDir, "presets.json"), "utf8"));
+}
+catch {
+    return [];
+} }
+export const FLEET_TEMPLATES = [
+    { id: "solo", label: "Solo · aide", roles: ["aide"], workers: 0, hint: "your planning buddy for a repo you drive yourself (plan-phase, queue)" },
+    { id: "minimal", label: "Minimal · aide + coordinator + 1 worker", roles: ["aide", "coordinator"], workers: 1, hint: "smallest fleet that ships: you talk to the aide, coordinator routes one lane" },
+    { id: "standard", label: "Standard · aide + coordinator + qa + 2 workers", roles: ["aide", "coordinator", "qa"], workers: 2, hint: "the playbook default; QA gates, aide owns the queue" },
+    { id: "full", label: "Full · + ci, N workers", roles: ["aide", "coordinator", "qa", "ci"], workers: 3, hint: "release-flow fleet (tier-1 auto-deploy) — cheap harness for ci" },
+];
+/* Fleet presence: which playbook roles are live for a project. */
+export function fleetStatus(live) {
+    const has = (re) => live.find((a) => re.test(a.role ?? ""))?.agentId ?? null;
+    const roles = { coordinator: has(/coordinator/i), aide: has(/aide|liaison|curator/i), qa: has(/\bqa\b|quality/i), ci: has(/\bci\b/i), workers: live.filter((a) => /worker|repo-owner|lane/i.test(a.role ?? "") || (!/coordinator|aide|liaison|curator|qa|quality|\bci\b|automation|human|audit/i.test(a.role ?? "") && a.role)).map((a) => a.agentId) };
+    const state = live.length === 0 ? "absent" : roles.coordinator && roles.workers.length > 0 ? "present" : "partial";
+    const missing = [!roles.coordinator && "coordinator", !roles.aide && "aide", !roles.qa && "qa", roles.workers.length === 0 && "worker"].filter(Boolean);
+    return { state, roles, missing, live: live.map((a) => a.agentId) };
+}

package/dist/runs.js

@@ -0,0 +1,46 @@
+const RING = 200, LOG_MAX = 400;
+export class Runs {
+    runs = [];
+    listeners = new Set();
+    seq = 0;
+    list(limit = 50) { return this.runs.slice(-limit).reverse(); }
+    get(id) { return this.runs.find((r) => r.id === id); }
+    running() { return this.runs.filter((r) => r.status === "running" || r.status === "queued"); }
+    subscribe(fn) { this.listeners.add(fn); return () => this.listeners.delete(fn); }
+    emit(r) { for (const l of this.listeners)
+        l(r); }
+    create(init) {
+        const r = { id: `run-${Date.now()}-${++this.seq}`, status: "queued", startedAt: Date.now(), log: [], ...init };
+        this.runs.push(r);
+        if (this.runs.length > RING)
+            this.runs.shift();
+        this.emit(r);
+        return r;
+    }
+    log(r, line) { r.log.push(`${new Date().toISOString().slice(11, 19)} ${line}`); if (r.log.length > LOG_MAX)
+        r.log.shift(); this.emit(r); }
+    start(r) { r.status = "running"; r.startedAt = Date.now(); this.emit(r); }
+    finish(r, result) { r.status = "ok"; r.endedAt = Date.now(); r.result = result; this.emit(r); }
+    fail(r, err) { r.status = "failed"; r.endedAt = Date.now(); r.error = err instanceof Error ? err.message : String(err); this.emit(r); }
+    /** Fire-and-forget variant: returns the Run immediately (status running); the task keeps logging. */
+    execAsync(init, task) {
+        const r = this.create(init);
+        this.start(r);
+        task((l) => this.log(r, l), r).then((out) => this.finish(r, out)).catch((e) => { this.log(r, `error: ${e instanceof Error ? e.message : String(e)}`); this.fail(r, e); });
+        return r;
+    }
+    /** Run an async task as a Run; the task gets a logger. */
+    async exec(init, task) {
+        const r = this.create(init);
+        this.start(r);
+        try {
+            const out = await task((l) => this.log(r, l), r);
+            this.finish(r, out);
+        }
+        catch (e) {
+            this.log(r, `error: ${e instanceof Error ? e.message : String(e)}`);
+            this.fail(r, e);
+        }
+        return r;
+    }
+}

package/dist/seam.js

@@ -0,0 +1,125 @@
+/* Read-only views over a project's seam files, parsed ONLY through @davidbalzan/groundwork-seam. */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { parseWorkDoc, queueItemsOf, doneEntriesOf, listWorkBoardOf, workDocIssues, SCHEMA } from "@davidbalzan/groundwork-seam";
+import { parseFactsDoc } from "@davidbalzan/groundwork-seam";
+const read = (p) => (existsSync(p) ? readFileSync(p, "utf8") : null);
+const FACT_STALE_DAYS = 14; // groundwork doctor rule
+export function boardOf(projectPath) {
+    const docs = path.join(projectPath, "docs");
+    const ws = read(path.join(docs, "WORKSTREAMS.md"));
+    const q = read(path.join(docs, "QUEUE.md"));
+    const d = read(path.join(docs, "DONE.md"));
+    const f = read(path.join(docs, "FACTS.md"));
+    const wsDoc = ws ? parseWorkDoc(ws) : null;
+    const board = wsDoc ? listWorkBoardOf(wsDoc) : [];
+    const schema = board.find((r) => "schema" in r)?.schema ?? null;
+    const qDoc = q ? parseWorkDoc(q) : null;
+    const dDoc = d ? parseWorkDoc(d) : null;
+    const facts = f ? parseFactsDoc(f) : null;
+    const now = Date.now();
+    return {
+        files: { workstreams: !!ws, queue: !!q, done: !!d, facts: !!f },
+        workstreams: { schema: schema ?? (ws ? "unknown" : null), rows: board, issues: wsDoc ? workDocIssues(wsDoc) : [] },
+        queue: qDoc ? queueItemsOf(qDoc) : [],
+        done: dDoc ? doneEntriesOf(dDoc) : [],
+        facts: facts
+            ? {
+                entries: facts.entries.map((e) => {
+                    const verified = e.verified;
+                    const ageDays = verified ? Math.floor((now - Date.parse(verified)) / 86_400_000) : null;
+                    return { ...e, ageDays, stale: ageDays !== null && ageDays > FACT_STALE_DAYS };
+                }),
+                issues: facts.issues,
+            }
+            : null,
+        phases: promoteByStreams(phasesOf(docs), board),
+        schemas: SCHEMA,
+    };
+}
+// Phase progress the way `groundwork status` derives it: checkbox counts in docs/phases/<phase>/PHASE<n>_TASKS.md
+export function phasesOf(docs) {
+    const dir = path.join(docs, "phases");
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && /^phase/i.test(e.name))
+        .map((e) => {
+        const tasks = readdirSync(path.join(dir, e.name)).find((n) => /_TASKS\.md$/i.test(n));
+        const src = tasks ? read(path.join(dir, e.name, tasks)) ?? "" : "";
+        const total = (src.match(/^\s*- \[[ xX]\]/gm) ?? []).length;
+        const done = (src.match(/^\s*- \[[xX]\]/gm) ?? []).length;
+        const readme = read(path.join(dir, e.name, "README.md")) ?? "";
+        const title = readme.match(/^#\s+(.+)$/m)?.[1] ?? e.name;
+        // complete: all tasks ticked · ongoing: some ticked · planned: tasks exist, none ticked · pending: no PHASE*_TASKS.md yet (run /plan-phase)
+        const state = total && done === total ? "complete" : done > 0 ? "ongoing" : total > 0 ? "planned" : "pending";
+        const n = e.name.match(/(\d+(?:\.\d+)?)/)?.[1] ?? e.name;
+        return { id: e.name, n, title, done, total, state, readme: existsSync(path.join(dir, e.name, "README.md")) ? `phases/${e.name}/README.md` : null, tasks: tasks ? `phases/${e.name}/${tasks}` : null };
+    })
+        .sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }));
+}
+export function docOf(projectPath, rel) {
+    const safe = path.normalize(rel).replace(/^(\.\.[/\\])+/, "");
+    const full = path.join(projectPath, "docs", safe);
+    if (!full.startsWith(path.join(projectPath, "docs")))
+        return null;
+    return read(full);
+}
+export function docsIndex(projectPath) {
+    const docs = path.join(projectPath, "docs");
+    if (!existsSync(docs))
+        return [];
+    const out = [];
+    const walk = (dir, prefix = "") => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            if (e.name.startsWith("."))
+                continue;
+            if (e.isDirectory())
+                walk(path.join(dir, e.name), prefix + e.name + "/");
+            else if (e.name.endsWith(".md"))
+                out.push(prefix + e.name);
+        }
+    };
+    walk(docs);
+    return out.sort();
+}
+/** Tasks of one phase: every `- [ ]` / `- [x]` in PHASE*_TASKS.md with line number, section (last ## / ### heading) and nesting depth. Same source `groundwork status` counts. */
+export function phaseTasksOf(docs, phaseId) {
+    const dir = path.join(docs, "phases", phaseId);
+    if (!existsSync(dir))
+        return null;
+    const tasksFile = readdirSync(dir).find((n) => /_TASKS\.md$/i.test(n));
+    if (!tasksFile)
+        return { phase: phaseId, file: null, sections: [], done: 0, total: 0 };
+    const src = read(path.join(dir, tasksFile)) ?? "";
+    const sections = [];
+    let cur = { title: "(top)", line: 1, tasks: [] };
+    src.split("\n").forEach((l, i) => {
+        const h = l.match(/^(#{2,4})\s+(.+)$/);
+        if (h) {
+            if (cur.tasks.length)
+                sections.push(cur);
+            cur = { title: h[2].trim(), line: i + 1, tasks: [] };
+            return;
+        }
+        const t = l.match(/^(\s*)- \[( |x|X)\]\s+(.*)$/);
+        if (t)
+            cur.tasks.push({ line: i + 1, done: t[2] !== " ", text: t[3].trim(), depth: Math.floor(t[1].length / 2) });
+    });
+    if (cur.tasks.length)
+        sections.push(cur);
+    const all = sections.flatMap((s) => s.tasks);
+    return { phase: phaseId, file: `phases/${phaseId}/${tasksFile}`, sections, done: all.filter((t) => t.done).length, total: all.length };
+}
+/** A phase with no ticked task is still ONGOING when the board has a non-done Active Stream that references it (P1-… / Phase 1 …). Streams are the coordinator's declaration of work in flight. */
+function promoteByStreams(phases, board) {
+    const rows = board;
+    return phases.map((ph) => {
+        const n = ph.n.replace(/\./g, "\\.");
+        const re = new RegExp(`(^|\\b)(P${n}[-\\s.]|Phase\\s*${n}\\b)`, "i");
+        const mine = rows.filter((r) => re.test(r.stream ?? r.lane ?? ""));
+        const active = mine.filter((r) => !/done|merged|deployed|complete|closed|✅/i.test(r.status ?? r.state ?? ""));
+        const state = ph.state === "complete" ? "complete" : active.length > 0 && ph.state !== "ongoing" ? "ongoing" : ph.state;
+        return { ...ph, state, streams: mine.length };
+    });
+}