@davidbalzan/groundwork-console 0.1.0

package/bin/groundwork-console.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/* groundwork-console — one command: starts the API + serves the built UI on one port, prints the sign-in link, opens the browser.
+   Flags: --port 8790 · --host 127.0.0.1 · --no-open · --no-auth · --config <file>
+   Subcommands: token (print the token) · doctor (kit requires + paths) · config (print config path) */
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+await import("../dist/env.js"); // legacy KIT_CONSOLE_* env + ~/.kit-console → ~/.groundwork-console move
+const args = process.argv.slice(2);
+const flag = (k, d) => { const i = args.indexOf(k); return i >= 0 ? (args[i + 1] ?? true) : d; };
+const has = (k) => args.includes(k);
+const sub = args.find((a) => !a.startsWith("--") && !["true", "false"].includes(a) && !/^\d+$/.test(a) && !args[args.indexOf(a) - 1]?.startsWith("--"));
+
+const port = String(flag("--port", process.env.PORT ?? "8790"));
+const host = String(flag("--host", process.env.GROUNDWORK_CONSOLE_HOST ?? "127.0.0.1"));
+if (flag("--config")) process.env.GROUNDWORK_CONSOLE_CONFIG = String(flag("--config"));
+process.env.PORT = port; process.env.GROUNDWORK_CONSOLE_HOST = host;
+if (has("--no-auth")) process.env.GROUNDWORK_CONSOLE_AUTH = "off";
+if (!process.env.GROUNDWORK_CONSOLE_CONFIG && !existsSync(path.resolve(process.cwd(), "groundwork-console.config.json"))) process.env.GROUNDWORK_CONSOLE_HOME_CONFIG = "1"; // packaged: prefer ~/.groundwork-console/config.json
+
+const pkg = JSON.parse(readFileSync(path.join(here, "../package.json"), "utf8"));
+const tokenFile = path.join(homedir(), ".groundwork-console", "token");
+
+if (sub === "token") { const { loadToken } = await import("../dist/auth.js"); console.log(loadToken()); process.exit(0); }
+if (sub === "config") { const { CONFIG_FILE } = await import("../dist/config.js"); console.log(CONFIG_FILE); process.exit(0); }
+if (sub === "doctor") {
+  const { requiresReport } = await import("../dist/kitresolve.js"); const { loadConfig, CONFIG_FILE } = await import("../dist/config.js");
+  const cfg = loadConfig(); const r = requiresReport(cfg.kitPath);
+  console.log(`groundwork-console ${pkg.version} · config ${CONFIG_FILE} · store ${cfg.coordDir}`);
+  for (const k of ["seam", "mcp", "groundwork", "playbook"]) console.log(`  ${r[k].ok === false ? "✗" : r[k].ok ? "✓" : "?"} ${k.padEnd(10)} ${String(r[k].installed ?? "missing").padEnd(8)} needs ${r[k].required}${r.paths[k] ? `  ← ${r.paths[k]}` : ""}`);
+  console.log(`  kit checkout: ${r.paths.kitCheckout ?? "none (using installed packages)"}`);
+  if (!r.ok) { console.log("\nfix: npm i -g agent-coord-mcp @davidbalzan/groundwork agent-coordination"); process.exit(1); }
+  process.exit(0);
+}
+if (sub && sub !== "start") { console.error(`unknown command: ${sub}\nusage: groundwork-console [start] [--port N] [--host H] [--no-open] [--no-auth] [--config file] | token | doctor | config`); process.exit(2); }
+
+await import("../dist/server.js");
+const { loadToken, authEnabled } = await import("../dist/auth.js");
+const { CONFIG_FILE } = await import("../dist/config.js");
+const base = `http://${host === "0.0.0.0" ? "localhost" : host}:${port}`;
+const token = authEnabled ? loadToken() : null;
+const url = token ? `${base}/api/auth/login?token=${encodeURIComponent(token)}&next=/` : `${base}/`;
+console.log(`\n  groundwork-console ${pkg.version}\n  UI      ${base}/\n  config  ${CONFIG_FILE}\n  token   ${authEnabled ? tokenFile : "auth off"}\n  sign in ${url}\n`);
+if (!has("--no-open") && host !== "0.0.0.0") { try { const { default: open } = await import("open"); await open(url); } catch { /* headless: link is printed */ } }

package/dist/answered.js

