proofdeck 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +23 -0
  3. package/README.md +152 -2
  4. package/README.zh-CN.md +152 -0
  5. package/bin/proofdeck.js +191 -0
  6. package/board/LICENSE +201 -0
  7. package/board/README.md +473 -0
  8. package/board/README.zh-CN.md +424 -0
  9. package/board/dist/_chk.db-shm +0 -0
  10. package/board/dist/_chk.db-wal +0 -0
  11. package/board/dist/adapters.d.ts +40 -0
  12. package/board/dist/adapters.d.ts.map +1 -0
  13. package/board/dist/adapters.js +124 -0
  14. package/board/dist/adapters.js.map +1 -0
  15. package/board/dist/board.d.ts +628 -0
  16. package/board/dist/board.d.ts.map +1 -0
  17. package/board/dist/board.js +2767 -0
  18. package/board/dist/board.js.map +1 -0
  19. package/board/dist/cli.d.ts +3 -0
  20. package/board/dist/cli.d.ts.map +1 -0
  21. package/board/dist/cli.js +1663 -0
  22. package/board/dist/cli.js.map +1 -0
  23. package/board/dist/config.d.ts +57 -0
  24. package/board/dist/config.d.ts.map +1 -0
  25. package/board/dist/config.js +99 -0
  26. package/board/dist/config.js.map +1 -0
  27. package/board/dist/db.d.ts +9 -0
  28. package/board/dist/db.d.ts.map +1 -0
  29. package/board/dist/db.js +506 -0
  30. package/board/dist/db.js.map +1 -0
  31. package/board/dist/git.d.ts +35 -0
  32. package/board/dist/git.d.ts.map +1 -0
  33. package/board/dist/git.js +147 -0
  34. package/board/dist/git.js.map +1 -0
  35. package/board/dist/index.d.ts +18 -0
  36. package/board/dist/index.d.ts.map +1 -0
  37. package/board/dist/index.js +13 -0
  38. package/board/dist/index.js.map +1 -0
  39. package/board/dist/mcp-config.d.ts +26 -0
  40. package/board/dist/mcp-config.d.ts.map +1 -0
  41. package/board/dist/mcp-config.js +88 -0
  42. package/board/dist/mcp-config.js.map +1 -0
  43. package/board/dist/mcp.d.ts +3 -0
  44. package/board/dist/mcp.d.ts.map +1 -0
  45. package/board/dist/mcp.js +949 -0
  46. package/board/dist/mcp.js.map +1 -0
  47. package/board/dist/quickstart.d.ts +75 -0
  48. package/board/dist/quickstart.d.ts.map +1 -0
  49. package/board/dist/quickstart.js +156 -0
  50. package/board/dist/quickstart.js.map +1 -0
  51. package/board/dist/serve.d.ts +10 -0
  52. package/board/dist/serve.d.ts.map +1 -0
  53. package/board/dist/serve.js +445 -0
  54. package/board/dist/serve.js.map +1 -0
  55. package/board/dist/signing.d.ts +18 -0
  56. package/board/dist/signing.d.ts.map +1 -0
  57. package/board/dist/signing.js +26 -0
  58. package/board/dist/signing.js.map +1 -0
  59. package/board/dist/sync.d.ts +49 -0
  60. package/board/dist/sync.d.ts.map +1 -0
  61. package/board/dist/sync.js +158 -0
  62. package/board/dist/sync.js.map +1 -0
  63. package/board/dist/types.d.ts +359 -0
  64. package/board/dist/types.d.ts.map +1 -0
  65. package/board/dist/types.js +20 -0
  66. package/board/dist/types.js.map +1 -0
  67. package/board/docs/adr/0001-shared-worktree-collision.md +102 -0
  68. package/board/docs/adr/0001-shared-worktree-collision.zh-CN.md +90 -0
  69. package/board/docs/attribution.md +123 -0
  70. package/board/docs/attribution.zh-CN.md +104 -0
  71. package/board/docs/development-workflow.md +81 -0
  72. package/board/docs/development-workflow.zh-CN.md +75 -0
  73. package/board/docs/diagrams/banner.png +0 -0
  74. package/board/docs/diagrams/banner.svg +1 -0
  75. package/board/docs/diagrams/before-after.png +0 -0
  76. package/board/docs/diagrams/before-after.svg +1 -0
  77. package/board/docs/diagrams/governance-chain.png +0 -0
  78. package/board/docs/diagrams/governance-chain.svg +1 -0
  79. package/board/docs/diagrams/value-flow.png +0 -0
  80. package/board/docs/diagrams/value-flow.svg +1 -0
  81. package/board/docs/entry-point.md +81 -0
  82. package/board/docs/entry-point.zh-CN.md +65 -0
  83. package/board/docs/kanban.png +0 -0
  84. package/board/docs/octoryn-mark.png +0 -0
  85. package/board/docs/registry-metadata.md +34 -0
  86. package/board/docs/registry-metadata.zh-CN.md +30 -0
  87. package/board/package.json +87 -0
  88. package/config.example.json +72 -0
  89. package/daemon.js +1148 -0
  90. package/docs/assets/demo.gif +0 -0
  91. package/docs/assets/logo-512.png +0 -0
  92. package/docs/assets/logo.svg +31 -0
  93. package/docs/assets/social-preview.png +0 -0
  94. package/docs/demo-run.mjs +61 -0
  95. package/docs/render-demo.py +94 -0
  96. package/docs/render-logo.py +101 -0
  97. package/docs/task-book.md +58 -0
  98. package/e2e/verify-acceptance.mjs +150 -0
  99. package/e2e/verify-antifraud.mjs +128 -0
  100. package/e2e/verify-caps.mjs +46 -0
  101. package/e2e/verify-checkpoint.mjs +208 -0
  102. package/e2e/verify-firstclass.mjs +110 -0
  103. package/e2e/verify-judge.mjs +52 -0
  104. package/e2e/verify-lease.mjs +95 -0
  105. package/e2e/verify-replay.mjs +92 -0
  106. package/e2e/verify-resilience.mjs +323 -0
  107. package/e2e/verify-review.mjs +86 -0
  108. package/e2e/verify-scheduling.mjs +110 -0
  109. package/e2e/verify-schema-evolution.mjs +107 -0
  110. package/e2e/verify-sla-digest.mjs +105 -0
  111. package/guard.js +97 -0
  112. package/lib/adapters/codex.js +206 -0
  113. package/lib/billing-convert.js +57 -0
  114. package/lib/board.js +46 -0
  115. package/lib/caps.js +35 -0
  116. package/lib/checkpoint.js +130 -0
  117. package/lib/gating.js +218 -0
  118. package/lib/guard-core.mjs +108 -0
  119. package/lib/http.js +161 -0
  120. package/lib/judge.js +89 -0
  121. package/lib/lease.js +93 -0
  122. package/lib/notify.js +56 -0
  123. package/lib/platform.js +120 -0
  124. package/lib/replay.js +68 -0
  125. package/lib/review.js +40 -0
  126. package/lib/runner.js +152 -0
  127. package/lib/schedule.js +59 -0
  128. package/lib/sla.js +42 -0
  129. package/lib/spans.js +36 -0
  130. package/lib/starve.js +43 -0
  131. package/lib/store.js +109 -0
  132. package/lib/supply.js +101 -0
  133. package/lib/usage.js +103 -0
  134. package/lib/verify.js +223 -0
  135. package/lib/watchdog-core.mjs +68 -0
  136. package/lib/watchdog-worker.mjs +75 -0
  137. package/package.json +55 -4
  138. package/scripts/run-daemon.sh +18 -0
  139. package/scripts/run-e2e.mjs +39 -0
