@afokapu/atdd-bun 0.10.31 → 0.10.32

package/planner-schemas/delivery-evidence.schema.json

@@ -1,103 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Delivery Evidence Schema",
-  "description": "Validates one <delivery root>/<tranche>/evidence.yaml: the record a tranche leaves of who wrote each stage and of its reviews. Local shape only: stage completeness, allowed models and fallbacks, reviewer independence, finding outcomes and SHA resolution are cross-field validator concerns (src/delivery.ts).",
-  "$comment": "Shipped by the delivery profile (delivery_evidence). `reviews` is chronological: a repair loop appends a new entry for the same stage rather than editing the earlier one.",
-  "type": "object",
-  "required": ["tranche", "status", "reviews"],
-  "additionalProperties": false,
-  "properties": {
-    "tranche": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "Must equal the tranche folder name." },
-    "status": { "enum": ["open", "ready"], "description": "open: the lifecycle is in progress. ready: every configured stage is approved and approved_sha is the commit to merge." },
-    "base_sha": { "$ref": "#/definitions/sha", "$comment": "Informational: the commit the tranche started from. Not checked; the gate derives its range from Git." },
-    "approved_sha": { "$ref": "#/definitions/sha" },
-    "pr": { "type": "string", "minLength": 1, "$comment": "Informational: the pull request URL. Not checked." },
-    "work": { "type": "array", "items": { "$ref": "#/definitions/work" }, "description": "Who wrote each stage, in order: one entry per stage written, more after a repair." },
-    "reviews": { "type": "array", "items": { "$ref": "#/definitions/review" } }
-  },
-  "if": { "required": ["status"], "properties": { "status": { "const": "ready" } } },
-  "then": { "required": ["approved_sha"] },
-  "definitions": {
-    "sha": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
-    "actor": {
-      "type": "object",
-      "required": ["model", "run"],
-      "additionalProperties": false,
-      "properties": {
-        "model": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
-        "run": { "type": "string", "minLength": 1, "description": "Identifies the process: a session id, a pane id plus start time, or the report file. Two entries with the same run are the same process." }
-      }
-    },
-    "fallback": {
-      "type": "object",
-      "required": ["from", "kind", "reason"],
-      "additionalProperties": false,
-      "description": "Why a later model in the stage's list was used: counted failures of the preferred one, or the operator's order (kind operator), which references its ruling instead and is accepted only for a model the stage lists.",
-      "if": { "required": ["kind"], "properties": { "kind": { "const": "operator" } } },
-      "then": { "required": ["decided_by", "decided_at", "ruling"], "not": { "anyOf": [{ "required": ["failures"] }, { "required": ["window"] }] } },
-      "else": { "required": ["failures", "window"] },
-      "properties": {
-        "role": { "enum": ["writer", "author", "reviewer"], "description": "Which actor fell back; author is the 0.9 spelling of writer. Default: writer on a work entry, reviewer on a review." },
-        "from": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
-        "kind": { "enum": ["outage", "rate_limit", "no_report", "timeout", "operator"], "description": "Why the model counts as unavailable, or operator when the operator ordered the substitution. A verdict is never one of these." },
-        "failures": { "type": "integer", "minimum": 1, "description": "Failures observed before falling back; at least delivery.fallback.after_failures." },
-        "window": {
-          "type": "object",
-          "required": ["from", "to"],
-          "additionalProperties": false,
-          "description": "When the first and last counted failures happened; the span is at most delivery.fallback.within_minutes.",
-          "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }
-        },
-        "decided_by": { "type": "string", "minLength": 2, "description": "operator only: who ruled, by name or board identity. Never the driver on its own authority." },
-        "decided_at": { "type": "string", "format": "date-time", "description": "operator only: when the ruling was given." },
-        "ruling": { "type": "string", "minLength": 3, "description": "operator only: where the ruling is recorded (a board message id, an ADR or a PR)." },
-        "reason": { "type": "string", "minLength": 10, "description": "Why the preferred model was not used: an outage, a rate limit, no auditable report, or the operator's order. Never a verdict." }
-      }
-    },
-    "finding": {
-      "type": "object",
-      "required": ["id", "severity", "evidence", "invariant", "proposed_fix"],
-      "additionalProperties": false,
-      "properties": {
-        "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$", "description": "Stable across re-reviews, so an upheld finding keeps its id." },
-        "severity": { "enum": ["critical", "high", "medium", "low"] },
-        "evidence": { "type": "string", "minLength": 5, "description": "Concrete: file:line, a failing command, a counter-example." },
-        "invariant": { "type": "string", "minLength": 5 },
-        "affects": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-        "proposed_fix": { "type": "string", "minLength": 5, "description": "A precise correction for the author to apply; the reviewer never applies it." },
-        "rebuttal": { "type": "string", "minLength": 20, "description": "The author's written dispute, with evidence. One round only." },
-        "outcome": { "enum": ["fixed", "withdrawn", "human"] },
-        "decision": { "type": "string", "minLength": 5, "description": "The human's ruling when outcome is human." }
-      }
-    },
-    "work": {
-      "type": "object",
-      "required": ["stage", "sha", "writer"],
-      "additionalProperties": false,
-      "properties": {
-        "stage": { "enum": ["plan", "red", "green", "refactor", "final", "plan_review", "test_review", "code_review", "final_review"] },
-        "sha": { "$ref": "#/definitions/sha", "description": "The commit the stage's work ended at." },
-        "writer": { "$ref": "#/definitions/actor" },
-        "fallback": { "type": "array", "items": { "$ref": "#/definitions/fallback" } }
-      }
-    },
-    "review": {
-      "type": "object",
-      "required": ["stage", "sha", "reviewer", "verdict", "checked"],
-      "additionalProperties": false,
-      "properties": {
-        "stage": { "enum": ["plan", "red", "green", "refactor", "final", "plan_review", "test_review", "code_review", "final_review"], "description": "The stage reviewed. The 0.9 names read as plan, red, refactor and final." },
-        "sha": { "$ref": "#/definitions/sha" },
-        "author": { "$ref": "#/definitions/actor", "$comment": "0.9: the writer of the reviewed work. Records now name writers under work." },
-        "reviewer": { "$ref": "#/definitions/actor" },
-        "fallback": { "type": "array", "items": { "$ref": "#/definitions/fallback" } },
-        "verdict": { "enum": ["approve", "request_changes"] },
-        "checked": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Everything the reviewer went through, not only what failed." },
-        "findings": { "type": "array", "items": { "$ref": "#/definitions/finding" } },
-        "report": { "type": "string", "minLength": 1, "description": "Path of the retained raw reviewer output, inside the tranche's folder." }
-      },
-      "if": { "required": ["verdict"], "properties": { "verdict": { "const": "request_changes" } } },
-      "then": { "required": ["findings"], "properties": { "findings": { "minItems": 1 } } }
-    }
-  }
-}