@@ -0,0 +1,34 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+/* Console-owned "answered" set for DAVID_DECISION packets (room posts + DMs), keyed by message id.
+   Until the bus has inReplyTo (queued P3), this is how the UI stops showing a packet as open once David replied from the console.
+   Persisted in ~/.groundwork-console/answered.json — never touches ~/agent-coord. */
+const FILE = path.join(homedir(), ".groundwork-console", "answered.json");
+let cache = null;
+export function answered() {
+    if (cache)
+        return cache;
+    try {
+        cache = existsSync(FILE) ? JSON.parse(readFileSync(FILE, "utf8")) : {};
+    }
+    catch {
+        cache = {};
+    }
+    return cache;
+}
+export function markAnswered(ids, meta) {
+    const a = answered();
+    let n = 0;
+    for (const id of ids)
+        if (id && !a[id]) {
+            a[id] = { ts: Date.now(), ...meta };
+            n++;
+        }
+    if (n) {
+        mkdirSync(path.dirname(FILE), { recursive: true });
+        writeFileSync(FILE, JSON.stringify(a, null, 2));
+    }
+    return n;
+}
+export const isAnswered = (id) => typeof id === "string" && !!answered()[id];

package/dist/auth.js

@@ -0,0 +1,47 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { getCookie, setCookie, deleteCookie } from "hono/cookie";
+/* Simple auth: one shared token (David alone). GROUNDWORK_CONSOLE_TOKEN env, else ~/.groundwork-console/token (generated once, 0600, printed at boot).
+   Login = POST /api/auth/login {token} → httpOnly cookie (30 d). Every other /api/* needs the cookie or `Authorization: Bearer <token>`.
+   GROUNDWORK_CONSOLE_AUTH=off disables (loopback dev). No users, no OAuth — see UX.md non-goals; GitHub OAuth is the step when a second human appears. */
+const TOKEN_FILE = path.join(homedir(), ".groundwork-console", "token");
+export const COOKIE = "gwc_session";
+export const authEnabled = process.env.GROUNDWORK_CONSOLE_AUTH !== "off";
+export function loadToken() {
+    if (process.env.GROUNDWORK_CONSOLE_TOKEN)
+        return process.env.GROUNDWORK_CONSOLE_TOKEN.trim();
+    if (existsSync(TOKEN_FILE)) {
+        const t = readFileSync(TOKEN_FILE, "utf8").trim();
+        if (t)
+            return t;
+    }
+    const t = randomBytes(24).toString("base64url");
+    mkdirSync(path.dirname(TOKEN_FILE), { recursive: true });
+    writeFileSync(TOKEN_FILE, t + "\n", { mode: 0o600 });
+    return t;
+}
+const TOKEN = loadToken();
+export const tokenFile = TOKEN_FILE;
+const same = (a, b) => { const x = Buffer.from(a), y = Buffer.from(b); return x.length === y.length && timingSafeEqual(x, y); };
+const PUBLIC = [/^\/api\/health$/, /^\/api\/auth\/(login|status)$/, /^\/api\/uploads\/[\w.-]+$/]; // uploads: served by unguessable hash for HTTP-node agents
+export function requireAuth() {
+    return async (c, next) => {
+        if (!authEnabled || PUBLIC.some((re) => re.test(c.req.path)))
+            return next();
+        const cookie = getCookie(c, COOKIE);
+        const bearer = c.req.header("authorization")?.replace(/^Bearer\s+/i, "");
+        if ((cookie && same(cookie, TOKEN)) || (bearer && same(bearer, TOKEN)))
+            return next();
+        return c.json({ error: "unauthorized", login: "/api/auth/login" }, 401);
+    };
+}
+export function login(c, token) {
+    if (!same(token.trim(), TOKEN))
+        return false;
+    setCookie(c, COOKIE, TOKEN, { httpOnly: true, sameSite: "Lax", path: "/", maxAge: 30 * 24 * 3600, secure: c.req.url.startsWith("https://") });
+    return true;
+}
+export function logout(c) { deleteCookie(c, COOKIE, { path: "/" }); }
+export function isAuthed(c) { const v = getCookie(c, COOKIE); return !authEnabled || (!!v && same(v, TOKEN)); }

package/dist/bus.js