@@ -0,0 +1,1663 @@
1
+ #!/usr/bin/env node
2
+ import { existsSync, readFileSync, writeFileSync } from "node:fs";
3
+ import { Command } from "commander";
4
+ import { Board } from "./board.js";
5
+ import { loadConfig } from "./config.js";
6
+ import { serve } from "./serve.js";
7
+ import { createSyncTarget } from "./sync.js";
8
+ import { ADAPTERS, getAdapter } from "./adapters.js";
9
+ import { MCP_CLIENTS, mcpConfig } from "./mcp-config.js";
10
+ import { renderQuickstart, runQuickstart } from "./quickstart.js";
11
+ import * as git from "./git.js";
12
+ const program = new Command();
13
+ program
14
+ .name("octoboard")
15
+ .description("Octopus Blackboard — shared memory & AI attribution for coding agents")
16
+ .version("0.2.4")
17
+ .option("--board <dir>", "board directory (defaults to nearest .octoboard/)")
18
+ .option("--as <agent>", "identity to write as (or set OCTOBOARD_AGENT)")
19
+ .option("--provider <provider>", "agent provider, e.g. anthropic, openai, local")
20
+ .option("--model <model>", "agent model, e.g. claude-opus-4-8")
21
+ .option("--cli <cli>", "agent CLI / surface, e.g. claude-code")
22
+ .option("--session <id>", "act within a specific session (or set OCTOBOARD_SESSION)");
23
+ /** Config overrides from the global identity flags. */
24
+ function overrides() {
25
+ const o = program.opts();
26
+ if (o.session) {
27
+ process.env.OCTOBOARD_SESSION = o.session;
28
+ }
29
+ return {
30
+ boardDir: o.board,
31
+ agent: o.as,
32
+ provider: o.provider,
33
+ model: o.model,
34
+ cli: o.cli,
35
+ };
36
+ }
37
+ /** Build a Board honoring the global identity flags. */
38
+ function board() {
39
+ return Board.open(overrides());
40
+ }
41
+ /** The resolved agent identity for this invocation. */
42
+ function actor() {
43
+ return loadConfig(overrides()).agent;
44
+ }
45
+ function printJson(value) {
46
+ console.log(JSON.stringify(value, null, 2));
47
+ }
48
+ /**
49
+ * Render a project report as the three-level drilldown tree:
50
+ * project -> tasks grouped by stream -> per-task status/progress + trace counts.
51
+ * Shared by `project show` and `report --project` so the two never drift apart.
52
+ * Pure read: it only formats what projectReport() already returned.
53
+ */
54
+ function renderProjectReport(rep) {
55
+ const p = rep.project;
56
+ console.log(`\u2500\u2500 ${p.name} (${p.key}) \u2500\u2500\u2500 [${p.status}]`);
57
+ if (p.description)
58
+ console.log(` what: ${p.description}`);
59
+ console.log(` created by ${p.createdBy} at ${p.createdAt}`);
60
+ console.log(` streams: ${Array.isArray(p.streams) && p.streams.length ? p.streams.join(" / ") : "(none declared \u2014 any stream accepted)"}`);
61
+ console.log(` tasks: ${rep.tasks.total} ${JSON.stringify(rep.tasks.byStatus)}`);
62
+ console.log(` trace: ${JSON.stringify(rep.trace)}`);
63
+ console.log(` timeline: ${rep.timeline.total} event(s)${rep.timeline.firstSeq ? ` (seq ${rep.timeline.firstSeq}\u2013${rep.timeline.lastSeq})` : ""}`);
64
+ const cards = rep.tasks.cards ?? [];
65
+ if (cards.length === 0) {
66
+ console.log(" (no tasks)");
67
+ return;
68
+ }
69
+ console.log(" legend: #N [status] progress key (assignee) tl=timeline rk=risks ev=evidence ss=sessions");
70
+ const groups = new Map();
71
+ for (const c of cards) {
72
+ const s = c.task.stream == null || c.task.stream === "" ? "(no stream)" : c.task.stream;
73
+ if (!groups.has(s))
74
+ groups.set(s, []);
75
+ groups.get(s).push(c);
76
+ }
77
+ const keys = [...groups.keys()].sort((a, b) => {
78
+ if (a === "(no stream)")
79
+ return 1;
80
+ if (b === "(no stream)")
81
+ return -1;
82
+ return a.localeCompare(b, "zh");
83
+ });
84
+ keys.forEach((s, gi) => {
85
+ const list = groups.get(s);
86
+ const last = gi === keys.length - 1;
87
+ console.log(` ${last ? "\u2514\u2500" : "\u251c\u2500"} ${s} (${list.length})`);
88
+ const pad = last ? " " : "\u2502 ";
89
+ for (const c of list) {
90
+ const t = c.task;
91
+ const prog = `${String(t.progress ?? 0).padStart(3)}%`;
92
+ const who = c.assignees && c.assignees.length ? c.assignees.join(",") : "\u2014";
93
+ const tr = c.trace ?? {};
94
+ const trs = `tl:${tr.timeline ?? 0} rk:${tr.risks ?? 0} ev:${tr.evidence ?? 0} ss:${tr.sessions ?? 0}`;
95
+ const title = t.title ? ` ${t.title}` : "";
96
+ console.log(`${pad} #${String(t.number ?? "?").padEnd(4)} [${String(t.status ?? "").padEnd(6)}] ${prog} ${t.key}${title} (${who}) ${trs}`);
97
+ }
98
+ });
99
+ }
100
+ program
101
+ .command("init")
102
+ .description("create a board in the current directory (.octoboard/)")
103
+ .action(() => {
104
+ const cfg = loadConfig(program.opts().board ? { boardDir: program.opts().board } : {});
105
+ const existed = existsSync(cfg.dbPath);
106
+ const b = new Board(cfg);
107
+ b.close();
108
+ console.log(existed
109
+ ? `Board already present at ${cfg.dbPath}`
110
+ : `Initialized board at ${cfg.dbPath}`);
111
+ });
112
+ program
113
+ .command("quickstart")
114
+ .description("zero-config onboarding: init the board, detect your MCP client, print a paste-ready config")
115
+ .option("--client <client>", `force a client instead of auto-detecting: ${MCP_CLIENTS.join(" | ")}`)
116
+ .option("--agent <name>", "identity the connected client writes under (defaults to the client id)")
117
+ .option("--no-probe", "skip the one-write + one-read proof step")
118
+ .option("--local <entry>", "use a local build path instead of the npx bin (dev)")
119
+ .action((opts) => {
120
+ if (opts.client && !MCP_CLIENTS.includes(opts.client)) {
121
+ console.error(`Unknown client '${opts.client}'. Available: ${MCP_CLIENTS.join(", ")}`);
122
+ process.exitCode = 1;
123
+ return;
124
+ }
125
+ const result = runQuickstart({
126
+ cwd: process.cwd(),
127
+ client: opts.client,
128
+ agent: opts.agent,
129
+ noProbe: opts.probe === false,
130
+ localEntry: opts.local,
131
+ });
132
+ console.log(renderQuickstart(result));
133
+ if (result.probe && !result.probe.chainOk) {
134
+ process.exitCode = 1;
135
+ }
136
+ });
137
+ program
138
+ .command("status")
139
+ .description("show who is on the board, open work, unread messages, open risks")
140
+ .option("--json", "output raw JSON")
141
+ .action((opts) => {
142
+ const b = board();
143
+ const status = b.status(actor());
144
+ const chain = b.verifyChain();
145
+ b.close();
146
+ if (opts.json) {
147
+ printJson({ ...status, chain });
148
+ return;
149
+ }
150
+ renderStatus(status, chain);
151
+ });
152
+ program
153
+ .command("note")
154
+ .argument("<text>", "free-form status broadcast to the board")
155
+ .option("--project <key>", "scope the note to a project")
156
+ .option("--task <key>", "scope the note to a task")
157
+ .description("leave a note on the board")
158
+ .action((text, opts) => {
159
+ const b = board();
160
+ if (opts.project && !b.projectExists(opts.project)) {
161
+ console.warn(`\u26a0 unknown project "${opts.project}" (not rejected \u2014 declare it via 'project add' to enable stream validation).`);
162
+ }
163
+ const ev = b.note(actor(), text, { project: opts.project ?? null, taskKey: opts.task ?? null });
164
+ b.close();
165
+ console.log(`#${ev.seq} note by ${ev.actor}`);
166
+ });
167
+ program
168
+ .command("claim")
169
+ .argument("<key>", "task key to claim, e.g. trust-layer-policy-schema")
170
+ .option("--title <title>", "human title for the task")
171
+ .description("claim a task (surfaces a conflict if another agent holds it)")
172
+ .action((key, opts) => {
173
+ const b = board();
174
+ const result = b.claim(actor(), key, opts.title ?? null);
175
+ b.close();
176
+ if (result.conflict) {
177
+ console.warn(`⚠ CONFLICT: "${key}" is also held by ${result.conflict}. Both claims recorded.`);
178
+ }
179
+ else {
180
+ console.log(`Claimed "${key}".`);
181
+ }
182
+ });
183
+ program
184
+ .command("release")
185
+ .argument("<key>", "task key to release")
186
+ .description("release a task you claimed")
187
+ .action((key) => {
188
+ const b = board();
189
+ const task = b.release(actor(), key);
190
+ b.close();
191
+ console.log(task ? `Released "${key}".` : `No task "${key}".`);
192
+ });
193
+ program
194
+ .command("done")
195
+ .argument("<key>", "task key to mark complete")
196
+ .description("mark a task done")
197
+ .action((key) => {
198
+ const b = board();
199
+ const task = b.complete(actor(), key);
200
+ b.close();
201
+ console.log(task ? `Completed "${key}".` : `No task "${key}".`);
202
+ });
203
+ // --- projects (four-layer: board -> project -> task -> trace) ----------------
204
+ // NOTE: nothing here auto-creates a project. `project add` is the only writer,
205
+ // and it is always explicit + attributed (hard constraint #3: agents must not
206
+ // silently create projects).
207
+ const project = program.command("project").description("create & inspect projects");
208
+ project
209
+ .command("add")
210
+ .argument("<key>", "project key, e.g. xijiangyue")
211
+ .option("--name <name>", "human-facing name (defaults to the key)")
212
+ .option("--desc <text>", "what the project is")
213
+ .option("--status <state>", "active | paused | archived", "active")
214
+ .option("--streams <list>", "controlled stream vocabulary (comma-separated, or a JSON array)")
215
+ .description("create or update a project (records who created it)")
216
+ .action((key, opts) => {
217
+ const b = board();
218
+ let p;
219
+ try {
220
+ p = b.createProject(actor(), key, {
221
+ name: opts.name ?? null,
222
+ description: opts.desc ?? null,
223
+ status: opts.status,
224
+ streams: opts.streams ?? null,
225
+ });
226
+ }
227
+ catch (e) {
228
+ b.close();
229
+ console.log(`Error: ${e.message}`);
230
+ return;
231
+ }
232
+ b.close();
233
+ const streams = p.streams && p.streams.length ? `, streams: ${p.streams.join("/")}` : "";
234
+ console.log(`Project "${p.key}" saved (${p.status}, created by ${p.createdBy}${streams}).`);
235
+ });
236
+ project
237
+ .command("list")
238
+ .option("--json", "output raw JSON")
239
+ .description("list all projects (with live task counts)")
240
+ .action((opts) => {
241
+ const b = board();
242
+ const ps = b.listProjects();
243
+ b.close();
244
+ if (opts.json)
245
+ return printJson(ps);
246
+ if (ps.length === 0) {
247
+ console.log("No projects yet.");
248
+ return;
249
+ }
250
+ console.log("KEY".padEnd(28) + "STATUS".padEnd(11) + "TASKS CREATED BY");
251
+ for (const p of ps)
252
+ console.log(`${p.key.padEnd(28)}${p.status.padEnd(11)}${String(p.taskCount).padEnd(7)}${p.createdBy}`);
253
+ });
254
+ project
255
+ .command("show")
256
+ .argument("<key>", "project key")
257
+ .option("--json", "output raw JSON")
258
+ .description("show a project: its tasks and trace summary (three-level)")
259
+ .action((key, opts) => {
260
+ const b = board();
261
+ const rep = b.projectReport(key);
262
+ b.close();
263
+ if (!rep) {
264
+ console.log(`No project '${key}'.`);
265
+ return;
266
+ }
267
+ if (opts.json)
268
+ return printJson(rep);
269
+ renderProjectReport(rep);
270
+ });
271
+ project
272
+ .command("status")
273
+ .argument("<key>", "project key")
274
+ .argument("<state>", "active | paused | archived")
275
+ .description("set a project's lifecycle status")
276
+ .action((key, state) => {
277
+ const b = board();
278
+ let updated;
279
+ try {
280
+ updated = b.setProjectStatus(actor(), key, state);
281
+ }
282
+ catch (e) {
283
+ b.close();
284
+ console.log(`Error: ${e.message}`);
285
+ return;
286
+ }
287
+ b.close();
288
+ console.log(updated ? `Project "${key}" \u2192 ${state}.` : `No project '${key}'.`);
289
+ });
290
+ // --- tasks (kanban) ----------------------------------------------------------
291
+ const task = program.command("task").description("define & inspect tasks");
292
+ task
293
+ .command("add")
294
+ .argument("<key>", "task key, e.g. trust-layer-policy-schema")
295
+ .option("--title <title>", "short title")
296
+ .option("--desc <text>", "what the task is")
297
+ .option("--project <name>", "project/repo it belongs to")
298
+ .option("--stream <name>", "sub-line within the project")
299
+ .option("--impact <text>", "change surface / blast radius")
300
+ .option("--risk <level>", "low | medium | high")
301
+ .description("create or update a task's kanban fields")
302
+ .action((key, opts) => {
303
+ const b = board();
304
+ // project existence is enforced by Board.defineTask (fail-closed). The old
305
+ // "(not rejected)" warn here would now lie, so it is dropped — single source.
306
+ const t = b.defineTask(actor(), key, {
307
+ title: opts.title ?? null,
308
+ description: opts.desc ?? null,
309
+ project: opts.project ?? null,
310
+ stream: opts.stream ?? null,
311
+ impact: opts.impact ?? null,
312
+ riskLevel: opts.risk ?? null,
313
+ });
314
+ b.close();
315
+ console.log(`Task #${t.number} "${t.key}" saved.`);
316
+ });
317
+ task
318
+ .command("show")
319
+ .argument("<ref>", "task key or number (#145)")
320
+ .option("--json", "output raw JSON")
321
+ .description("show a task's full kanban card")
322
+ .action((ref, opts) => {
323
+ const b = board();
324
+ const t = b.resolveTask(ref);
325
+ const card = t ? b.taskCard(t.key) : undefined;
326
+ b.close();
327
+ if (!card) {
328
+ console.log(`No task '${ref}'.`);
329
+ return;
330
+ }
331
+ if (opts.json)
332
+ return printJson(card);
333
+ const k = card.task;
334
+ console.log(`#${k.number} ${k.title ?? k.key} [${k.status}] ${k.progress}%`);
335
+ console.log(` key: ${k.key}${k.project ? ` project: ${k.project}` : ""}`);
336
+ if (k.description)
337
+ console.log(` what: ${k.description}`);
338
+ if (k.impact)
339
+ console.log(` impact: ${k.impact}`);
340
+ if (k.riskLevel)
341
+ console.log(` risk: ${k.riskLevel}`);
342
+ console.log(` assignees: ${card.assignees.join(", ") || "(none)"} active agents: ${card.activeAgents}`);
343
+ if (card.impactFiles.length)
344
+ console.log(` files touched: ${card.impactFiles.join(", ")}`);
345
+ for (const r of card.risks)
346
+ console.log(` ⚠ [${r.severity}] ${r.title}`);
347
+ });
348
+ task
349
+ .command("status")
350
+ .argument("<ref>", "task key or number")
351
+ .argument("<status>", "open | claimed | in-progress | blocked | done")
352
+ .description("set a task's status")
353
+ .action((ref, status) => {
354
+ const b = board();
355
+ const t = b.resolveTask(ref);
356
+ const updated = t ? b.setTaskStatus(actor(), t.key, status) : undefined;
357
+ b.close();
358
+ console.log(updated ? `#${updated.number} → ${status}.` : `No task '${ref}'.`);
359
+ });
360
+ program
361
+ .command("tasks")
362
+ .option("--json", "output raw JSON")
363
+ .option("--project <key>", "only tasks in this project")
364
+ .option("--stream <name>", "only tasks in this sub-line")
365
+ .description("list all tasks as kanban cards, grouped by status")
366
+ .action((opts) => {
367
+ const b = board();
368
+ const cards = b.listTaskCards({ project: opts.project, stream: opts.stream });
369
+ b.close();
370
+ if (opts.json)
371
+ return printJson(cards);
372
+ if (cards.length === 0) {
373
+ console.log("No tasks yet.");
374
+ return;
375
+ }
376
+ const columns = ["open", "claimed", "in-progress", "blocked", "done"];
377
+ for (const col of columns) {
378
+ const inCol = cards.filter((c) => c.task.status === col);
379
+ if (inCol.length === 0)
380
+ continue;
381
+ console.log(`\n── ${col.toUpperCase()} (${inCol.length}) ──`);
382
+ for (const c of inCol) {
383
+ const t = c.task;
384
+ const who = c.assignees.length
385
+ ? ` ←${c.assignees.join(",")}`
386
+ : t.claimedBy
387
+ ? ` ←${t.claimedBy}`
388
+ : "";
389
+ const agents = c.activeAgents > 0 ? ` ⚡${c.activeAgents}` : "";
390
+ const risk = t.riskLevel ? ` !${t.riskLevel}` : "";
391
+ console.log(` #${t.number} ${t.title ?? t.key} ${t.progress}%${who}${agents}${risk}`);
392
+ }
393
+ }
394
+ });
395
+ program
396
+ .command("assign")
397
+ .argument("<ref>", "task key or number (#145)")
398
+ .argument("<agent>", "agent to notify (e.g. claude, codex)")
399
+ .description("assign a task to an agent and drop a 'please look at #N' in their inbox")
400
+ .action((ref, agent) => {
401
+ const b = board();
402
+ const t = b.resolveTask(ref);
403
+ const updated = t ? b.assign(actor(), t.key, agent) : undefined;
404
+ b.close();
405
+ console.log(updated
406
+ ? `Assigned #${updated.number} to ${agent} — notification left in their inbox.`
407
+ : `No task '${ref}'.`);
408
+ });
409
+ program
410
+ .command("progress")
411
+ .argument("<ref>", "task key or number")
412
+ .argument("<percent>", "0–100")
413
+ .description("report task progress (moves it to in-progress, or done at 100)")
414
+ .action((ref, percentArg) => {
415
+ const percent = parseInt(percentArg, 10);
416
+ const b = board();
417
+ if (!Number.isInteger(percent)) {
418
+ b.close();
419
+ console.error("percent must be an integer 0–100.");
420
+ process.exitCode = 1;
421
+ return;
422
+ }
423
+ const t = b.resolveTask(ref);
424
+ const updated = t ? b.setProgress(actor(), t.key, percent) : undefined;
425
+ b.close();
426
+ console.log(updated
427
+ ? `#${updated.number} → ${updated.progress}% [${updated.status}].`
428
+ : `No task '${ref}'.`);
429
+ });
430
+ program
431
+ .command("message")
432
+ .argument("<agent>", "recipient agent, or 'all' to broadcast")
433
+ .argument("<body>", "message body")
434
+ .option("--project <key>", "scope the message to a project")
435
+ .option("--task <key>", "scope the message to a task")
436
+ .description("leave a message for another agent")
437
+ .action((agent, body, opts) => {
438
+ const b = board();
439
+ const to = agent === "all" ? null : agent;
440
+ if (opts.project && !b.projectExists(opts.project)) {
441
+ console.warn(`\u26a0 unknown project "${opts.project}" (not rejected \u2014 declare it via 'project add' to enable stream validation).`);
442
+ }
443
+ b.message(actor(), to, body, { project: opts.project ?? null, taskKey: opts.task ?? null });
444
+ b.close();
445
+ console.log(to ? `Message left for ${to}.` : "Broadcast to the board.");
446
+ });
447
+ program
448
+ .command("inbox")
449
+ .option("--all", "include already-read messages")
450
+ .option("--mark-read", "ack the messages shown, for your identity only")
451
+ .description("show what's waiting for you: messages and handoffs")
452
+ .action((opts) => {
453
+ const b = board();
454
+ const me = actor();
455
+ const messages = b.inbox(me, opts.all);
456
+ const handoffs = b.handoffsFor(me);
457
+ let acked = [];
458
+ if (opts.markRead) {
459
+ // Ack the ids we just listed, not a re-query, so a message that lands
460
+ // while we're printing stays unread for the next look.
461
+ acked = messages.map((m) => m.id);
462
+ for (const mid of acked)
463
+ b.markRead(mid, me);
464
+ }
465
+ b.close();
466
+ if (messages.length === 0 && handoffs.length === 0) {
467
+ console.log("Inbox empty.");
468
+ return;
469
+ }
470
+ for (const m of messages) {
471
+ const dest = m.toAgent ? "" : " (broadcast)";
472
+ console.log(`• ${m.fromAgent}${dest}: ${m.body}`);
473
+ }
474
+ for (const h of handoffs) {
475
+ const q = h.openQuestions.length > 0
476
+ ? ` (open: ${h.openQuestions.join("; ")})`
477
+ : "";
478
+ console.log(`⇢ handoff from ${h.fromAgent}: ${h.summary}${q}`);
479
+ }
480
+ if (acked.length > 0) {
481
+ console.log(`\n✓ acked ${acked.length} message(s) as ${me}.`);
482
+ }
483
+ });
484
+ program
485
+ .command("mark-read [messageId]")
486
+ .description("ack a message as seen, for your identity only (--all acks the whole inbox)")
487
+ .option("--all", "ack every message currently in your inbox")
488
+ .option("--json", "output raw JSON")
489
+ .action((messageId, opts) => {
490
+ const b = board();
491
+ const me = actor();
492
+ if (!messageId && !opts.all) {
493
+ b.close();
494
+ console.error("Give a message id, or pass --all. Try: octoboard inbox");
495
+ process.exitCode = 1;
496
+ return;
497
+ }
498
+ const ids = opts.all
499
+ ? b.markInboxRead(me)
500
+ : (() => {
501
+ if (!b.markRead(messageId, me)) {
502
+ b.close();
503
+ console.error(`No such message: ${messageId}. Try: octoboard inbox --all`);
504
+ process.exitCode = 1;
505
+ return null;
506
+ }
507
+ return [messageId];
508
+ })();
509
+ if (ids === null) {
510
+ return;
511
+ }
512
+ if (opts.json) {
513
+ printJson({ agent: me, acked: ids });
514
+ b.close();
515
+ return;
516
+ }
517
+ console.log(`✓ acked ${ids.length} message(s) as ${me}.`);
518
+ b.close();
519
+ });
520
+ program
521
+ .command("outbox")
522
+ .description("messages you dispatched that nobody has opened yet")
523
+ .option("--json", "output raw JSON")
524
+ .action((opts) => {
525
+ const b = board();
526
+ const me = actor();
527
+ const pending = b.pendingAcks(me);
528
+ const rows = pending.map((p) => ({ ...p, readers: b.readers(p.id).map((r) => r.agent) }));
529
+ b.close();
530
+ if (opts.json) {
531
+ printJson(rows);
532
+ return;
533
+ }
534
+ if (rows.length === 0) {
535
+ console.log(`Nothing outstanding — every message you sent has been acked.`);
536
+ return;
537
+ }
538
+ console.log(`${rows.length} message(s) sent by ${me} with no ack yet:`);
539
+ for (const r of rows) {
540
+ console.log(`• ${r.createdAt} → ${r.toAgent} ${r.id}`);
541
+ }
542
+ });
543
+ program
544
+ .command("handoffs")
545
+ .description("show handoffs left for you (what was passed to you)")
546
+ .option("--json", "output raw JSON")
547
+ .action((opts) => {
548
+ const b = board();
549
+ const handoffs = b.handoffsFor(actor());
550
+ b.close();
551
+ if (opts.json) {
552
+ printJson(handoffs);
553
+ return;
554
+ }
555
+ if (handoffs.length === 0) {
556
+ console.log("No handoffs for you.");
557
+ return;
558
+ }
559
+ for (const h of handoffs) {
560
+ console.log(`⇢ from ${h.fromAgent}${h.taskKey ? ` [${h.taskKey}]` : ""}: ${h.summary}`);
561
+ if (h.context)
562
+ console.log(` context: ${h.context}`);
563
+ if (h.relatedFiles.length)
564
+ console.log(` files: ${h.relatedFiles.join(", ")}`);
565
+ if (h.openQuestions.length)
566
+ console.log(` open questions: ${h.openQuestions.join("; ")}`);
567
+ }
568
+ });
569
+ program
570
+ .command("decision")
571
+ .argument("<title>", "the decision made")
572
+ .option("--why <rationale>", "rationale behind the decision")
573
+ .option("--evidence <ref>", "evidence pointer (path, URL, log)")
574
+ .option("--commit <sha...>", "related commit sha(s)")
575
+ .option("--task <key...>", "related task key(s)")
576
+ .option("--project <key>", "scope the decision to a project")
577
+ .description("record an architectural decision")
578
+ .action((title, opts) => {
579
+ const b = board();
580
+ if (opts.project && !b.projectExists(opts.project)) {
581
+ console.warn(`\u26a0 unknown project "${opts.project}" (not rejected \u2014 declare it via 'project add' to enable stream validation).`);
582
+ }
583
+ b.decision(actor(), title, {
584
+ rationale: opts.why ?? null,
585
+ evidence: opts.evidence ?? null,
586
+ relatedCommits: opts.commit ?? [],
587
+ relatedTasks: opts.task ?? [],
588
+ project: opts.project ?? null,
589
+ });
590
+ b.close();
591
+ console.log("Decision recorded.");
592
+ });
593
+ program
594
+ .command("evidence")
595
+ .argument("<ref>", "pointer to evidence: file path, URL, log, test run")
596
+ .option("--note <note>", "what this evidence shows")
597
+ .option("--for <target>", "what it supports, e.g. task:auth-mw")
598
+ .option("--project <key>", "scope the evidence to a project")
599
+ .option("--task <key>", "scope the evidence to a task")
600
+ .option("--kind <kind>", "register kind: memory | skill | hook | lesson | playbook")
601
+ .description("attach evidence to the board (local files are content-hashed)")
602
+ .action((ref, opts) => {
603
+ const b = board();
604
+ if (opts.project && !b.projectExists(opts.project)) {
605
+ console.warn(`\u26a0 unknown project "${opts.project}" (not rejected \u2014 declare it via 'project add' to enable stream validation).`);
606
+ }
607
+ let ev;
608
+ try {
609
+ ev = b.evidence(actor(), ref, opts.note ?? null, opts.for ?? null, opts.project ?? null, {
610
+ taskKey: opts.task ?? null,
611
+ kind: opts.kind ?? null,
612
+ });
613
+ }
614
+ catch (e) {
615
+ b.close();
616
+ console.error(`Error: ${e.message}`);
617
+ process.exitCode = 1;
618
+ return;
619
+ }
620
+ b.close();
621
+ if (ev.skipped) {
622
+ console.warn(`\u26a0 not registered: "${ev.skipped}" \u2014 actor is not a member of "${ev.project}" and no --task given.`);
623
+ return;
624
+ }
625
+ console.log(ev.sha256
626
+ ? `Evidence attached (sha256 ${ev.sha256.slice(0, 12)}…).`
627
+ : "Evidence attached.");
628
+ });
629
+ program
630
+ .command("evidence-list")
631
+ .option("--project <key>", "filter by project")
632
+ .option("--task <key>", "filter by task")
633
+ .option("--kind <kind>", "filter by kind")
634
+ .option("--json", "output raw JSON")
635
+ .description("list the sedimentation register (evidence) filtered by project / task / kind")
636
+ .action((opts) => {
637
+ const b = board();
638
+ const rows = b.listEvidence({
639
+ ...(opts.project !== undefined ? { project: opts.project } : {}),
640
+ ...(opts.task !== undefined ? { taskKey: opts.task } : {}),
641
+ ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
642
+ });
643
+ b.close();
644
+ if (opts.json)
645
+ return printJson(rows);
646
+ if (rows.length === 0) {
647
+ console.log("No evidence registered.");
648
+ return;
649
+ }
650
+ console.log("CREATED".padEnd(26) + "KIND".padEnd(10) + "PROJECT".padEnd(22) + "REF");
651
+ for (const r of rows)
652
+ console.log(`${(r.createdAt ?? "").padEnd(26)}${(r.kind ?? "-").padEnd(10)}${(r.project ?? "-").padEnd(22)}${r.ref}`);
653
+ });
654
+ program
655
+ .command("evidence-verify")
656
+ .option("--json", "output raw JSON")
657
+ .description("re-check content-hashed evidence files for tampering")
658
+ .action((opts) => {
659
+ const b = board();
660
+ const checks = b.verifyEvidence();
661
+ b.close();
662
+ if (opts.json) {
663
+ printJson(checks);
664
+ return;
665
+ }
666
+ const bad = checks.filter((c) => c.status === "changed" || c.status === "missing");
667
+ for (const c of checks) {
668
+ console.log(` [${c.status}] ${c.ref}`);
669
+ }
670
+ if (bad.length > 0) {
671
+ console.error(`✗ ${bad.length} evidence file(s) changed or missing.`);
672
+ process.exitCode = 1;
673
+ }
674
+ else {
675
+ console.log("✓ all content-hashed evidence intact.");
676
+ }
677
+ });
678
+ program
679
+ .command("file")
680
+ .argument("<path>", "file path that changed")
681
+ .option("--change <kind>", "added | modified | deleted", "modified")
682
+ .option("--task <key>", "task this change belongs to")
683
+ .option("--project <key>", "project this change belongs to")
684
+ .description("record a file you touched (cooperative conflict awareness)")
685
+ .action((path, opts) => {
686
+ const b = board();
687
+ if (opts.task) {
688
+ const others = b
689
+ .filesForTask(opts.task)
690
+ .filter((f) => f.agentId !== actor());
691
+ if (others.length > 0) {
692
+ console.warn(`⚠ ${others.length} change(s) by other agents already recorded on task "${opts.task}".`);
693
+ }
694
+ }
695
+ // Real-time collision: another live session editing the same file right now.
696
+ const liveEditors = b
697
+ .activeEditorsOfFile(path, b.activeSessionId(), 120_000)
698
+ .filter((e) => e.agent !== actor());
699
+ if (liveEditors.length > 0) {
700
+ console.warn(`⚠ LIVE: ${liveEditors.map((e) => e.agent).join(", ")} also editing ${path} right now.`);
701
+ }
702
+ b.fileChanged(actor(), path, opts.change, opts.task ?? null, opts.project ?? null);
703
+ b.close();
704
+ console.log(`Recorded ${opts.change}: ${path}`);
705
+ });
706
+ program
707
+ .command("risk")
708
+ .argument("<title>", "the risk")
709
+ .option("--severity <level>", "low | medium | high", "medium")
710
+ .option("--task <ref>", "attach the risk to a task (key or #number)")
711
+ .option("--project <key>", "scope the risk to a project")
712
+ .description("flag an open risk (optionally on a task)")
713
+ .action((title, opts) => {
714
+ const b = board();
715
+ const taskKey = opts.task ? (b.resolveTask(opts.task)?.key ?? null) : null;
716
+ if (opts.project && !b.projectExists(opts.project)) {
717
+ console.warn(`\u26a0 unknown project "${opts.project}" (not rejected \u2014 declare it via 'project add' to enable stream validation).`);
718
+ }
719
+ b.risk(actor(), title, opts.severity, taskKey, opts.project ?? null);
720
+ b.close();
721
+ console.log(taskKey ? `Risk flagged on task ${taskKey}.` : "Risk flagged.");
722
+ });
723
+ program
724
+ .command("risks")
725
+ .option("--status <state>", "open | mitigated | closed | all", "open")
726
+ .option("--json", "output raw JSON")
727
+ .description("list risk cards (with their ids) — defaults to open")
728
+ .action((opts) => {
729
+ const b = board();
730
+ const rows = opts.status === "all" ? b.listRisks(null) : b.listRisks(opts.status);
731
+ b.close();
732
+ if (opts.json)
733
+ return printJson(rows);
734
+ if (rows.length === 0) {
735
+ console.log(`No ${opts.status} risks.`);
736
+ return;
737
+ }
738
+ console.log(`\n── Risks (${opts.status}, ${rows.length}) ──`);
739
+ for (const r of rows) {
740
+ const by = r.resolvedBy ? ` → ${r.status} by ${r.resolvedBy} @ ${r.resolvedAt}` : "";
741
+ console.log(` ${r.id.slice(0, 8)} [${r.severity}] ${r.title}${by}`);
742
+ }
743
+ });
744
+ program
745
+ .command("resolve-risk")
746
+ .argument("<ref>", "risk id, unique id prefix, or exact title")
747
+ .option("--status <state>", "closed | mitigated | open (reopen a card)", "closed")
748
+ .option("--note <text>", "how/why it was settled — recorded on the timeline")
749
+ .description("close the loop: settle a risk card instead of leaving it open forever")
750
+ .action((ref, opts) => {
751
+ const b = board();
752
+ const r = b.resolveRisk(actor(), ref, opts.status, opts.note ?? null);
753
+ b.close();
754
+ if (!r) {
755
+ console.error(`No risk matches '${ref}'. Try \`blackboard risks --status all\`.`);
756
+ process.exitCode = 1;
757
+ return;
758
+ }
759
+ console.log(r.resolvedAt
760
+ ? `Risk ${r.id.slice(0, 8)} → ${r.status} (by ${r.resolvedBy} @ ${r.resolvedAt}).`
761
+ : `Risk ${r.id.slice(0, 8)} → ${r.status} (reopened).`);
762
+ });
763
+ program
764
+ .command("handoff")
765
+ .argument("<agent>", "agent to hand off to")
766
+ .argument("<summary>", "state at handoff, e.g. 'tests pass except policy replay'")
767
+ .option("--context <text>", "extra context for the receiving agent")
768
+ .option("--file <path...>", "related file(s)")
769
+ .option("--question <q...>", "open question(s) for the next agent")
770
+ .option("--task <key>", "task being handed off")
771
+ .option("--project <key>", "project being handed off")
772
+ .description("hand off work to another agent")
773
+ .action((agent, summary, opts) => {
774
+ const b = board();
775
+ if (opts.project && !b.projectExists(opts.project)) {
776
+ console.warn(`\u26a0 unknown project "${opts.project}" (not rejected \u2014 declare it via 'project add' to enable stream validation).`);
777
+ }
778
+ b.handoff(actor(), agent, summary, {
779
+ context: opts.context ?? null,
780
+ relatedFiles: opts.file ?? [],
781
+ openQuestions: opts.question ?? [],
782
+ taskKey: opts.task ?? null,
783
+ project: opts.project ?? null,
784
+ });
785
+ b.close();
786
+ console.log(`Handed off to ${agent}.`);
787
+ });
788
+ program
789
+ .command("timeline")
790
+ .option("--limit <n>", "how many entries", (v) => parseInt(v, 10), 30)
791
+ .option("--session <id>", "only events from this session (HH:MM view)")
792
+ .option("--json", "output raw JSON")
793
+ .description("show the append-only, hash-chained history")
794
+ .action((opts) => {
795
+ const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 30;
796
+ const b = board();
797
+ const events = opts.session
798
+ ? b.sessionTimeline(opts.session)
799
+ : b.timeline(limit);
800
+ b.close();
801
+ if (opts.json) {
802
+ printJson(events);
803
+ return;
804
+ }
805
+ if (opts.session) {
806
+ for (const e of events) {
807
+ const t = new Date(e.at).toLocaleTimeString("en-GB", {
808
+ hour: "2-digit",
809
+ minute: "2-digit",
810
+ });
811
+ console.log(`${t} ${e.summary}`);
812
+ }
813
+ return;
814
+ }
815
+ for (const e of events) {
816
+ console.log(`#${String(e.seq).padStart(3, "0")} ${e.at} ${e.actor.padEnd(10)} ${e.summary}`);
817
+ }
818
+ });
819
+ // --- sessions ----------------------------------------------------------------
820
+ const session = program
821
+ .command("session")
822
+ .description("manage execution sessions");
823
+ session
824
+ .command("start")
825
+ .option("--label <label>", "human label for this session")
826
+ .description("start a session and make it current for this agent")
827
+ .action((opts) => {
828
+ const b = board();
829
+ const s = b.startSession(opts.label ?? null);
830
+ b.close();
831
+ console.log(`Session started: ${s.id}`);
832
+ console.log(` agent: ${s.agentName} branch: ${s.gitBranch ?? "-"} machine: ${s.machine ?? "-"}`);
833
+ console.log(` (writes now attribute to this session; run 'octoboard session stop' to end)`);
834
+ });
835
+ session
836
+ .command("stop")
837
+ .argument("[id]", "session to stop (defaults to your active session)")
838
+ .description("stop a session")
839
+ .action((sid) => {
840
+ const b = board();
841
+ const s = b.stopSession(sid);
842
+ b.close();
843
+ console.log(s ? `Session stopped: ${s.id}` : "No active session.");
844
+ });
845
+ session
846
+ .command("heartbeat")
847
+ .description("stamp your active session as alive (for real-time liveness)")
848
+ .action(() => {
849
+ const b = board();
850
+ const s = b.heartbeat();
851
+ b.close();
852
+ console.log(s
853
+ ? `Heartbeat: ${s.id.slice(0, 8)} @ ${s.lastHeartbeat}`
854
+ : "No active session.");
855
+ });
856
+ session
857
+ .command("list")
858
+ .option("--json", "output raw JSON")
859
+ .description("list recent sessions")
860
+ .action((opts) => {
861
+ const b = board();
862
+ const sessions = b.listSessions();
863
+ b.close();
864
+ if (opts.json) {
865
+ printJson(sessions);
866
+ return;
867
+ }
868
+ for (const s of sessions) {
869
+ const state = s.finishedAt ? "closed" : "OPEN";
870
+ console.log(`${s.id.slice(0, 8)} [${state}] ${s.agentName.padEnd(10)} ${s.gitBranch ?? "-"} ${s.startedAt}`);
871
+ }
872
+ });
873
+ session
874
+ .command("show")
875
+ .argument("<id>", "session id")
876
+ .option("--json", "output raw JSON")
877
+ .description("show a session and its timeline")
878
+ .action((sid, opts) => {
879
+ const b = board();
880
+ const s = b.getSession(sid);
881
+ const events = s ? b.sessionTimeline(sid) : [];
882
+ b.close();
883
+ if (!s) {
884
+ console.log("No such session.");
885
+ return;
886
+ }
887
+ if (opts.json) {
888
+ printJson({ session: s, timeline: events });
889
+ return;
890
+ }
891
+ console.log(`Session ${s.id}`);
892
+ console.log(` agent ${s.agentName} branch ${s.gitBranch ?? "-"} ${s.workingDirectory ?? ""}`);
893
+ console.log(` started ${s.startedAt} ${s.finishedAt ? `finished ${s.finishedAt}` : "OPEN"}`);
894
+ console.log(" timeline:");
895
+ for (const e of events) {
896
+ const t = new Date(e.at).toLocaleTimeString("en-GB", {
897
+ hour: "2-digit",
898
+ minute: "2-digit",
899
+ });
900
+ console.log(` ${t} ${e.summary}`);
901
+ }
902
+ });
903
+ // --- attribution & git --------------------------------------------------------
904
+ program
905
+ .command("link")
906
+ .argument("[rev]", "commit to link (defaults to HEAD)", "HEAD")
907
+ .option("--actor <type>", "human | ai", "ai")
908
+ .option("--name <name>", "explicit actor name")
909
+ .option("--note", "also write an additive git note (refs/notes/blackboard)")
910
+ .description("attribute a commit's files to the current session")
911
+ .action((rev, opts) => {
912
+ const b = board();
913
+ const result = b.link(rev, {
914
+ actorType: opts.actor,
915
+ actor: opts.name,
916
+ writeNote: Boolean(opts.note),
917
+ });
918
+ b.close();
919
+ if (!result) {
920
+ console.error(`Could not resolve '${rev}' (not a git repo, or unknown revision).`);
921
+ process.exitCode = 1;
922
+ return;
923
+ }
924
+ console.log(`Linked ${result.sha.slice(0, 12)} → ${opts.name ?? actor()} (${result.count} file(s)).`);
925
+ });
926
+ program
927
+ .command("attribute")
928
+ .argument("<rev>", "commit sha or revision")
929
+ .option("--file <path>", "specific file")
930
+ .option("--actor <type>", "human | ai", "ai")
931
+ .option("--name <name>", "explicit actor name")
932
+ .description("record a single attribution for a commit")
933
+ .action((rev, opts) => {
934
+ const b = board();
935
+ const a = b.attribute(rev, {
936
+ file: opts.file ?? null,
937
+ actorType: opts.actor,
938
+ actor: opts.name,
939
+ });
940
+ b.close();
941
+ console.log(`Attributed ${a.commit.slice(0, 12)}${a.file ? ` (${a.file})` : ""} to ${a.actorType} ${a.actor}.`);
942
+ });
943
+ program
944
+ .command("review")
945
+ .argument("<rev>", "commit sha or revision")
946
+ .option("--by <type>", "human | ai", "human")
947
+ .option("--name <name>", "reviewer name")
948
+ .option("--outcome <outcome>", "approved | changes-requested | rejected | commented", "approved")
949
+ .option("--note <note>", "review note")
950
+ .description("record who reviewed a commit and the outcome")
951
+ .action((rev, opts) => {
952
+ const b = board();
953
+ const r = b.review(rev, {
954
+ reviewerType: opts.by,
955
+ reviewer: opts.name,
956
+ outcome: opts.outcome,
957
+ note: opts.note ?? null,
958
+ });
959
+ b.close();
960
+ console.log(`Recorded ${r.reviewerType} review of ${r.commit.slice(0, 12)}: ${r.outcome}.`);
961
+ });
962
+ program
963
+ .command("who")
964
+ .argument("<file>", "file to explain")
965
+ .option("--line <n>", "which session introduced this line", (v) => parseInt(v, 10))
966
+ .option("--json", "output raw JSON")
967
+ .description("who changed this file (git authors + AI sessions)")
968
+ .action((file, opts) => {
969
+ const b = board();
970
+ if (opts.line !== undefined) {
971
+ if (!Number.isInteger(opts.line) || opts.line < 1) {
972
+ b.close();
973
+ console.error("--line must be a positive integer.");
974
+ process.exitCode = 1;
975
+ return;
976
+ }
977
+ const bl = b.blame(file, opts.line);
978
+ b.close();
979
+ if (!bl) {
980
+ console.log("No blame available (not a git repo, or file/line unknown).");
981
+ return;
982
+ }
983
+ if (opts.json)
984
+ return printJson(bl);
985
+ console.log(`${file}:${opts.line} last changed in ${bl.sha.slice(0, 12)} (git author ${bl.gitAuthor})`);
986
+ for (const a of bl.attributions) {
987
+ console.log(` ↳ ${a.actorType} ${a.actor}${a.model ? ` [${a.model}]` : ""} session ${a.sessionId?.slice(0, 8) ?? "-"}`);
988
+ }
989
+ return;
990
+ }
991
+ const result = b.whoTouched(file);
992
+ b.close();
993
+ if (opts.json)
994
+ return printJson(result);
995
+ console.log(`Git authors: ${result.gitAuthors.join(", ") || "(none / not a repo)"}`);
996
+ console.log("AI sessions touching this file:");
997
+ if (result.sessions.length === 0)
998
+ console.log(" (none recorded)");
999
+ for (const s of result.sessions) {
1000
+ console.log(` ${s.agent.padEnd(10)} session ${s.sessionId?.slice(0, 8) ?? "-"} ${s.at}`);
1001
+ }
1002
+ if (result.attributions.length > 0) {
1003
+ console.log("Commit attributions:");
1004
+ for (const a of result.attributions) {
1005
+ console.log(` ${a.commit.slice(0, 12)} ${a.actorType} ${a.actor}${a.model ? ` [${a.model}]` : ""}`);
1006
+ }
1007
+ }
1008
+ });
1009
+ program
1010
+ .command("explain")
1011
+ .argument("[rev]", "commit to explain (defaults to HEAD)", "HEAD")
1012
+ .option("--json", "output raw JSON")
1013
+ .description("explain a commit: attribution, reviews, related decisions")
1014
+ .action((rev, opts) => {
1015
+ const b = board();
1016
+ const info = b.explain(rev);
1017
+ b.close();
1018
+ if (!info) {
1019
+ console.log(`Nothing known about '${rev}'.`);
1020
+ return;
1021
+ }
1022
+ if (opts.json)
1023
+ return printJson(info);
1024
+ const c = info.commit;
1025
+ console.log(`commit ${c.sha}`);
1026
+ if (c.author)
1027
+ console.log(` ${c.author} <${c.authorEmail}> ${c.date}`);
1028
+ if (c.subject)
1029
+ console.log(` ${c.subject}`);
1030
+ console.log(" produced by:");
1031
+ if (info.attributions.length === 0)
1032
+ console.log(" (no AI attribution recorded)");
1033
+ for (const a of info.attributions) {
1034
+ console.log(` ${a.actorType} ${a.actor}${a.model ? ` [${a.model}]` : ""}${a.file ? ` — ${a.file}` : ""}`);
1035
+ }
1036
+ console.log(" reviews:");
1037
+ if (info.reviews.length === 0)
1038
+ console.log(" (unreviewed)");
1039
+ for (const r of info.reviews) {
1040
+ console.log(` ${r.reviewerType} ${r.reviewer}: ${r.outcome}`);
1041
+ }
1042
+ if (info.decisions.length > 0) {
1043
+ console.log(" decisions:");
1044
+ for (const d of info.decisions)
1045
+ console.log(` ${d.title}`);
1046
+ }
1047
+ if (info.note)
1048
+ console.log(` git note: ${info.note}`);
1049
+ });
1050
+ program
1051
+ .command("commits")
1052
+ .argument("<actor>", "actor, cli, provider, or model, e.g. claude-code")
1053
+ .option("--json", "output raw JSON")
1054
+ .description("which commits came from an AI / CLI")
1055
+ .action((query, opts) => {
1056
+ const b = board();
1057
+ const rows = b.commitsByActor(query);
1058
+ b.close();
1059
+ if (opts.json)
1060
+ return printJson(rows);
1061
+ if (rows.length === 0)
1062
+ console.log(`No commits attributed to '${query}'.`);
1063
+ for (const r of rows) {
1064
+ console.log(`${r.commit.slice(0, 12)} ${r.actor}${r.cli ? ` (${r.cli})` : ""} ${r.at}`);
1065
+ }
1066
+ });
1067
+ program
1068
+ .command("unreviewed")
1069
+ .option("--json", "output raw JSON")
1070
+ .description("AI-produced commits with no human review")
1071
+ .action((opts) => {
1072
+ const b = board();
1073
+ const rows = b.unreviewedCommits();
1074
+ b.close();
1075
+ if (opts.json)
1076
+ return printJson(rows);
1077
+ if (rows.length === 0) {
1078
+ console.log("✓ every AI-attributed commit has a human review.");
1079
+ return;
1080
+ }
1081
+ console.log("Commits never human-reviewed:");
1082
+ for (const r of rows)
1083
+ console.log(` ${r.commit.slice(0, 12)} ${r.actor} ${r.at}`);
1084
+ });
1085
+ program
1086
+ .command("joint")
1087
+ .argument("<agentA>")
1088
+ .argument("<agentB>")
1089
+ .description("files modified by BOTH agents (collision surface)")
1090
+ .action((a, bName) => {
1091
+ const b = board();
1092
+ const files = b.jointFiles(a, bName);
1093
+ b.close();
1094
+ if (files.length === 0) {
1095
+ console.log(`No files jointly modified by ${a} and ${bName}.`);
1096
+ return;
1097
+ }
1098
+ console.log(`Files touched by both ${a} and ${bName}:`);
1099
+ for (const f of files)
1100
+ console.log(` ${f}`);
1101
+ });
1102
+ program
1103
+ .command("mcp-config")
1104
+ .argument("[client]", `client: ${MCP_CLIENTS.join(" | ")}`, "json")
1105
+ .option("--agent <name>", "identity to write as (defaults to the client name)")
1106
+ .option("--dir <path>", "explicit board directory (default: discover .octoboard/)")
1107
+ .option("--local <entry>", "use a local build path instead of the npx bin (dev)")
1108
+ .description("print MCP client config to connect a CLI to this blackboard")
1109
+ .action((client, opts) => {
1110
+ if (!MCP_CLIENTS.includes(client)) {
1111
+ console.error(`Unknown client '${client}'. Available: ${MCP_CLIENTS.join(", ")}`);
1112
+ process.exitCode = 1;
1113
+ return;
1114
+ }
1115
+ const result = mcpConfig(client, {
1116
+ agent: opts.agent,
1117
+ boardDir: opts.dir,
1118
+ localEntry: opts.local,
1119
+ });
1120
+ console.log(`# Add to: ${result.path}`);
1121
+ if (result.note)
1122
+ console.log(`# ${result.note}`);
1123
+ console.log(result.content);
1124
+ });
1125
+ program
1126
+ .command("serve")
1127
+ .option("--port <n>", "port to listen on", (v) => parseInt(v, 10), 4319)
1128
+ .option("--host <host>", "bind address (default 127.0.0.1; use 0.0.0.0 to expose on the LAN)", "127.0.0.1")
1129
+ .description("start a read-only local web dashboard (loopback-only by default)")
1130
+ .action((opts) => {
1131
+ if (!Number.isInteger(opts.port) || opts.port <= 0 || opts.port > 65535) {
1132
+ console.error("--port must be an integer between 1 and 65535.");
1133
+ process.exitCode = 1;
1134
+ return;
1135
+ }
1136
+ const b = board();
1137
+ const server = serve(b, opts.port, opts.host);
1138
+ const where = opts.host === "0.0.0.0"
1139
+ ? `all interfaces :${opts.port} (LAN-exposed!)`
1140
+ : `http://localhost:${opts.port}`;
1141
+ console.error(`Dashboard on ${where} (read-only) — Ctrl-C to stop`);
1142
+ process.on("SIGINT", () => {
1143
+ server.close();
1144
+ b.close();
1145
+ process.exit(0);
1146
+ });
1147
+ });
1148
+ program
1149
+ .command("report")
1150
+ .option("--json", "output raw JSON")
1151
+ .option("--project <key>", "three-level aggregation for one project instead of the scorecard")
1152
+ .description("scorecard: review coverage, AI/human ratio, per-agent breakdown")
1153
+ .action((opts) => {
1154
+ const b = board();
1155
+ const r = b.report(opts.project ?? null);
1156
+ b.close();
1157
+ if (opts.project) {
1158
+ if (!r) {
1159
+ console.log(`No project '${opts.project}'.`);
1160
+ return;
1161
+ }
1162
+ if (opts.json)
1163
+ return printJson(r);
1164
+ renderProjectReport(r);
1165
+ return;
1166
+ }
1167
+ if (opts.json) {
1168
+ printJson(r);
1169
+ return;
1170
+ }
1171
+ // Only show 100% when coverage is exactly complete; otherwise floor so a
1172
+ // 99.5% never rounds up to a reassuring "100%".
1173
+ const pct = (n) => n === null ? "n/a" : n === 1 ? "100%" : `${Math.floor(n * 100)}%`;
1174
+ console.log("── Accountability scorecard ───────────");
1175
+ console.log(` review coverage: ${pct(r.reviewCoverage)} (${r.commits.humanReviewed}/${r.commits.aiProduced} AI commits approved)`);
1176
+ console.log(` unreviewed AI: ${r.commits.unreviewed} commit(s)`);
1177
+ console.log(` attributions: ${r.attributions.total} (ai ${r.attributions.ai} / human ${r.attributions.human})`);
1178
+ console.log(` sessions: ${r.sessions.total} (${r.sessions.open} open)`);
1179
+ console.log(` open risks: ${r.risks.open} (mitigated ${r.risks.mitigated} / closed ${r.risks.closed})`);
1180
+ console.log(" per agent:");
1181
+ if (r.perAgent.length === 0)
1182
+ console.log(" (none)");
1183
+ for (const a of r.perAgent) {
1184
+ console.log(` ${a.agent.padEnd(12)} [${a.actorType}] ${a.commits} commit(s), ${a.files} file(s), ${a.attributions} attribution(s)`);
1185
+ }
1186
+ });
1187
+ program
1188
+ .command("blame")
1189
+ .argument("<file>", "file to trace")
1190
+ .argument("<line>", "line number")
1191
+ .option("--json", "output raw JSON")
1192
+ .description("trace a line back to the session that introduced it (narrative)")
1193
+ .action((file, lineArg, opts) => {
1194
+ const line = parseInt(lineArg, 10);
1195
+ const b = board();
1196
+ if (!Number.isInteger(line) || line < 1) {
1197
+ b.close();
1198
+ console.error("line must be a positive integer.");
1199
+ process.exitCode = 1;
1200
+ return;
1201
+ }
1202
+ const n = b.blameNarrative(file, line);
1203
+ b.close();
1204
+ if (!n) {
1205
+ console.log("No blame available (not a git repo, or file/line unknown).");
1206
+ return;
1207
+ }
1208
+ if (opts.json) {
1209
+ printJson(n);
1210
+ return;
1211
+ }
1212
+ console.log(`${file}:${line} last changed in ${n.sha.slice(0, 12)} (git author ${n.gitAuthor})`);
1213
+ for (const a of n.attributions) {
1214
+ console.log(` produced by ${a.actorType} ${a.actor}${a.model ? ` [${a.model}]` : ""}`);
1215
+ }
1216
+ if (n.session) {
1217
+ console.log(` in session ${n.session.id.slice(0, 8)} (${n.session.agentName}, branch ${n.session.gitBranch ?? "-"})`);
1218
+ // Show the session's other activity, minus the kinds surfaced separately
1219
+ // (decisions/handoffs below) and the link/attribution for this very line.
1220
+ const shownSeparately = new Set([
1221
+ "decision",
1222
+ "handoff",
1223
+ "link",
1224
+ "attribution",
1225
+ ]);
1226
+ const also = n.sessionTimeline.filter((e) => !shownSeparately.has(e.kind));
1227
+ if (also.length > 0) {
1228
+ console.log(" that session also:");
1229
+ for (const e of also)
1230
+ console.log(` · ${e.summary}`);
1231
+ }
1232
+ for (const d of n.decisions)
1233
+ console.log(` ⟐ decided: ${d.title}`);
1234
+ for (const h of n.handoffs)
1235
+ console.log(` → handoff to ${h.toAgent}: ${h.summary}`);
1236
+ }
1237
+ else {
1238
+ console.log(" (no session context recorded for this commit)");
1239
+ }
1240
+ });
1241
+ program
1242
+ .command("export")
1243
+ .option("--range <range>", "commit range to export, e.g. main..HEAD (default: all attributed)")
1244
+ .option("--out <file>", "write the bundle to a file (default: stdout)")
1245
+ .description("export a portable attribution bundle (survives push/PR)")
1246
+ .action((opts) => {
1247
+ const b = board();
1248
+ const commits = opts.range ? git.revList(opts.range) : undefined;
1249
+ const bundle = b.exportBundle(commits);
1250
+ b.close();
1251
+ const json = JSON.stringify(bundle, null, 2);
1252
+ if (opts.out) {
1253
+ writeFileSync(opts.out, json, "utf8");
1254
+ console.log(`Wrote ${bundle.attributions.length} attribution(s), ${bundle.reviews.length} review(s) to ${opts.out}.`);
1255
+ }
1256
+ else {
1257
+ console.log(json);
1258
+ }
1259
+ });
1260
+ program
1261
+ .command("import")
1262
+ .argument("<file>", "bundle file to import")
1263
+ .option("--require-signed", "refuse a bundle that is unsigned or has a bad signature")
1264
+ .description("import an attribution bundle into this board (idempotent)")
1265
+ .action((file, opts) => {
1266
+ const b = board();
1267
+ try {
1268
+ const bundle = JSON.parse(readFileSync(file, "utf8"));
1269
+ const c = b.importBundle(bundle, {
1270
+ requireSigned: Boolean(opts.requireSigned),
1271
+ });
1272
+ const trust = c.verified === true
1273
+ ? " (signature ✓)"
1274
+ : c.verified === false
1275
+ ? " (signature INVALID)"
1276
+ : " (unsigned)";
1277
+ console.log(`Imported ${c.attributions} attribution(s), ${c.reviews} review(s), ${c.sessions} session(s), ${c.decisions} decision(s)${trust}.`);
1278
+ if (c.verified === false)
1279
+ process.exitCode = 1;
1280
+ }
1281
+ catch (err) {
1282
+ console.error(err instanceof Error ? err.message : String(err));
1283
+ process.exitCode = 1;
1284
+ }
1285
+ finally {
1286
+ b.close();
1287
+ }
1288
+ });
1289
+ program
1290
+ .command("ingest")
1291
+ .argument("<file>", "transcript file to ingest")
1292
+ .option("--format <format>", `adapter: ${ADAPTERS.join(" | ")}`, "generic")
1293
+ .option("--dry-run", "parse and print events without recording them")
1294
+ .description("ingest a CLI transcript into the active session (file edits, decisions, notes)")
1295
+ .action((file, opts) => {
1296
+ const adapter = getAdapter(opts.format);
1297
+ if (!adapter) {
1298
+ console.error(`Unknown format '${opts.format}'. Available: ${ADAPTERS.join(", ")}`);
1299
+ process.exitCode = 1;
1300
+ return;
1301
+ }
1302
+ let events;
1303
+ try {
1304
+ events = adapter.parse(readFileSync(file, "utf8"));
1305
+ }
1306
+ catch (err) {
1307
+ console.error(err instanceof Error ? err.message : String(err));
1308
+ process.exitCode = 1;
1309
+ return;
1310
+ }
1311
+ if (opts.dryRun) {
1312
+ printJson(events);
1313
+ return;
1314
+ }
1315
+ const b = board();
1316
+ const counts = b.ingest(events);
1317
+ b.close();
1318
+ console.log(`Ingested ${counts.files} file(s), ${counts.decisions} decision(s), ${counts.notes} note(s) via ${adapter.name}.`);
1319
+ });
1320
+ program
1321
+ .command("prune")
1322
+ .requiredOption("--before <iso>", "delete messages/evidence/file-changes created before this ISO time")
1323
+ .description("retention: delete old sensitive rows (the audit timeline is never pruned)")
1324
+ .action((opts) => {
1325
+ const when = new Date(opts.before);
1326
+ if (isNaN(when.getTime())) {
1327
+ console.error("--before must be a valid ISO timestamp, e.g. 2026-01-01T00:00:00Z");
1328
+ process.exitCode = 1;
1329
+ return;
1330
+ }
1331
+ const b = board();
1332
+ const c = b.prune(when.toISOString());
1333
+ b.close();
1334
+ console.log(`Pruned ${c.messages} message(s), ${c.evidence} evidence, ${c.filesChanged} file-change(s). Timeline preserved.`);
1335
+ });
1336
+ program
1337
+ .command("redact")
1338
+ .argument("<seq>", "timeline sequence number to redact")
1339
+ .option("--reason <reason>", "why (shown in the tombstone)")
1340
+ .description("hide a timeline entry's content at the read layer (chain stays valid)")
1341
+ .action((seqArg, opts) => {
1342
+ const seq = parseInt(seqArg, 10);
1343
+ const b = board();
1344
+ if (!Number.isInteger(seq) || seq < 1) {
1345
+ b.close();
1346
+ console.error("seq must be a positive integer.");
1347
+ process.exitCode = 1;
1348
+ return;
1349
+ }
1350
+ const ok = b.redact(seq, opts.reason ?? null);
1351
+ b.close();
1352
+ console.log(ok ? `Redacted #${seq}.` : `No timeline entry #${seq}.`);
1353
+ });
1354
+ program
1355
+ .command("sync")
1356
+ .argument("<direction>", "push | pull")
1357
+ .option("--target <spec>", "file path or postgres:// URL (or OCTOBOARD_SYNC_TARGET)")
1358
+ .option("--range <range>", "commit range for push (default: all attributed)")
1359
+ .description("sync attribution to/from a team board (file or Postgres)")
1360
+ .action(async (direction, opts) => {
1361
+ const spec = opts.target ?? process.env.OCTOBOARD_SYNC_TARGET;
1362
+ if (!spec) {
1363
+ console.error("No sync target (use --target or set OCTOBOARD_SYNC_TARGET).");
1364
+ process.exitCode = 1;
1365
+ return;
1366
+ }
1367
+ const b = board();
1368
+ const target = createSyncTarget(spec);
1369
+ try {
1370
+ if (direction === "push") {
1371
+ const commits = opts.range ? git.revList(opts.range) : undefined;
1372
+ const res = await target.push(b.exportBundle(commits));
1373
+ console.log(`Pushed: ${res.attributions} attribution(s), ${res.reviews} review(s), ${res.sessions} session(s), ${res.decisions} decision(s).`);
1374
+ }
1375
+ else if (direction === "pull") {
1376
+ const counts = b.importBundle(await target.pull());
1377
+ console.log(`Pulled: ${counts.attributions} attribution(s), ${counts.reviews} review(s), ${counts.sessions} session(s), ${counts.decisions} decision(s).`);
1378
+ }
1379
+ else {
1380
+ console.error("direction must be 'push' or 'pull'.");
1381
+ process.exitCode = 1;
1382
+ }
1383
+ }
1384
+ catch (err) {
1385
+ console.error(err instanceof Error ? err.message : String(err));
1386
+ process.exitCode = 1;
1387
+ }
1388
+ finally {
1389
+ await target.close();
1390
+ b.close();
1391
+ }
1392
+ });
1393
+ program
1394
+ .command("trailers")
1395
+ .argument("[rev]", "commit to describe", "HEAD")
1396
+ .description("print git trailer lines encoding a commit's attribution")
1397
+ .action((rev) => {
1398
+ const b = board();
1399
+ const lines = b.trailersFor(rev);
1400
+ b.close();
1401
+ if (lines.length === 0) {
1402
+ console.error("No attribution recorded for this commit.");
1403
+ process.exitCode = 1;
1404
+ return;
1405
+ }
1406
+ for (const l of lines) {
1407
+ console.log(l);
1408
+ }
1409
+ });
1410
+ program
1411
+ .command("check")
1412
+ .option("--range <range>", "commit range to check, e.g. main..HEAD (default: all attributed commits)")
1413
+ .option("--require-human-review", "fail if any AI-produced commit lacks a human review")
1414
+ .option("--require-attribution", "fail if a scoped commit has no attribution at all")
1415
+ .option("--verify-chain", "fail if the timeline hash chain is broken")
1416
+ .option("--json", "output raw JSON")
1417
+ .description("governance gate: assert policy over commits, exit 1 on violation")
1418
+ .action((opts) => {
1419
+ const b = board();
1420
+ let commits;
1421
+ if (opts.range) {
1422
+ commits = git.revList(opts.range);
1423
+ }
1424
+ // With no explicit policy flags, apply a sensible default gate.
1425
+ const anyPolicy = opts.requireHumanReview || opts.requireAttribution || opts.verifyChain;
1426
+ const result = b.check({
1427
+ commits,
1428
+ requireHumanReview: anyPolicy ? Boolean(opts.requireHumanReview) : true,
1429
+ requireAttribution: Boolean(opts.requireAttribution),
1430
+ verifyChain: anyPolicy ? Boolean(opts.verifyChain) : true,
1431
+ });
1432
+ b.close();
1433
+ if (opts.json) {
1434
+ printJson(result);
1435
+ }
1436
+ else if (result.ok) {
1437
+ console.log(`✓ policy passed (${result.checked} commit(s) checked).`);
1438
+ }
1439
+ else {
1440
+ console.error(`✗ policy FAILED — ${result.violations.length} violation(s):`);
1441
+ for (const v of result.violations) {
1442
+ const where = v.commit ? `${v.commit.slice(0, 12)} ` : "";
1443
+ console.error(` [${v.kind}] ${where}${v.detail}`);
1444
+ }
1445
+ }
1446
+ if (!result.ok) {
1447
+ process.exitCode = 1;
1448
+ }
1449
+ });
1450
+ program
1451
+ .command("watch")
1452
+ .option("--for <agent>", "only notify about events relevant to this agent")
1453
+ .option("--interval <ms>", "poll interval in milliseconds", (v) => parseInt(v, 10), 1000)
1454
+ .option("--once", "print events since the current head and exit (no loop)")
1455
+ .description("subscribe to board changes (poll the timeline for new events)")
1456
+ .action((opts) => {
1457
+ const b = board();
1458
+ const forAgent = opts.for;
1459
+ let last = b.headSeq();
1460
+ const drain = () => {
1461
+ const fresh = b.since(last);
1462
+ if (fresh.length > 0) {
1463
+ last = fresh[fresh.length - 1].seq;
1464
+ }
1465
+ const show = forAgent ? b.notable(fresh, forAgent) : fresh;
1466
+ for (const e of show) {
1467
+ const t = new Date(e.at).toLocaleTimeString("en-GB", {
1468
+ hour: "2-digit",
1469
+ minute: "2-digit",
1470
+ second: "2-digit",
1471
+ });
1472
+ console.log(`${t} #${e.seq} ${e.actor.padEnd(10)} ${e.summary}`);
1473
+ }
1474
+ };
1475
+ if (opts.once) {
1476
+ // `--once` reports from 0 so a one-shot poll is useful in scripts.
1477
+ last = 0;
1478
+ drain();
1479
+ b.close();
1480
+ return;
1481
+ }
1482
+ const interval = Number.isInteger(opts.interval) && opts.interval > 0
1483
+ ? opts.interval
1484
+ : 1000;
1485
+ console.error(`watching board from seq ${last}${forAgent ? ` for ${forAgent}` : ""} — Ctrl-C to stop`);
1486
+ const timer = setInterval(drain, interval);
1487
+ process.on("SIGINT", () => {
1488
+ clearInterval(timer);
1489
+ b.close();
1490
+ process.exit(0);
1491
+ });
1492
+ });
1493
+ program
1494
+ .command("sign")
1495
+ .description("sign the current timeline head with your active session key")
1496
+ .action(() => {
1497
+ const b = board();
1498
+ const signed = b.signHead();
1499
+ b.close();
1500
+ if (!signed) {
1501
+ console.error("Nothing to sign (no active session, missing key, or empty board).");
1502
+ process.exitCode = 1;
1503
+ return;
1504
+ }
1505
+ console.log(`Signed head at seq ${signed.headSeq}.`);
1506
+ });
1507
+ program
1508
+ .command("anchor")
1509
+ .option("--out <file>", "write the anchor to a JSON file")
1510
+ .option("--git-note", "write the anchor as a git note on HEAD (refs/notes/blackboard)")
1511
+ .description("record the current timeline head as an external anchor (proves against truncation)")
1512
+ .action((opts) => {
1513
+ const b = board();
1514
+ const h = b.head();
1515
+ b.close();
1516
+ const line = `${h.seq}:${h.hash}`;
1517
+ if (opts.out) {
1518
+ writeFileSync(opts.out, JSON.stringify({ seq: h.seq, hash: h.hash }, null, 2), "utf8");
1519
+ console.log(`Anchor written to ${opts.out} (${line})`);
1520
+ }
1521
+ else if (opts.gitNote) {
1522
+ const ok = git.writeNote("HEAD", `blackboard-anchor ${line}`);
1523
+ console.log(ok
1524
+ ? `Anchor written to git note on HEAD (${line})`
1525
+ : "Failed — not a git repo?");
1526
+ if (!ok)
1527
+ process.exitCode = 1;
1528
+ }
1529
+ else {
1530
+ console.log(line);
1531
+ }
1532
+ });
1533
+ program
1534
+ .command("verify")
1535
+ .option("--against <spec>", "check an external anchor: 'seq:hash', a JSON file, or 'git-note'")
1536
+ .description("verify the timeline hash chain and show signature trust")
1537
+ .action((opts) => {
1538
+ const b = board();
1539
+ const result = b.verifyChain();
1540
+ const sigs = b.verifySignatures(result); // reuse the one verification
1541
+ const signedThrough = b.signedThrough(result);
1542
+ // Resolve + check an external anchor, if requested, before closing.
1543
+ let anchorMsg = null;
1544
+ if (opts.against) {
1545
+ const parsed = resolveAnchor(opts.against);
1546
+ if (!parsed) {
1547
+ anchorMsg = `⚠ could not read anchor '${opts.against}'`;
1548
+ }
1549
+ else {
1550
+ const a = b.verifyAnchor(parsed.seq, parsed.hash);
1551
+ if (a.status === "ok") {
1552
+ anchorMsg = `✓ external anchor holds — history through seq ${parsed.seq} is intact`;
1553
+ }
1554
+ else {
1555
+ anchorMsg =
1556
+ a.status === "truncated"
1557
+ ? `✗ TRUNCATED — anchored seq ${parsed.seq} is gone (head is at ${a.headSeq})`
1558
+ : `✗ ALTERED — history at/below seq ${parsed.seq} was changed`;
1559
+ process.exitCode = 1;
1560
+ }
1561
+ }
1562
+ }
1563
+ b.close();
1564
+ if (result.ok && (result.anchored || result.length === 0)) {
1565
+ console.log(`✓ chain intact — ${result.length} entr(ies) verified`);
1566
+ }
1567
+ else if (result.ok) {
1568
+ // Links verify, but with no head anchor a tail truncation is undetectable.
1569
+ console.warn(`⚠ links intact but UNANCHORED — tail truncation undetectable (${result.length} entries). Anchor externally to be sure.`);
1570
+ }
1571
+ else {
1572
+ console.error(`✗ chain BROKEN at seq ${result.brokenAtSeq} (of ${result.length})`);
1573
+ process.exitCode = 1;
1574
+ }
1575
+ if (sigs.length === 0) {
1576
+ console.log("trust: (no signatures yet — run 'octoboard sign' or stop a session)");
1577
+ }
1578
+ else {
1579
+ console.log(`trust: signed through seq ${signedThrough}`);
1580
+ for (const s of sigs) {
1581
+ const mark = s.valid && s.current
1582
+ ? "✓ trusted"
1583
+ : s.valid
1584
+ ? "⚠ stale (history changed)"
1585
+ : "✗ invalid";
1586
+ console.log(` seq ${String(s.headSeq).padStart(3)} ${s.agent ?? "?"} (${s.sessionId.slice(0, 8)}) ${mark}`);
1587
+ }
1588
+ }
1589
+ if (anchorMsg)
1590
+ console.log(anchorMsg);
1591
+ });
1592
+ /** Resolve an external anchor spec: `seq:hash`, a JSON file, or `git-note`. */
1593
+ function resolveAnchor(spec) {
1594
+ const parseLine = (s) => {
1595
+ const m = /(\d+):([0-9a-f]{64})/.exec(s);
1596
+ return m ? { seq: Number(m[1]), hash: m[2] } : null;
1597
+ };
1598
+ if (spec === "git-note") {
1599
+ const note = git.readNote("HEAD");
1600
+ return note ? parseLine(note) : null;
1601
+ }
1602
+ if (existsSync(spec)) {
1603
+ try {
1604
+ const j = JSON.parse(readFileSync(spec, "utf8"));
1605
+ if (typeof j.seq === "number" && typeof j.hash === "string") {
1606
+ return { seq: j.seq, hash: j.hash };
1607
+ }
1608
+ }
1609
+ catch {
1610
+ /* fall through */
1611
+ }
1612
+ return null;
1613
+ }
1614
+ return parseLine(spec);
1615
+ }
1616
+ function renderStatus(status, chain) {
1617
+ const seen = (iso) => {
1618
+ const ms = Date.now() - new Date(iso).getTime();
1619
+ const min = Math.floor(ms / 60000);
1620
+ if (min < 1)
1621
+ return "just now";
1622
+ if (min < 60)
1623
+ return `${min}m ago`;
1624
+ return `${Math.floor(min / 60)}h ago`;
1625
+ };
1626
+ console.log("── Agents ─────────────────────────────");
1627
+ if (status.agents.length === 0)
1628
+ console.log(" (none yet)");
1629
+ for (const a of status.agents) {
1630
+ console.log(` ${a.name.padEnd(12)} ${a.kind ?? ""} last seen ${seen(a.lastSeen)}`);
1631
+ }
1632
+ console.log("\n── Open work ──────────────────────────");
1633
+ if (status.openTasks.length === 0)
1634
+ console.log(" (nothing claimed)");
1635
+ for (const t of status.openTasks) {
1636
+ const holder = t.claimedBy ? `← ${t.claimedBy}` : "(unclaimed)";
1637
+ console.log(` [${t.status}] ${t.key.padEnd(28)} ${holder}`);
1638
+ }
1639
+ console.log("\n── Unread messages ────────────────────");
1640
+ if (status.unreadMessages.length === 0)
1641
+ console.log(" (none)");
1642
+ for (const m of status.unreadMessages) {
1643
+ const dest = m.toAgent ? `→ ${m.toAgent}` : "→ all";
1644
+ console.log(` ${m.fromAgent} ${dest}: ${m.body}`);
1645
+ }
1646
+ console.log("\n── Open risks ─────────────────────────");
1647
+ if (status.openRisks.length === 0)
1648
+ console.log(" (none)");
1649
+ for (const r of status.openRisks) {
1650
+ console.log(` ${r.id.slice(0, 8)} [${r.severity}] ${r.title}`);
1651
+ }
1652
+ console.log("\n── Recent ─────────────────────────────");
1653
+ for (const e of status.recentTimeline) {
1654
+ console.log(` #${e.seq} ${e.actor}: ${e.summary}`);
1655
+ }
1656
+ const mark = chain.ok ? "✓" : "✗";
1657
+ console.log(`\naudit: ${mark} ${chain.length} entries${chain.ok ? "" : ` — BROKEN at ${chain.brokenAtSeq}`}`);
1658
+ }
1659
+ program.parseAsync(process.argv).catch((err) => {
1660
+ console.error(err instanceof Error ? err.message : String(err));
1661
+ process.exitCode = 1;
1662
+ });
1663
+ //# sourceMappingURL=cli.js.map