package/src/board-ui.ts

@@ -1,91 +0,0 @@
-import { allowedTopics, DIRECTORY, format, read, type Message } from "./board";
-
-/** `atdd-bun chat` alone: a terminal view of the board, every topic in a panel on the left and the selected topic's
- * conversation on the right, refreshed every second. ntfy cannot list its topics, so the board keeps a directory
- * topic (atdd-topics) that atdd-bun chat post fills with each topic's name on its first message. */
-
-/** Every topic the directory names, in order. */
-export async function knownTopics(url: string): Promise<string[]> {
-  const entries = await read(url, [DIRECTORY]).catch(() => [] as Message[]);
-  return [...new Set(entries.map(entry => entry.raw.trim()).filter(topic => /^[A-Za-z0-9_-]{1,64}$/.test(topic)))].sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
-}
-
-export type UiState = { topics: string[]; messages: Map<string, Message[]>; selected: number; scroll: number; url: string };
-
-/** A topic's parent is the longest other topic it extends (atdd-p-t3-final-1 under atdd-p-t3 under atdd-p). */
-function tree(topics: string[]): Array<{ topic: string; depth: number; label: string }> {
-  return topics.map(topic => {
-    const ancestors = topics.filter(other => other !== topic && topic.startsWith(`${other}-`));
-    const parent = ancestors.sort((a, b) => b.length - a.length)[0];
-    return { topic, depth: ancestors.length, label: parent ? topic.slice(parent.length + 1) : topic };
-  });
-}
-
-const fit = (text: string, width: number) => text.length > width ? `${text.slice(0, Math.max(0, width - 1))}…` : text.padEnd(width);
-function wrap(text: string, width: number): string[] {
-  const out: string[] = [];
-  for (const line of text.split("\n")) {
-    if (!line) { out.push(""); continue; }
-    for (let i = 0; i < line.length; i += width) out.push(line.slice(i, i + width));
-  }
-  return out;
-}
-
-/** The screen as lines, without escape codes except the selection's inverse video: pure, so it can be tested. */
-export function render(state: UiState, width: number, height: number): string[] {
-  const left = Math.max(20, Math.min(40, Math.floor(width / 3))), right = Math.max(10, width - left - 3), rows = Math.max(1, height - 2);
-  const nodes = tree(state.topics), selected = nodes[state.selected]?.topic;
-  const panel = nodes.map((node, i) => {
-    const count = String(state.messages.get(node.topic)?.length ?? 0);
-    const text = `${"  ".repeat(node.depth)}${node.label}`;
-    const cell = `${fit(text, left - count.length - 1)} ${count}`;
-    return i === state.selected ? `\x1b[7m${cell}\x1b[0m` : cell;
-  });
-  if (!panel.length) panel.push(fit("no topics yet", left));
-  const body = selected ? (state.messages.get(selected) ?? []).flatMap(message => wrap(format(message), right)) : wrap("Nothing posted yet. Topics appear here as agents post to them.", right);
-  const end = Math.max(0, body.length - state.scroll), start = Math.max(0, end - rows), view = body.slice(start, end);
-  const first = Math.max(0, Math.min(state.selected - Math.floor(rows / 2), panel.length - rows));
-  const header = fit(` Delivery board  ${state.url}  ·  ${state.topics.length} topics  ·  ↑↓ topic  PgUp/PgDn scroll  q quit`, width);
-  const lines = [header, `${"─".repeat(left)}─┬─${"─".repeat(right)}`];
-  for (let row = 0; row < rows - 1; row++) lines.push(`${panel[first + row] ?? " ".repeat(left)} │ ${fit(view[row] ?? "", right)}`);
-  lines.push(fit(selected ? ` ${selected}${state.scroll ? `  (scrolled up ${state.scroll})` : ""}` : "", width));
-  return lines;
-}
-
-/** Runs the view until q. Without a terminal it prints the topic list and exits. */
-export async function runUi(url: string, env: Record<string, string | undefined> = process.env): Promise<number> {
-  const visible = async () => { const all = await knownTopics(url); return env.ATDD_AGENT ? all.filter(topic => allowedTopics(env).includes(topic)) : all; };
-  const state: UiState = { topics: [], messages: new Map(), selected: 0, scroll: 0, url };
-  const refresh = async () => {
-    state.topics = await visible();
-    for (const topic of state.topics) {
-      const known = state.messages.get(topic) ?? [], since = known.at(-1)?.id ?? "all";
-      const fresh = await read(url, [topic], since).catch(() => [] as Message[]);
-      if (fresh.length || !state.messages.has(topic)) state.messages.set(topic, [...known, ...fresh]);
-    }
-  };
-  await refresh();
-  if (!process.stdout.isTTY || !process.stdin.isTTY) {
-    for (const topic of state.topics) console.log(`${topic}  ${state.messages.get(topic)?.length ?? 0}`);
-    return 0;
-  }
-  const draw = () => process.stdout.write(`\x1b[H\x1b[2J${render(state, process.stdout.columns || 100, process.stdout.rows || 30).join("\n")}`);
-  process.stdout.write("\x1b[?1049h\x1b[?25l");
-  process.stdin.setRawMode(true); process.stdin.resume();
-  let done: (code: number) => void = () => {};
-  const finished = new Promise<number>(resolve => { done = resolve; });
-  const quit = () => { clearInterval(timer); process.stdin.setRawMode(false); process.stdin.pause(); process.stdout.write("\x1b[?25h\x1b[?1049l"); done(0); };
-  process.stdin.on("data", (data: Buffer) => {
-    const key = data.toString();
-    if (key === "q" || key === "\x03") return quit();
-    if (key === "\x1b[A" || key === "k") { state.selected = Math.max(0, state.selected - 1); state.scroll = 0; }
-    if (key === "\x1b[B" || key === "j") { state.selected = Math.min(state.topics.length - 1, state.selected + 1); state.scroll = 0; }
-    if (key === "\x1b[5~") state.scroll += 10;
-    if (key === "\x1b[6~") state.scroll = Math.max(0, state.scroll - 10);
-    draw();
-  });
-  process.stdout.on("resize", draw);
-  const timer = setInterval(async () => { await refresh(); draw(); }, 1000);
-  draw();
-  return finished;
-}