@@ -0,0 +1,79 @@
+/* Read-only views over the agent-coord store (~/agent-coord). Mirrors what the MCP tools return, without going through the MCP. */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { listPanes } from "./tmux.js";
+const readJson = (p, fallback) => { try {
+    return JSON.parse(readFileSync(p, "utf8"));
+}
+catch {
+    return fallback;
+} };
+const tailJsonl = (p, limit) => {
+    if (!existsSync(p))
+        return [];
+    const lines = readFileSync(p, "utf8").split("\n").filter(Boolean);
+    return lines.slice(-limit).map((l) => { try {
+        return JSON.parse(l);
+    }
+    catch {
+        return { malformed: true, raw: l };
+    } });
+};
+export async function agentsAsync(root) {
+    const panes = await listPanes();
+    return agentsSync(root).map((a) => {
+        const pane = a.pane ? panes.find((p) => p.paneId === a.pane || p.target === a.pane) : undefined;
+        const paneActivity = pane?.activityTs ?? null;
+        const lastSeen = Math.max(a.lastSeen ?? 0, paneActivity ?? 0);
+        const age = lastSeen ? Date.now() - lastSeen : Infinity;
+        return { ...a, paneActivity, paneCommand: pane?.command ?? null, paneAlive: pane ? !pane.dead : null, lastSeen: lastSeen || null, heartbeatAgeMs: Number.isFinite(age) ? age : null, liveness: age < 15 * 60_000 ? "live" : age < 24 * 3_600_000 ? "idle" : "dead", active: paneActivity ? Date.now() - paneActivity < 60_000 : false };
+    }).sort((a, b) => (b.lastSeen ?? 0) - (a.lastSeen ?? 0));
+}
+export const agents = agentsSync;
+export function agentsSync(root) {
+    const reg = readJson(path.join(root, "agents.json"), {});
+    const transports = existsSync(path.join(root, "transports")) ? new Set(readdirSync(path.join(root, "transports")).map((f) => f.replace(/\.json$/, ""))) : new Set();
+    const now = Date.now();
+    return Object.values(reg).map((a) => {
+        const tPath = path.join(root, "transports", `${a.agentId}.json`);
+        const t = transports.has(a.agentId) ? readJson(tPath, {}) : null;
+        // activity = freshest of heartbeat, transport marker mtime, inbox mtime, cursor mtime (the MCP prefers pane activity; we don't have tmux here)
+        const mtimes = [tPath, path.join(root, "inbox", `${a.agentId}.jsonl`), path.join(root, "cursors", `${a.agentId}.json`)].filter(existsSync).map((f) => statSync(f).mtimeMs);
+        const lastSeen = Math.max(a.lastHeartbeat ?? 0, ...mtimes);
+        const age = lastSeen ? now - lastSeen : Infinity;
+        return { ...a, transport: t?.transport ?? t?.kind ?? (t ? "tmux-push" : null), pane: t?.tmuxTarget ?? null, liveness: age < 15 * 60_000 ? "live" : age < 24 * 3_600_000 ? "idle" : "dead", heartbeatAgeMs: Number.isFinite(age) ? age : null, lastSeen: lastSeen || null };
+    }).sort((a, b) => (b.lastSeen ?? 0) - (a.lastSeen ?? 0));
+}
+export function rooms(root) {
+    const meta = readJson(path.join(root, "rooms.json"), {});
+    const dir = path.join(root, "rooms");
+    const files = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith(".jsonl")) : [];
+    return files.map((f) => {
+        const name = f.replace(/\.jsonl$/, "");
+        const p = path.join(dir, f);
+        const count = readFileSync(p, "utf8").split("\n").filter(Boolean).length;
+        return { room: name, ...(meta[name] ?? {}), messageCount: count, lastTs: statSync(p).mtimeMs };
+    }).sort((a, b) => b.lastTs - a.lastTs);
+}
+export function roomMessages(root, room, limit = 100, before) {
+    const p = path.join(root, "rooms", `${path.basename(room)}.jsonl`);
+    if (before === undefined)
+        return tailJsonl(p, limit);
+    // history page: the `limit` messages before timestamp `before`
+    if (!existsSync(p))
+        return [];
+    const all = readFileSync(p, "utf8").split("\n").filter(Boolean).map((l) => { try {
+        return JSON.parse(l);
+    }
+    catch {
+        return { malformed: true, raw: l };
+    } });
+    const older = all.filter((m) => typeof m.ts === "number" && m.ts < before);
+    return older.slice(-limit);
+}
+export function roomMessageCount(root, room) { const p = path.join(root, "rooms", `${path.basename(room)}.jsonl`); return existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean).length : 0; }
+export function statusStream(root, limit = 50) { return tailJsonl(path.join(root, "status.jsonl"), limit); }
+export function scopes(root) { return readJson(path.join(root, "scopes.json"), {}); }
+/* prefix classification — same table as seam/protocol/prefixes.ts (byte-0, case-sensitive) */
+export const PREFIXES = ["DAVID_DECISION", "SCOPE CHANGE", "AGENT_ACTION", "BLOCKER", "VERDICT", "RISK", "DONE", "FYI", "GO"];
+export function prefixOf(text) { return PREFIXES.find((p) => text.startsWith(p + ":") || text.startsWith(p + " ")) ?? null; }

package/dist/config.js

@@ -0,0 +1,40 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const expand = (p) => (p.startsWith("~") ? path.join(homedir(), p.slice(1)) : p);
+const here = path.dirname(fileURLToPath(import.meta.url));
+/* Config resolution (ergonomics first):
+   1. GROUNDWORK_CONSOLE_CONFIG (explicit)
+   2. ./groundwork-console.config.json in the current directory (dev checkout of this repo)
+   3. ~/.groundwork-console/config.json — created on first run with a starter (no projects; Add project in the UI). */
+const HOME_CFG = path.join(homedir(), ".groundwork-console", "config.json");
+const repoCfg = path.resolve(here, "../../../groundwork-console.config.json");
+const CONFIG_PATH = process.env.GROUNDWORK_CONSOLE_CONFIG ?? (existsSync(path.resolve(process.cwd(), "groundwork-console.config.json")) ? path.resolve(process.cwd(), "groundwork-console.config.json") : existsSync(repoCfg) && !process.env.GROUNDWORK_CONSOLE_HOME_CONFIG ? repoCfg : HOME_CFG);
+const STARTER = { $comment: "Groundwork Console config. Paths are absolute or ~-relative. Add projects from the UI (Home → Add project) or here.", kitPath: "~/workspace/groundwork-kit", coordDir: "~/agent-coord", projects: [] };
+export function loadConfig() {
+    if (!existsSync(CONFIG_PATH)) {
+        mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+        writeFileSync(CONFIG_PATH, JSON.stringify(STARTER, null, 2) + "\n");
+    }
+    const raw = { ...STARTER, ...JSON.parse(readFileSync(CONFIG_PATH, "utf8")) };
+    return {
+        kitPath: expand(raw.kitPath ?? ""),
+        coordDir: expand(process.env.AGENT_COORD_DIR ?? raw.coordDir ?? "~/agent-coord"),
+        projects: (raw.projects ?? []).map((p) => ({ ...p, path: expand(p.path) })),
+    };
+}
+export const CONFIG_FILE = CONFIG_PATH;
+export function saveProjects(projects) {
+    const raw = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    const home = homedir();
+    raw.projects = projects.map((p) => ({ ...p, path: p.path.startsWith(home) ? "~" + p.path.slice(home.length) : p.path }));
+    writeFileSync(CONFIG_PATH, JSON.stringify(raw, null, 2) + "\n");
+}
+export function validateProjectPath(p) {
+    const full = expand(p);
+    if (!existsSync(full))
+        return { ok: false, reason: "path does not exist" };
+    const docs = path.join(full, "docs");
+    return { ok: true, path: full, hasDocs: existsSync(docs), hasSeam: ["WORKSTREAMS.md", "QUEUE.md", "DONE.md", "FACTS.md"].filter((f) => existsSync(path.join(docs, f))), isGit: existsSync(path.join(full, ".git")) };
+}

package/dist/docwrite.js