package/src/board.ts

@@ -1,222 +0,0 @@
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { runUi } from "./board-ui";
-
-/** The delivery board: a local ntfy server the coordinator, drivers, writers and reviewers talk through
- * (the delivery.board convention). One topic per level (program, tranche, review conversation); every message
- * carries a header naming its sender, recipients and subject. The board is where the work is visible; the
- * evidence record stays the only thing the delivery rules judge. */
-
-export const DEFAULT_BOARD_URL = "http://127.0.0.1:2586";
-const LOCAL_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
-const TOPIC_LIMIT = 64;
-/** The board's directory: one message per topic, its name, posted with the topic's first message. */
-export const DIRECTORY = "atdd-topics";
-
-/** The board is opt-in: on only when atdd-bun.yaml names delivery.board. Its URL is $ATDD_BOARD_URL, else
- * delivery.board.url, else the default; the environment moves the board on one machine but never switches it on. Only a
- * local address is accepted, so a wrong setting can never send a message to a public server. */
-export async function boardUrl(root = process.cwd(), env: Record<string, string | undefined> = process.env): Promise<string> {
-  let board: unknown;
-  const file = join(root, "atdd-bun.yaml");
-  if (existsSync(file)) try { board = (Bun.YAML.parse(await readFile(file, "utf8")) as { delivery?: { board?: unknown } } | null)?.delivery?.board; } catch { /* reported by delivery.config-schema */ }
-  if (!board || typeof board !== "object" || Array.isArray(board)) throw new Error("the board is not enabled; add delivery.board to atdd-bun.yaml (for example board: { url: http://127.0.0.1:2586 }) to have agents talk through it");
-  const configured = (board as { url?: unknown }).url;
-  return localUrl(env.ATDD_BOARD_URL || (typeof configured === "string" ? configured : DEFAULT_BOARD_URL));
-}
-
-export function localUrl(raw: string): string {
-  let url: URL;
-  try { url = new URL(raw); } catch { throw new Error(`board URL ${raw} is not a URL`); }
-  if (!/^https?:$/.test(url.protocol) || !LOCAL_HOSTS.has(url.hostname)) throw new Error(`board URL ${raw} is not local; the board runs on this machine (127.0.0.1, localhost or [::1])`);
-  return `${url.protocol}//${url.host}`;
-}
-
-/** A topic name derived from its level: atdd-<program>[-<tranche>[-<stage>-<round>]]. Parts are lowercased and
- * reduced to [a-z0-9-]; a name longer than ntfy's 64 characters keeps its start and a hash of the whole. */
-export function topicName(program: string, tranche?: string, stage?: string, round?: string | number): string {
-  const parts = [program, tranche, stage, round === undefined ? undefined : String(round)].filter((part): part is string => part !== undefined && part !== "");
-  if (!parts.length) throw new Error("a topic needs at least the program name");
-  if (stage !== undefined && round === undefined) throw new Error("a review conversation topic needs its stage and round");
-  const slug = (part: string) => part.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  const name = ["atdd", ...parts.map(slug)].join("-");
-  if (name.length <= TOPIC_LIMIT) return name;
-  const hash = createHash("sha256").update(name).digest("hex").slice(0, 8);
-  return `${name.slice(0, TOPIC_LIMIT - 9).replace(/-+$/, "")}-${hash}`;
-}
-
-/** Topics this agent may use, from $ATDD_TOPICS (comma-separated), given by whoever launched it. */
-export function allowedTopics(env: Record<string, string | undefined> = process.env): string[] {
-  return (env.ATDD_TOPICS ?? "").split(",").map(topic => topic.trim()).filter(Boolean);
-}
-
-export function checkTopic(topic: string, env: Record<string, string | undefined> = process.env): void {
-  if (!/^[A-Za-z0-9_-]{1,64}$/.test(topic)) throw new Error(`${topic} is not a topic name; derive one with atdd-bun chat topic`);
-  const allowed = allowedTopics(env);
-  if (!allowed.includes(topic)) throw new Error(`${topic} is not one of this agent's topics (ATDD_TOPICS: ${allowed.join(", ") || "none"}); an agent reads and writes only the topics it was launched with`);
-}
-
-export const HEADER_FIELDS = ["kind", "stage", "reply-to", "repo", "branch", "worktree", "goal", "base", "sha"] as const;
-export type Header = { from: string; to: string[]; participants: string[]; conversation: string } & Partial<Record<(typeof HEADER_FIELDS)[number], string>>;
-export type Message = { id: string; time: number; topic: string; header: Partial<Header>; body: string; raw: string };
-
-export function envelope(header: Header, body: string): string {
-  const value = (v: string | string[]) => Array.isArray(v) ? `[${v.join(", ")}]` : JSON.stringify(v);
-  return `---\n${Object.entries(header).filter(([, v]) => v !== undefined).map(([k, v]) => `${k}: ${value(v as string | string[])}`).join("\n")}\n---\n${body.trim()}`;
-}
-
-export function parseEnvelope(text: string): { header: Partial<Header>; body: string } {
-  const match = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-  if (!match) return { header: {}, body: text };
-  try { return { header: (Bun.YAML.parse(match[1]) ?? {}) as Partial<Header>, body: match[2] }; } catch { return { header: {}, body: text }; }
-}
-
-const addressedTo = (message: Message, agent: string) => [message.header.to ?? []].flat().includes(agent);
-
-/** Posts with a few retries (a busy or restarting board), then fails loudly: a message is never silently lost. The first
- * message on a topic also names the topic in the directory, so the board's view can list it. */
-export async function post(url: string, topic: string, header: Header, body: string): Promise<string> {
-  const first = await fetch(`${url}/${topic}/json?poll=1&since=latest`).then(res => res.ok ? res.text() : "x").then(text => !text.trim()).catch(() => false);
-  let error = "";
-  for (let attempt = 0; attempt < 5; attempt++) {
-    try {
-      const res = await fetch(`${url}/${topic}`, { method: "POST", body: envelope(header, body), headers: { Title: `${header.from} -> ${header.to.join(", ")}` } });
-      if (res.ok) {
-        const id = (await res.json() as { id: string }).id;
-        if (first) await fetch(`${url}/${DIRECTORY}`, { method: "POST", body: topic }).catch(() => undefined);
-        return id;
-      }
-      error = `${res.status} ${await res.text()}`;
-    } catch (e) { error = String(e); }
-    await Bun.sleep(250 * 2 ** attempt);
-  }
-  throw new Error(`post to ${topic} failed: ${error}`);
-}
-
-/** Every message on the topics after `since` (a message id, or "all"). */
-export async function read(url: string, topics: string[], since = "all", signal?: AbortSignal): Promise<Message[]> {
-  const res = await fetch(`${url}/${topics.join(",")}/json?poll=1&since=${since}`, { signal });
-  if (!res.ok) throw new Error(`reading ${topics.join(", ")} failed: ${res.status} ${await res.text()}`);
-  return (await res.text()).split("\n").filter(Boolean).map(line => JSON.parse(line)).filter(m => m.event === "message")
-    .map(m => ({ id: m.id, time: m.time, topic: m.topic, raw: m.message, ...parseEnvelope(m.message) }));
-}
-
-/** Waits for the next message addressed to `agent` on any of `topics` after `since`, passing over the kinds in `skip`.
- * It polls rather than streams: a live stream can drop a message published while it connects. ntfy reads `since` (a
- * message id) as that message's time on every topic, so one cursor serves several topics. Returns null after
- * `timeoutSeconds`, so an agent's tool call stays bounded. */
-/** The longest one poll may take. ntfy answers a poll at once, so only a stalled request ever reaches it. */
-const POLL_LIMIT_MS = 10_000;
-
-/** What a listener prints when nothing has arrived for a while: the owner's check-in, for the agent to act on (move
- * the work, or tell whoever it waits on), never to answer with a "still here" post. */
-export function checkIn(agent: string, quietSeconds: number, rearm = false): string {
-  const quiet = quietSeconds <= 0 ? "" : quietSeconds < 60 ? ` for ${quietSeconds} s` : ` for ${Math.round(quietSeconds / 60)} min`;
-  return `CHECK-IN for ${agent}: no message${quiet}. Where are you? Are you moving forward, or blocked on someone, and do they know? Is your stakeholder informed? Are you avoiding ceremony and rabbit holes, effectiveness first, then efficiency? Act on it: move the work, or post once to whoever you wait on; never post just to say you are still here.${rearm ? " Then re-arm this listener." : ""}`;
-}
-
-export async function waitFor(url: string, topics: string[], agent: string, since = "all", timeoutSeconds = 0, skip: string[] = [], intervalMs = 500, seen: (id: string) => void = () => {}): Promise<Message | null> {
-  const deadline = timeoutSeconds > 0 ? Date.now() + timeoutSeconds * 1000 : Infinity;
-  for (;;) {
-    let messages: Message[] = [];
-    // Each poll is bounded: a request that never answers (a half-open connection after the board restarts or the
-    // machine sleeps) would otherwise hold the wait past its deadline and deliver nothing. It counts as unavailable.
-    const bound = AbortSignal.timeout(Math.max(1, Math.min(POLL_LIMIT_MS, deadline - Date.now())));
-    try { messages = await read(url, topics, since, bound); } catch { /* the board is briefly unavailable: keep waiting */ }
-    for (const message of messages) { since = message.id; seen(since); if (addressedTo(message, agent) && !skip.includes(message.header.kind ?? "")) return message; }
-    if (Date.now() >= deadline) return null;
-    await Bun.sleep(intervalMs);
-  }
-}
-
-/** Where `wait` keeps its place, per identity and topic set, so restarting a watcher is always the same command.
- * Best effort: where the file cannot be read or written, wait behaves as if it had no saved place. */
-function cursorFile(agent: string, topics: string[], env: Record<string, string | undefined>): string {
-  const key = `${agent}__${[...topics].sort().join("+")}`.replace(/[^A-Za-z0-9@+_.-]/g, "_");
-  return join(env.ATDD_BOARD_STATE || join(homedir(), ".atdd-board", "cursors"), key);
-}
-const loadCursor = (file: string) => { try { return readFileSync(file, "utf8").trim() || undefined; } catch { return undefined; } };
-/** The place to start from on a topic set this identity has never listened to: its OLDEST saved place on any other set,
- * so nothing unread is skipped and nothing older is replayed. Without one, the start of the board, as before. */
-function seedCursor(agent: string, env: Record<string, string | undefined>): string | undefined {
-  const dir = env.ATDD_BOARD_STATE || join(homedir(), ".atdd-board", "cursors"), prefix = `${agent}__`.replace(/[^A-Za-z0-9@+_.-]/g, "_");
-  try {
-    const saved = readdirSync(dir).filter(name => name.startsWith(prefix)).map(name => ({ file: join(dir, name), at: statSync(join(dir, name)).mtimeMs })).sort((a, b) => a.at - b.at);
-    for (const { file } of saved) { const id = loadCursor(file); if (id) return id; }
-  } catch { /* no saved places */ }
-  return undefined;
-}
-const saveCursor = (file: string, id: string) => { try { mkdirSync(join(file, ".."), { recursive: true }); writeFileSync(file, `${id}\n`); } catch { /* best effort */ } };
-
-export function format(message: Message, withTopic = false): string {
-  const time = new Date(message.time * 1000).toTimeString().slice(0, 8), h = message.header;
-  const route = `${h.from ?? "?"} -> ${[h.to ?? []].flat().join(", ") || "?"}`, tags = [h.kind, h.stage].filter(Boolean).join(" · ");
-  return `${withTopic ? `[${message.topic}] ` : ""}${time}  ${route}${tags ? `  (${tags})` : ""}  #${message.id}\n${message.body.trim()}\n`;
-}
-
-/** `atdd-bun chat` opens the board's terminal view; `atdd-bun chat <topic|post|read|wait> …` is for agents.
- * Returns the exit code: 0 done, 1 error, 2 wait timed out. */
-export async function chat(args: string[], env: Record<string, string | undefined> = process.env, root = process.cwd()): Promise<number> {
-  const [command, ...rest] = args;
-  const flag = (name: string) => { const i = rest.indexOf(`--${name}`); return i >= 0 ? rest[i + 1] : undefined; };
-  const list = (value?: string) => (value ?? "").split(",").map(item => item.trim()).filter(Boolean);
-  const positional = rest.filter((arg, i) => !arg.startsWith("--") && !(i > 0 && rest[i - 1].startsWith("--") && rest[i - 1] !== "--mine"));
-  const agent = () => { if (!env.ATDD_AGENT) throw new Error("ATDD_AGENT is not set: every agent is launched with its identity"); return env.ATDD_AGENT; };
-  try {
-    if (command === "topic") { console.log(topicName(positional[0], positional[1], positional[2], positional[3])); return 0; }
-    const url = await boardUrl(root, env);
-    if (command === undefined) return await runUi(url, env);
-    const topics = list(positional[0]);
-    if (!topics.length) throw new Error(`usage: atdd-bun chat ${command} <topic> …`);
-    const me = agent();
-    topics.forEach(topic => checkTopic(topic, env));
-    if (command === "wait") {
-      // Without --since, continue from where this identity last stopped on these topics; either way, remember the place.
-      const file = cursorFile(me, topics, env);
-      const message = await waitFor(url, topics, me, flag("since") || loadCursor(file) || seedCursor(me, env) || "all", Number(flag("timeout") ?? 0), list(flag("skip")), 500, id => saveCursor(file, id));
-      if (!message) { console.log(checkIn(me, Number(flag("timeout") ?? 0), true)); return 2; }
-      console.log(format(message, topics.length > 1));
-      return 0;
-    }
-    if (command === "follow") {
-      // The listener for a host that wakes its agent on each line a running process prints: every message addressed to
-      // this identity, as it arrives, until --timeout (seconds; none = until stopped). Same place-keeping as wait.
-      const file = cursorFile(me, topics, env), skip = list(flag("skip")), total = Number(flag("timeout") ?? 0);
-      const deadline = total > 0 ? Date.now() + total * 1000 : Infinity;
-      let since = flag("since") || loadCursor(file) || seedCursor(me, env) || "all";
-      // After --check-in seconds without a message (default 20 minutes; 0 = never), the agent is asked to check itself.
-      const quietLimit = Number(flag("check-in") ?? 1200) * 1000;
-      let quietSince = Date.now();
-      for (;;) {
-        const left = Math.ceil((deadline - Date.now()) / 1000);
-        if (left <= 0) return 0;
-        const message = await waitFor(url, topics, me, since, Math.min(60, left, quietLimit > 0 ? Math.max(1, Math.ceil((quietSince + quietLimit - Date.now()) / 1000)) : 60), skip, 500, id => { since = id; saveCursor(file, id); });
-        if (message) { console.log(format(message, topics.length > 1)); quietSince = Date.now(); }
-        else if (quietLimit > 0 && Date.now() - quietSince >= quietLimit) { console.log(checkIn(me, Math.round((Date.now() - quietSince) / 1000))); quietSince = Date.now(); }
-      }
-    }
-    if (topics.length !== 1) throw new Error(`${command} takes one topic`);
-    const topic = topics[0];
-    if (command === "post") {
-      const to = list(flag("to"));
-      if (!to.length) throw new Error("--to is required: every message names its recipients");
-      const body = await new Response(Bun.stdin.stream()).text();
-      if (!body.trim()) throw new Error("the message body is read from standard input and is empty");
-      const header: Header = { from: me, to, participants: [...new Set([me, ...to, ...list(flag("participants"))])], conversation: topic };
-      for (const field of HEADER_FIELDS) if (flag(field)) header[field] = flag(field);
-      console.log(await post(url, topic, header, body));
-      return 0;
-    }
-    if (command === "read") {
-      for (const message of await read(url, [topic], flag("since") || "all")) if (!rest.includes("--mine") || addressedTo(message, me)) console.log(format(message));
-      return 0;
-    }
-    throw new Error(`unknown chat command ${command}; run atdd-bun chat alone for the board, or topic, post, read, wait`);
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    return 1;
-  }
-}