@@ -0,0 +1,66 @@
+/* Free-text writes of non-seam docs/*.md. Seam files (QUEUE/DONE/WORKSTREAMS/FACTS) stay Board-only.
+   Bytes are written as typed — no line-ending normalisation. If-Match is sha256 of the last GET body. */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+export const SEAM_BASENAMES = new Set(["QUEUE.md", "DONE.md", "WORKSTREAMS.md", "FACTS.md"]);
+export function sha256(s) {
+    return createHash("sha256").update(s, "utf8").digest("hex");
+}
+export class DocWriteError extends Error {
+    status;
+    sha;
+    constructor(message, status, sha) {
+        super(message);
+        this.status = status;
+        this.sha = sha;
+        this.name = "DocWriteError";
+    }
+}
+export function resolveDoc(projectPath, rel) {
+    const safe = path.normalize(rel).replace(/^(\.\.[/\\])+/, "").replace(/^[/\\]+/, "");
+    if (!safe || !safe.toLowerCase().endsWith(".md"))
+        return null;
+    if (safe.split(/[/\\]/).some((s) => s === ".." || s === "" || s === "."))
+        return null;
+    const docsRoot = path.resolve(projectPath, "docs");
+    const full = path.resolve(docsRoot, safe);
+    if (full !== docsRoot && !full.startsWith(docsRoot + path.sep))
+        return null;
+    return { rel: safe.split(path.sep).join("/"), full };
+}
+export function writeDoc(projectPath, rel, content, ifMatch, log) {
+    const resolved = resolveDoc(projectPath, rel);
+    if (!resolved)
+        throw new DocWriteError("path not under docs/ or not a .md file", 400);
+    if (SEAM_BASENAMES.has(resolved.rel))
+        throw new DocWriteError("QUEUE/DONE/WORKSTREAMS/FACTS are seam files — write them on the Board, not as free text", 400);
+    if (!existsSync(resolved.full))
+        throw new DocWriteError("not found", 404);
+    const src = readFileSync(resolved.full, "utf8");
+    const diskSha = sha256(src);
+    if (!ifMatch)
+        throw new DocWriteError("ifMatch (sha256 of last GET) required", 400);
+    if (diskSha !== ifMatch)
+        throw new DocWriteError("conflict: file changed on disk", 409, diskSha);
+    log(`disk crlf=${src.includes("\r\n")} incoming crlf=${content.includes("\r\n")} — writing bytes as typed`);
+    const tmp = `${resolved.full}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        writeFileSync(tmp, content, "utf8");
+        renameSync(tmp, resolved.full);
+    }
+    catch (e) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* leftover tmp */ }
+        throw e;
+    }
+    const after = readFileSync(resolved.full, "utf8");
+    if (after !== content)
+        throw new Error("post-write verification failed: disk !== content");
+    const sha = sha256(content);
+    const bytes = Buffer.byteLength(content, "utf8");
+    log(`wrote docs/${resolved.rel} (${bytes} bytes, sha ${sha.slice(0, 12)})`);
+    return { file: `docs/${resolved.rel}`, bytes, sha };
+}

package/dist/env.js

@@ -0,0 +1,23 @@
+import { existsSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+/* Rename compatibility (kit-console → groundwork-console, 2026-08-18). Import this FIRST from server.ts and the bin.
+   1. Legacy env vars: KIT_CONSOLE_* are honoured as GROUNDWORK_CONSOLE_* when the new name is unset.
+   2. State dir: ~/.kit-console is moved once to ~/.groundwork-console (token, config, switches, answered, uploads, events-state) so nothing has to be re-entered. */
+for (const [k, v] of Object.entries(process.env))
+    if (k.startsWith("KIT_CONSOLE_") && v !== undefined) {
+        const nk = "GROUNDWORK_CONSOLE_" + k.slice("KIT_CONSOLE_".length);
+        if (process.env[nk] === undefined)
+            process.env[nk] = v;
+    }
+const OLD = path.join(homedir(), ".kit-console"), NEW = path.join(homedir(), ".groundwork-console");
+if (existsSync(OLD) && !existsSync(NEW)) {
+    try {
+        renameSync(OLD, NEW);
+        console.log(`state dir moved: ${OLD} → ${NEW}`);
+    }
+    catch (e) {
+        console.warn(`could not move ${OLD} → ${NEW}: ${e.message}`);
+    }
+}
+export const STATE_DIR = NEW;

package/dist/events.js

@@ -0,0 +1,170 @@
+/* Mechanical event detection over the seam + bus, with rule evaluation.
+   Snapshot per project every tick, diff, emit typed events, keep a ring buffer, SSE fan-out.
+   LIVE sends only when: busWrites.enabled && !config.dryRun && rule.enabled. Dedupe by key (persisted), rate-limited. Every send is a Run. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { boardOf } from "./seam.js";
+import { roomMessages, agents } from "./bus.js";
+import { busWrites } from "./mcp.js";
+const RING = 500;
+const expand = (p) => (p.startsWith("~") ? path.join(homedir(), p.slice(1)) : p);
+export class EventEngine {
+    cfg;
+    rulesPath;
+    runs;
+    send;
+    snaps = new Map();
+    buffer = [];
+    listeners = new Set();
+    seq = 0;
+    rules;
+    state = { sent: {}, window: {} };
+    constructor(cfg, rulesPath, runs, send) {
+        this.cfg = cfg;
+        this.rulesPath = rulesPath;
+        this.runs = runs;
+        this.send = send;
+        this.rules = JSON.parse(readFileSync(rulesPath, "utf8"));
+        for (const r of this.rules.rules)
+            r.enabled = r.enabled === true;
+        this.loadState();
+    }
+    get config() { return { identity: this.rules.identity, dryRun: this.rules.dryRun, limits: this.rules.limits ?? {}, rules: this.rules.rules, live: !this.rules.dryRun && busWrites.enabled, busWrites: busWrites.enabled }; }
+    recent(limit = 100) { return this.buffer.slice(-limit); }
+    subscribe(fn) { this.listeners.add(fn); return () => this.listeners.delete(fn); }
+    /** Console-owned config writes: dryRun + per-rule enabled, persisted to groundwork-console.rules.json. */
+    setDryRun(v) { this.rules.dryRun = v; this.saveRules(); }
+    setRuleEnabled(id, v) { const r = this.rules.rules.find((x) => x.id === id); if (!r)
+        throw new Error("unknown rule"); r.enabled = v; this.saveRules(); }
+    saveRules() { writeFileSync(this.rulesPath, JSON.stringify(this.rules, null, 2) + "\n"); }
+    get statePath() { return expand(this.rules.stateFile ?? "~/.groundwork-console/events-state.json"); }
+    loadState() { try {
+        if (existsSync(this.statePath))
+            this.state = JSON.parse(readFileSync(this.statePath, "utf8"));
+    }
+    catch { /* fresh */ } }
+    saveState() { mkdirSync(path.dirname(this.statePath), { recursive: true }); writeFileSync(this.statePath, JSON.stringify(this.state)); }
+    start(intervalMs = 15_000) { this.tick(true); setInterval(() => this.tick(false), intervalMs).unref(); }
+    snapshot(projectPath, room) {
+        const b = boardOf(projectPath);
+        const msgs = room ? roomMessages(this.cfg.coordDir, room, 50) : [];
+        const lastDecision = [...msgs].reverse().find((m) => typeof m.text === "string" && m.text.startsWith("DAVID_DECISION"));
+        const mal = b.workstreams.rows.filter((r) => "malformed" in r);
+        return { phases: Object.fromEntries(b.phases.map((p) => [p.id, { done: p.done, total: p.total, state: p.state }])), doneCount: b.done.length, queueIds: b.queue.filter((q) => !q.done).map((q) => q.id), staleFacts: b.facts?.entries.filter((e) => e.stale).map((e) => e.id) ?? [], malformed: mal.length, malformedLine: mal[0]?.line, lastDecisionId: lastDecision?.id ?? null };
+    }
+    tick(first) {
+        for (const p of this.cfg.projects) {
+            let cur;
+            try {
+                cur = this.snapshot(p.path, p.room);
+            }
+            catch {
+                continue;
+            }
+            const prev = this.snaps.get(p.name);
+            this.snaps.set(p.name, cur);
+            const base = { project: p.name, room: p.room ?? "" };
+            if (!prev || first) {
+                const bl = { ...base, baseline: true };
+                for (const f of cur.staleFacts)
+                    this.emitRaw("state.fact.stale", p.name, { ...bl, fact: f });
+                if (cur.malformed > 0)
+                    this.emitRaw("state.board.malformed", p.name, { ...bl, count: cur.malformed, line: cur.malformedLine ?? "?" });
+                if (cur.lastDecisionId)
+                    this.emitRaw("state.decision.open", p.name, { ...bl, id: cur.lastDecisionId });
+                const active = Object.entries(cur.phases).find(([, ph]) => ph.state === "ongoing");
+                if (active)
+                    this.emitRaw("state.phase.active", p.name, { ...bl, phase: active[0], done: active[1].done, total: active[1].total });
+                continue;
+            }
+            for (const [id, ph] of Object.entries(cur.phases)) {
+                const was = prev.phases[id];
+                if (was && was.state !== "complete" && ph.state === "complete")
+                    void this.emit("phase.completed", p.name, { ...base, phase: id, done: ph.done, total: ph.total });
+                if (was && was.done === 0 && ph.done > 0)
+                    void this.emit("phase.started", p.name, { ...base, phase: id, done: ph.done, total: ph.total });
+                if (was && ph.done !== was.done)
+                    void this.emit("phase.progress", p.name, { ...base, phase: id, done: ph.done, total: ph.total, delta: ph.done - was.done });
+            }
+            if (cur.doneCount > prev.doneCount)
+                void this.emit("done.appended", p.name, { ...base, count: cur.doneCount - prev.doneCount });
+            for (const id of prev.queueIds.filter((x) => !cur.queueIds.includes(x)))
+                void this.emit("queue.item.closed", p.name, { ...base, item: id });
+            for (const id of cur.queueIds.filter((x) => !prev.queueIds.includes(x)))
+                void this.emit("queue.item.added", p.name, { ...base, item: id });
+            for (const f of cur.staleFacts.filter((x) => !prev.staleFacts.includes(x)))
+                void this.emit("fact.stale", p.name, { ...base, fact: f, ageDays: ">14", owner: this.coordinatorFor(p.name, p.room) ?? "coordinator" });
+            if (cur.malformed > prev.malformed)
+                void this.emit("board.malformed", p.name, { ...base, count: cur.malformed, line: cur.malformedLine ?? "?" });
+            if (cur.lastDecisionId && cur.lastDecisionId !== prev.lastDecisionId)
+                void this.emit("decision.posted", p.name, { ...base, id: cur.lastDecisionId });
+        }
+    }
+    /** The live coordinator agent for a project/room (role coordinator, project == room or name), else null. */
+    coordinatorFor(project, room) {
+        const a = agents(this.cfg.coordDir).find((x) => /coordinator/i.test(x.role ?? "") && (x.project === room || x.project === project) && x.liveness !== "dead");
+        return a?.agentId ?? null;
+    }
+    emitRaw(type, project, data) {
+        const e = { id: `${Date.now()}-${++this.seq}`, ts: Date.now(), type, project, data, actions: [] };
+        this.push(e);
+    }
+    push(e) { this.buffer.push(e); if (this.buffer.length > RING)
+        this.buffer.shift(); this.notify(e); }
+    notify(e) { for (const l of this.listeners)
+        l(e); }
+    async emit(type, project, data) {
+        const live = !this.rules.dryRun && busWrites.enabled;
+        const actions = this.rules.rules.filter((r) => r.on === type).map((r) => ({
+            ruleId: r.id, type: r.action.type, dryRun: !(live && r.enabled),
+            to: r.action.to && this.fill(r.action.to, data), room: r.action.room && this.fill(r.action.room, data), prefix: r.action.prefix, text: r.action.text && this.fill(r.action.text, data), note: r.action.note,
+        }));
+        const e = { id: `${Date.now()}-${++this.seq}`, ts: Date.now(), type, project, data, actions };
+        this.push(e);
+        for (const a of actions) {
+            if (a.type !== "send_message" || a.dryRun)
+                continue;
+            const rule = this.rules.rules.find((r) => r.id === a.ruleId);
+            const key = `${a.ruleId}|${this.fill(rule.key ?? "{project}", data)}`;
+            const ttl = (this.rules.limits?.dedupeTtlHours ?? 72) * 3_600_000;
+            if (this.state.sent[key] && Date.now() - this.state.sent[key] < ttl) {
+                a.skipped = `dedupe (${key})`;
+                this.notify(e);
+                continue;
+            }
+            const wk = `${a.ruleId}|${project}`;
+            const hourAgo = Date.now() - 3_600_000;
+            this.state.window[wk] = (this.state.window[wk] ?? []).filter((t) => t > hourAgo);
+            if (this.state.window[wk].length >= (this.rules.limits?.maxPerRulePerProjectPerHour ?? 3)) {
+                a.skipped = "rate limit";
+                this.notify(e);
+                continue;
+            }
+            // resolve "coordinator" → live coordinator agent id
+            let to = a.to;
+            if (to === "coordinator") {
+                const c = this.coordinatorFor(project, String(data.room ?? ""));
+                if (!c) {
+                    a.skipped = "no live coordinator for project";
+                    this.notify(e);
+                    continue;
+                }
+                to = c;
+            }
+            const text = `${a.prefix ? a.prefix + ": " : ""}${a.text ?? ""}`;
+            const run = await this.runs.exec({ kind: "bus", label: `rule ${a.ruleId} → ${to ?? "#" + a.room}`, project, sideEffects: true, args: { event: type, to, room: a.room, text: text.slice(0, 200) } }, (log) => this.send({ ...(to ? { to } : { room: a.room }), text }, log));
+            a.runId = run.id;
+            a.sent = run.status === "ok";
+            if (run.status !== "ok")
+                a.skipped = run.error ?? "send failed";
+            if (a.sent) {
+                this.state.sent[key] = Date.now();
+                this.state.window[wk].push(Date.now());
+                this.saveState();
+            }
+            this.notify(e);
+        }
+    }
+    fill(t, d) { return t.replace(/\{(\w+)\}/g, (_m, k) => String(d[k] ?? `{${k}}`)); }
+}

package/dist/extensions.js

@@ -0,0 +1,31 @@
+/* Interim parser for the WORKSTREAMS coordinator-extension sections (## Open PRs · Cutover Gates · Needs David · Risks · Rooms · Decisions Recorded).
+   The seam reports these as "unknown workstreams grammar" today; asked grok to make the seam own them. Generic: header cells → objects; bullets → strings. */
+const SECTIONS = ["Open PRs", "Cutover Gates", "Needs David", "Risks", "Rooms", "Decisions Recorded"];
+const cells = (l) => l.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+export function extensionsOf(source) {
+    if (!source)
+        return [];
+    const lines = source.split("\n");
+    const out = [];
+    for (const title of SECTIONS) {
+        const start = lines.findIndex((l) => l.trim().toLowerCase().startsWith(`## ${title.toLowerCase()}`));
+        if (start < 0)
+            continue;
+        let end = lines.findIndex((l, i) => i > start && /^## /.test(l));
+        if (end < 0)
+            end = lines.length;
+        const body = lines.slice(start + 1, end);
+        const raw = body.join("\n").trim();
+        const tbl = body.filter((l) => l.trim().startsWith("|"));
+        const sec = { title, raw };
+        if (tbl.length >= 2) {
+            const headers = cells(tbl[0]);
+            sec.table = { headers, rows: tbl.slice(1).filter((l) => !/^\|\s*-{2,}/.test(l.trim()) && !/^\|[\s:|-]+\|$/.test(l.trim())).map((l) => Object.fromEntries(cells(l).map((c, i) => [headers[i] ?? `c${i}`, c]))) };
+        }
+        const bullets = body.filter((l) => /^\s*[-*] /.test(l)).map((l) => l.replace(/^\s*[-*] /, "").trim());
+        if (bullets.length)
+            sec.bullets = bullets;
+        out.push(sec);
+    }
+    return out;
+}

package/dist/gitinfo.js

@@ -0,0 +1,69 @@
+/* Read-only git views for a project's docs: uncommitted hunks (working tree vs HEAD, staged included), last commit touching the file + its hunks, and a docs/ status map. */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+async function git(cwd, args) { try {
+    const r = await run("git", args, { cwd, maxBuffer: 8 << 20 });
+    return r.stdout;
+}
+catch (e) {
+    const err = e;
+    if (err.stdout !== undefined && (err.code === 1))
+        return err.stdout;
+    return null;
+} }
+export function parseHunks(diff) {
+    const out = [];
+    let cur = null;
+    for (const line of diff.split("\n")) {
+        const m = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(.*)$/);
+        if (m) {
+            cur = { oldStart: +m[1], oldLines: m[2] === undefined ? 1 : +m[2], newStart: +m[3], newLines: m[4] === undefined ? 1 : +m[4], header: m[5].trim(), lines: [] };
+            out.push(cur);
+            continue;
+        }
+        if (cur && /^[+\- ]/.test(line) && !line.startsWith("+++") && !line.startsWith("---"))
+            cur.lines.push(line);
+    }
+    return out;
+}
+export async function docGit(projectPath, rel) {
+    const inside = await git(projectPath, ["rev-parse", "--is-inside-work-tree"]);
+    if (!inside?.trim().startsWith("true"))
+        return { repo: false, tracked: false, uncommitted: [], untracked: false, lastCommit: null };
+    const tracked = (await git(projectPath, ["ls-files", "--error-unmatch", "--", rel])) !== null;
+    const untrackedList = (await git(projectPath, ["ls-files", "--others", "--exclude-standard", "--", rel])) ?? "";
+    const untracked = !tracked && untrackedList.trim().length > 0;
+    const uncommitted = tracked ? parseHunks((await git(projectPath, ["diff", "-U3", "HEAD", "--", rel])) ?? "") : [];
+    let lastCommit = null;
+    if (tracked) {
+        const log = (await git(projectPath, ["log", "-1", "--format=%H%x1f%h%x1f%s%x1f%an%x1f%cI", "--", rel]))?.trim();
+        if (log) {
+            const [sha, short, subject, author, date] = log.split("\x1f");
+            const show = (await git(projectPath, ["show", "--format=", "-U3", sha, "--", rel])) ?? "";
+            lastCommit = { sha, short, subject, author, date, hunks: parseHunks(show) };
+        }
+    }
+    return { repo: true, tracked, uncommitted, untracked, lastCommit };
+}
+/** docs/ status map: path → "M" | "A" | "??" | "D" (porcelain codes, working tree vs HEAD incl. staged) */
+export async function docsStatus(projectPath) {
+    const out = (await git(projectPath, ["status", "--porcelain=v1", "--untracked-files=all", "--", "docs"])) ?? "";
+    const map = {};
+    for (const l of out.split("\n")) {
+        if (!l.trim())
+            continue;
+        const code = l.slice(0, 2).trim() || "M";
+        const p = l.slice(3).trim().replace(/^docs\//, "");
+        map[p] = code;
+    }
+    return map;
+}
+export async function lastDocsCommit(projectPath) {
+    const log = (await git(projectPath, ["log", "-1", "--format=%h%x1f%s%x1f%cI", "--", "docs"]))?.trim();
+    if (!log)
+        return null;
+    const [short, subject, date] = log.split("\x1f");
+    const files = ((await git(projectPath, ["show", "--format=", "--name-only", short, "--", "docs"])) ?? "").split("\n").filter(Boolean).map((f) => f.replace(/^docs\//, ""));
+    return { short, subject, date, files };
+}

package/dist/groundwork.js

@@ -0,0 +1,34 @@
+/* Groundwork + playbook CLIs, JSON mode (shipped by grok 2026-08-16). Cached briefly; both are read-only commands. */
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const cache = new Map();
+async function json(key, ttl, argv, fallback) {
+    const hit = cache.get(key);
+    if (hit && Date.now() - hit.at < ttl)
+        return hit.value;
+    let value;
+    try {
+        const r = await run("node", argv, { timeout: 20_000, maxBuffer: 4 << 20 });
+        value = { ...JSON.parse(r.stdout), ranAt: Date.now() };
+    }
+    catch (e) {
+        const err = e;
+        try {
+            value = { ...JSON.parse(err.stdout ?? ""), ranAt: Date.now() };
+        }
+        catch {
+            value = { ...fallback, ranAt: Date.now(), error: err.message };
+        }
+    }
+    cache.set(key, { at: Date.now(), value });
+    return value;
+}
+import { groundworkCli, playbookCli } from "./kitresolve.js";
+const gw = (kit) => groundworkCli(kit) ?? path.join(kit, "packages/groundwork/src/cli.mjs");
+const pb = (kit) => playbookCli(kit) ?? path.join(kit, "packages/coord-playbook/bin/install.mjs");
+export const doctor = (kit, proj) => json(`doctor:${proj}`, 30_000, [gw(kit), "doctor", proj, "--json"], { ok: false, exit: 1, checks: [], ranAt: 0 });
+export const status = (kit, proj) => json(`status:${proj}`, 15_000, [gw(kit), "status", proj, "--json"], { streams: [], next: null, queueFound: false, phases: [], ranAt: 0 });
+export const list = (kit, proj) => json(`list:${proj}`, 60_000, [gw(kit), "list", proj, "--json"], { version: "", project: proj, skills: [], ranAt: 0 });
+export const playbookList = (kit) => json("pb:list", 60_000, [pb(kit), "list", "--json"], { version: "", cards: [], ranAt: 0 });