@jjanczur/tyran 0.1.32 → 0.1.34

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.
package/scripts/board.mjs CHANGED
@@ -21,8 +21,13 @@
21
21
  *
22
22
  * CLI:
23
23
  * node board.mjs [--dir <.tyran>] [--check]
24
- * [--serve [--port <n>] [--write] [--open] [--transcripts <dir>]...]
25
- * Exit: 0 ok · 1 drift (--check) · 2 usage/IO
24
+ * [--serve|--detach [--port <n>] [--write] [--open] [--transcripts <dir>]...]
25
+ * [--status] [--stop]
26
+ * Exit: 0 ok · 1 drift (--check), or no server (--status/--stop) · 2 usage/IO
27
+ *
28
+ * `--serve` holds the terminal; `--detach` starts the same server, waits only
29
+ * until it answers, and returns. Anything that is not a human with a spare
30
+ * terminal wants the second one — see board-daemon.mjs.
26
31
  */
27
32
  import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
28
33
  import { createServer } from 'node:http';
@@ -50,9 +55,22 @@ import { SettingsError, applyPolicyClass, applySetting, readSettings } from './s
50
55
  import { checkStopAt } from './stop-check.mjs';
51
56
  import { runState } from './overnight.mjs';
52
57
  import { answerOne, answerProblem, classify, openAsks, partitionAsks, reRender, sortAsks } from './answer.mjs';
58
+ import {
59
+ HEALTH_ROUTE,
60
+ PORT_SEARCH_SPAN,
61
+ findLiveServer,
62
+ removeServerRecord,
63
+ startDetached,
64
+ stopServer,
65
+ urlFor,
66
+ writeServerRecord,
67
+ } from './board-daemon.mjs';
53
68
 
54
69
  export const BOARD_HTML_FILE = 'board.html';
55
70
 
71
+ /** How often a served board checks that it still has a directory to serve. */
72
+ export const DIR_WATCHDOG_MS = 60_000;
73
+
56
74
  /**
57
75
  * Open the served board in the operator's browser.
58
76
  *
@@ -234,6 +252,7 @@ export const MAX_LOGGED_ERRORS = 20;
234
252
 
235
253
  export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
236
254
  const asks = [];
255
+ const summaries = [];
237
256
  const agents = [];
238
257
  const paused = [];
239
258
  const logged = [];
@@ -246,6 +265,39 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
246
265
  for (const { name, state, board, files: docs } of initiatives) {
247
266
  merged += state.merged;
248
267
  tickets += state.ticketList.length;
268
+ // Per-initiative, because one blended percentage over every initiative is
269
+ // not a fact about any of them: an operator reading "50%" across four
270
+ // slugs cannot tell which is nearly done from which has not started.
271
+ //
272
+ // The TITLE is the point of the row. `init.created` has carried a written
273
+ // sentence all along — "Settings on the board: edit config and the
274
+ // autonomy policy from the page" — and the board showed the directory
275
+ // slug. `waiting` and `last_ts` are here rather than a computed idle time
276
+ // because this payload is byte-compared under `--check` and reads no
277
+ // clock; the page ages them, exactly as it already ages agents.
278
+ summaries.push({
279
+ name,
280
+ title: typeof state.created?.data?.title === 'string' ? state.created.data.title : null,
281
+ tickets: state.ticketList.length,
282
+ merged: state.merged,
283
+ percent: state.percent,
284
+ waiting: board.asks.length,
285
+ // A COUNT, and deliberately not the findings themselves. Measured across
286
+ // 63 distinct real journals: 3 carry any finding at all, 49 in total,
287
+ // and NOT ONE names a ticket — so they cannot enrich a card, which is
288
+ // where a richer board would have put them. Their median claim is 429
289
+ // characters, a paragraph rather than a label, and STATE.md already
290
+ // renders the full seven-column table.
291
+ //
292
+ // So this is a pointer, not a copy: the research exists and the reader
293
+ // is told where. Duplicating the prose here would be ADR-21's defect
294
+ // and would cost ~600 B per finding in a byte-compared payload.
295
+ // Guarded: `crossBoard` is exported and takes any folded state, and a
296
+ // caller assembling one by hand need not have every collection. A
297
+ // missing array must read as "none", never take the board down.
298
+ findings: (state.findings ?? []).length,
299
+ last_ts: state.lastTs,
300
+ });
249
301
  if (state.lastTs !== null && (asOf === null || state.lastTs > asOf)) asOf = state.lastTs;
250
302
  for (const a of board.asks) asks.push({ ...a, init: name });
251
303
  for (const a of board.agents) agents.push({ ...a, init: name });
@@ -329,6 +381,10 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
329
381
  stop: stop === null ? null : { stopped: stop.stopped, reason: stop.reason },
330
382
  paused,
331
383
  asks,
384
+ // Ordered by directory name, like everything else here, so two renders of
385
+ // one journal set are byte-identical. `totals.percent` blends these; the
386
+ // rows are what let a reader see WHICH initiative it blends.
387
+ initiatives: summaries,
332
388
  agents,
333
389
  files,
334
390
  lanes,
@@ -607,14 +663,17 @@ function handleSettingsWrite(dir, route, body) {
607
663
 
608
664
  // ------------------------------------------------------------------- CLI
609
665
 
610
- const BOOLEAN_FLAGS = ['check', 'serve', 'write', 'open'];
666
+ const BOOLEAN_FLAGS = ['check', 'serve', 'write', 'open', 'detach', 'stop', 'status'];
611
667
  const VALUE_FLAGS = ['dir', 'port'];
612
668
  // Repeatable, unlike VALUE_FLAGS: sources are the union over every directory
613
669
  // given, exactly like cost.mjs's own `--transcripts`.
614
670
  const REPEATABLE_FLAGS = ['transcripts'];
615
671
 
616
672
  function parseArgs(argv) {
617
- const flags = { dir: '.tyran', port: 4173, check: false, serve: false, write: false, open: false, transcripts: [] };
673
+ const flags = {
674
+ dir: '.tyran', port: 4173, check: false, serve: false, write: false, open: false,
675
+ detach: false, stop: false, status: false, transcripts: [],
676
+ };
618
677
  for (let i = 0; i < argv.length; i += 1) {
619
678
  const arg = argv[i];
620
679
  if (!arg.startsWith('--')) throw new UsageError(`unexpected argument "${arg}"`);
@@ -646,25 +705,34 @@ function main() {
646
705
  if (!(err instanceof UsageError)) throw err;
647
706
  console.error(`board: ${err.message}`);
648
707
  console.error(
649
- 'usage: board.mjs [--dir <.tyran>] [--check] ' +
650
- '[--serve [--port <n>] [--write] [--transcripts <dir>]...]'
708
+ 'usage: board.mjs [--dir <.tyran>] [--check]\n' +
709
+ ' [--serve|--detach [--port <n>] [--write] [--open] [--transcripts <dir>]...]\n' +
710
+ ' [--status] [--stop]'
651
711
  );
652
712
  process.exit(2);
653
713
  }
654
- if (flags.write && !flags.serve) {
655
- console.error('board: --write only means anything with --serve (it is what the served page may edit)');
714
+ // `--detach` is `--serve` that returns. Every flag describing HOW to serve
715
+ // therefore has to accept either, or the detached form would refuse exactly
716
+ // the arguments it exists to be given.
717
+ const serving = flags.serve || flags.detach;
718
+ if (flags.serve && flags.detach) {
719
+ console.error('board: --serve and --detach are the same server, one holding the terminal and one not — pass one');
720
+ process.exit(2);
721
+ }
722
+ if (flags.write && !serving) {
723
+ console.error('board: --write only means anything with --serve or --detach (it is what the served page may edit)');
656
724
  process.exit(2);
657
725
  }
658
- if (flags.open && !flags.serve) {
726
+ if (flags.open && !serving) {
659
727
  // Same refusal as --write and --transcripts, for the same reason: there is
660
728
  // no URL to open without a server, and a flag that silently does nothing
661
729
  // reads as configuration.
662
- console.error('board: --open only means anything with --serve (there is no URL to open without it)');
730
+ console.error('board: --open only means anything with --serve or --detach (there is no URL to open without it)');
663
731
  process.exit(2);
664
732
  }
665
- if (flags.transcripts.length > 0 && !flags.serve) {
733
+ if (flags.transcripts.length > 0 && !serving) {
666
734
  console.error(
667
- 'board: --transcripts only means anything with --serve (it is what /cost.json reads instead of ' +
735
+ 'board: --transcripts only means anything with --serve or --detach (it is what /cost.json reads instead of ' +
668
736
  'the derived transcript directory)'
669
737
  );
670
738
  process.exit(2);
@@ -691,6 +759,63 @@ function main() {
691
759
  }
692
760
  const outDir = join(dir, 'state');
693
761
 
762
+ // ---- the three routes that talk ABOUT a server rather than being one ----
763
+ //
764
+ // All three are async, and `main` stays sync for everything else on
765
+ // purpose: the rendering path is the one every test and every hook drives,
766
+ // and making it return a promise would change the shape of a contract that
767
+ // has nothing to do with servers.
768
+ if (flags.status) {
769
+ findLiveServer(dir, flags.port).then((live) => {
770
+ if (live === null) {
771
+ console.log(
772
+ `board: no server is answering for ${dir} ` +
773
+ `(tried the recorded port, if any, then ${flags.port}-${flags.port + PORT_SEARCH_SPAN - 1}) — ` +
774
+ `start one with: node scripts/board.mjs --dir ${dir} --detach --write`,
775
+ );
776
+ process.exitCode = 1;
777
+ return;
778
+ }
779
+ console.log(
780
+ `board: serving ${urlFor(live.port)} (pid ${live.health.pid ?? '?'}; ` +
781
+ `${live.health.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'})`,
782
+ );
783
+ });
784
+ return;
785
+ }
786
+ if (flags.stop) {
787
+ stopServer(dir).then((result) => {
788
+ if (result.stopped) {
789
+ console.log(`board: stopped the server on port ${result.port} (pid ${result.pid})`);
790
+ return;
791
+ }
792
+ console.error(`board: ${result.reason}`);
793
+ process.exitCode = 1;
794
+ });
795
+ return;
796
+ }
797
+ if (flags.detach) {
798
+ startDetached(dir, { port: flags.port, write: flags.write, open: flags.open, transcripts: flags.transcripts })
799
+ .then((result) => {
800
+ if (result.error) {
801
+ console.error(`board: ${result.error}`);
802
+ process.exitCode = 2;
803
+ return;
804
+ }
805
+ // "Already running" is a SUCCESS, and saying which one it is matters:
806
+ // this command is meant to be safe to run on every session start, so
807
+ // its ordinary outcome is that there was nothing to do.
808
+ console.log(
809
+ result.reused
810
+ ? `board: already serving ${result.url} (pid ${result.pid ?? '?'})`
811
+ : `board: serving ${result.url} (pid ${result.pid ?? '?'}; ` +
812
+ `${flags.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'}; ` +
813
+ `stop it with: node scripts/board.mjs --dir ${dir} --stop)`,
814
+ );
815
+ });
816
+ return;
817
+ }
818
+
694
819
  if (flags.serve) {
695
820
  // Loopback-only, re-rendered per request so it is always fresh. No
696
821
  // filesystem path is ever derived from the URL.
@@ -726,6 +851,15 @@ function main() {
726
851
  // marker, the resume watcher and the usage sidecar are gitignored and
727
852
  // different on every machine, so they are served — the same split, and
728
853
  // the same argument, spend already makes.
854
+ // The liveness answer, and the ONLY reliable one. A caller asking
855
+ // "is a board already up for this repo" cannot use the recorded pid —
856
+ // see board-daemon.mjs for why — so it asks the server itself, and
857
+ // `dir` is what stops ANOTHER repository's board (same program, same
858
+ // route) from answering yes on this one's behalf.
859
+ if (req.url === HEALTH_ROUTE) {
860
+ sendJson(res, 200, { tyran_board: true, schema: 1, dir, pid: process.pid, port: flags.port, write: flags.write });
861
+ return;
862
+ }
729
863
  if (req.url === '/run.json') {
730
864
  try {
731
865
  sendJson(res, 200, { schema: 1, ...runState(resolve(dir, '..')) });
@@ -846,13 +980,46 @@ function main() {
846
980
  process.exitCode = 2;
847
981
  });
848
982
  server.listen(flags.port, '127.0.0.1', () => {
849
- const url = `http://127.0.0.1:${flags.port}/`;
983
+ const url = urlFor(flags.port);
984
+ // Written from INSIDE the listen callback, so the record only ever
985
+ // describes a server that actually bound a port — a record written
986
+ // before this point would be an intention, and `--stop` would signal
987
+ // whatever inherited the pid of a board that never started.
988
+ writeServerRecord(dir, { pid: process.pid, port: flags.port, url, write: flags.write, started_at: new Date().toISOString() });
850
989
  console.log(
851
990
  `board: serving ${url} ` +
852
991
  `(${flags.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'}; Ctrl-C to stop)`,
853
992
  );
854
993
  if (flags.open) openInBrowser(url);
855
994
  });
995
+ // Clear the record on the way out, so the next caller does not have to
996
+ // probe a port to learn that this one is gone. Best-effort: a killed
997
+ // process runs none of this, which is exactly why the reader treats the
998
+ // record as a hint and the health probe as the answer.
999
+ const clear = () => { removeServerRecord(dir); };
1000
+ process.on('exit', clear);
1001
+ for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
1002
+ process.on(signal, () => {
1003
+ clear();
1004
+ process.exit(0);
1005
+ });
1006
+ }
1007
+ // A board whose directory is gone is serving nothing, and nothing will
1008
+ // ever ask it to stop: `--stop` needs a `.tyran` to find the record in,
1009
+ // and the operator who deleted the checkout is not going to hunt a pid.
1010
+ // Detached servers are started automatically now, so "nobody ever stops
1011
+ // it" is the DEFAULT case rather than an unlucky one — a deleted worktree
1012
+ // otherwise leaves a process holding a port until the machine reboots.
1013
+ const watchdog = setInterval(() => {
1014
+ if (!existsSync(dir)) {
1015
+ clear();
1016
+ process.exit(0);
1017
+ }
1018
+ }, DIR_WATCHDOG_MS);
1019
+ // Unref'd so it is the SERVER that keeps this process alive, never the
1020
+ // timer: a watchdog that held the loop open would turn every exit path
1021
+ // above into a hang.
1022
+ watchdog.unref?.();
856
1023
  return;
857
1024
  }
858
1025
 
@@ -65,6 +65,7 @@ import { classifyPath, normalizePath, validateFile, knowledgeWarnings, MANDATORY
65
65
  import { auditEntries, loadEntries as loadKnowledgeEntries } from './knowledge.mjs';
66
66
  import { readPlatformUsage } from './usage-source.mjs';
67
67
  import { gitRunner } from './scan-repo.mjs';
68
+ import { SERVER_RECORD_FILE } from './board-daemon.mjs';
68
69
  import { parseMistakes, countSignatures, fenceState, KNOWLEDGE_THRESHOLD, MISTAKES_FILE, CLAUDE_MD_FILE } from './mistakes.mjs';
69
70
 
70
71
  /** Severity order is also the report order. `info` never fails the check. */
@@ -1613,7 +1614,17 @@ export function mistakesFindings(repoRoot, run = null) {
1613
1614
 
1614
1615
  /** The repo-global overnight runtime files that legally live at state/ level. */
1615
1616
  /** The cross-initiative board artefacts board.mjs writes at state/ level. */
1616
- export const CROSS_BOARD_FILES = Object.freeze(['BOARD.md', 'board.json', 'board.html']);
1617
+ export const CROSS_BOARD_FILES = Object.freeze([
1618
+ 'BOARD.md',
1619
+ 'board.json',
1620
+ 'board.html',
1621
+ // Not a projection like the three above — the running server's own record,
1622
+ // written from inside its listen callback and removed on the way out. It
1623
+ // sits at this level because the server serves the whole directory, and it
1624
+ // is machine-local for the same reason the overnight files are: another
1625
+ // clone has a different pid on a different port.
1626
+ SERVER_RECORD_FILE,
1627
+ ]);
1617
1628
 
1618
1629
  export const OVERNIGHT_RUNTIME_FILES = Object.freeze([
1619
1630
  'paused-until.json',
@@ -228,15 +228,37 @@ export function runState(repo, nowMs = Date.now()) {
228
228
  five_hour: pickWindow(sidecar.five_hour),
229
229
  seven_day: pickWindow(sidecar.seven_day),
230
230
  },
231
+ // Which mode the gate is IN, not only what it can see. Without this a page
232
+ // cannot tell "the gate cannot see" from "the feature was never switched
233
+ // on", and off is the default (templates/config.yaml) — so a telemetry
234
+ // warning built on the `usage` field alone would fire on every repository
235
+ // that has never enabled overnight mode.
236
+ limits_mode: readLimitsFile(repo)?.mode ?? 'off',
231
237
  };
232
238
  }
233
239
 
234
- /** Numbers and an ISO string only — never a free payload string from a hook. */
240
+ /**
241
+ * Numbers and an ISO string only — never a free payload string from a hook.
242
+ *
243
+ * `resets_at` arrives as epoch SECONDS: `statusline.mjs`'s `windowOf` keeps
244
+ * only `finiteNumber` values, and `usage-source.mjs` normalises the platform's
245
+ * ISO string to the same. This function tested `typeof === 'string'` and so
246
+ * returned null for every real payload it has ever been given — `/run.json`
247
+ * has never once carried a reset time, and the board's run panel could say a
248
+ * pause was in force but never when it would end.
249
+ *
250
+ * The string half of the guard was not wrong about the OUTPUT: this is the
251
+ * page's shape, and an ISO string is what a reader wants. It was wrong about
252
+ * the input. So convert, rather than widening the test and emitting seconds
253
+ * the page would have to know to multiply.
254
+ */
235
255
  function pickWindow(w) {
236
256
  if (w === null || typeof w !== 'object') return null;
257
+ const seconds = typeof w.resets_at === 'number' && Number.isFinite(w.resets_at) ? w.resets_at : null;
258
+ const iso = seconds === null ? null : new Date(seconds * 1000);
237
259
  return {
238
260
  used_percentage: typeof w.used_percentage === 'number' ? w.used_percentage : null,
239
- resets_at: typeof w.resets_at === 'string' ? w.resets_at : null,
261
+ resets_at: iso !== null && Number.isFinite(iso.getTime()) ? iso.toISOString() : null,
240
262
  };
241
263
  }
242
264
 
@@ -400,6 +400,17 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
400
400
  title: null,
401
401
  deps: null,
402
402
  agents: [],
403
+ // The same spawns as `agents`, by REFERENCE rather than by name, so a
404
+ // ticket can answer "what actually ran here" — which model, from when
405
+ // to when, ending in what verdict. `agents` stays a list of names
406
+ // because BOARD.md and the lane cards both read it as one.
407
+ //
408
+ // References, not copies, on purpose: the `report` fold mutates a
409
+ // spawn's status, verdict and reportTs after this push, and a copy
410
+ // taken at spawn time would freeze every run as `running` with no
411
+ // verdict — which is exactly the row an operator opens a finished
412
+ // ticket to read.
413
+ runs: [],
403
414
  report: null,
404
415
  review: null,
405
416
  merge: null,
@@ -482,7 +493,11 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
482
493
  }
483
494
  }
484
495
  state.agents.push(agent);
485
- if (data.ticket != null) ticketOf(data.ticket, ts).agents.push(agent.agent);
496
+ if (data.ticket != null) {
497
+ const onTicket = ticketOf(data.ticket, ts);
498
+ onTicket.agents.push(agent.agent);
499
+ onTicket.runs.push(agent);
500
+ }
486
501
  break;
487
502
  }
488
503
  case 'report': {
@@ -909,6 +924,25 @@ export function boardOf(state, { staleHours = DEFAULT_STALE_HOURS } = {}) {
909
924
  // discarded at fold time, so the board could say a ticket had come back
910
925
  // and never why — the one thing the reader opens the card for.
911
926
  report_text: t.report?.text ?? null,
927
+ // The two lifecycle facts the LANE could only imply. `done` said a
928
+ // ticket was merged and never which commit; `changes-requested` said a
929
+ // review had come back and never who wrote it. Both are in the journal
930
+ // — `review` carries ticket/verdict/by and `merge` carries ticket/sha —
931
+ // and neither reached the one surface people open to ask.
932
+ review: t.review === null ? null : { verdict: t.review.verdict, by: t.review.by, ts: t.review.ts },
933
+ merge: t.merge === null ? null : { sha: t.merge.sha, mode: t.merge.mode, ts: t.merge.ts },
934
+ // What actually ran, in spawn order: which agent, on which model, from
935
+ // when to when, ending in what verdict. `worked_by` answers "who
936
+ // touched this"; this answers "what did it cost me and how did it go",
937
+ // which is the question a finished ticket is opened for.
938
+ execution: t.runs.map((a) => ({
939
+ agent: a.agent,
940
+ role: a.role,
941
+ model: a.model,
942
+ started: a.spawnTs,
943
+ ended: a.reportTs,
944
+ verdict: a.verdict,
945
+ })),
912
946
  annotation: annotations.length > 0 ? annotations.join(' · ') : null,
913
947
  });
914
948
  }
@@ -375,6 +375,17 @@ export function scanRepo(dir, { run = gitRunner(dir) } = {}) {
375
375
  resume_margin_minutes: 5,
376
376
  keep_awake: false,
377
377
  },
378
+ // The dashboard, ON. Written in full for the same reason `limits:` is —
379
+ // the Settings tab patches keys that exist and will not invent them — but
380
+ // with the opposite default, because the argument for OFF does not apply.
381
+ // `limits:` off is inert; a board that does not start means every
382
+ // projection Tyran writes is generated and never read by anyone.
383
+ board: {
384
+ autostart: true,
385
+ port: 4173,
386
+ write: true,
387
+ open: false,
388
+ },
378
389
  };
379
390
 
380
391
  const questions = [];
@@ -745,6 +756,9 @@ export const STATE_GITIGNORE_LINES = Object.freeze([
745
756
  // that was stale the moment it was written.
746
757
  'state/conductor.json',
747
758
  'state/ANSWERS.md',
759
+ // The running board's own record: a pid and a port, which name a process on
760
+ // THIS machine and a stranger anywhere else.
761
+ 'state/board-server.json',
748
762
  ]);
749
763
  const STATE_GITIGNORE_BODY =
750
764
  '# Runtime files, never history. Leases record who holds a worktree or a\n' +
@@ -68,7 +68,7 @@ export function validateConfig(doc) {
68
68
  const errors = [];
69
69
  if (!isPlainObject(doc)) return ['config must be a mapping'];
70
70
 
71
- const known = ['profile', 'autonomy', 'tiers', 'validation', 'shared_zones', 'budget', 'main_writable_paths', 'limits', 'pricing', 'spend'];
71
+ const known = ['profile', 'autonomy', 'tiers', 'validation', 'shared_zones', 'budget', 'main_writable_paths', 'limits', 'pricing', 'spend', 'board'];
72
72
  for (const key of Object.keys(doc)) {
73
73
  if (!known.includes(key)) errors.push(`${key}: unknown top-level key`);
74
74
  }
@@ -259,9 +259,59 @@ export function validateConfig(doc) {
259
259
  }
260
260
  }
261
261
 
262
+ // The dashboard's own switches. Absent means the DEFAULTS below apply, and
263
+ // those defaults are ON — the board is where everything Tyran does becomes
264
+ // legible, and an install that leaves it off is an install where none of it
265
+ // is. This block exists to turn it DOWN, which is why every key is optional.
266
+ if ('board' in doc) {
267
+ if (!isPlainObject(doc.board)) errors.push('board: must be a mapping');
268
+ else {
269
+ const board = doc.board;
270
+ for (const key of ['autostart', 'write', 'open']) {
271
+ if (key in board && typeof board[key] !== 'boolean') {
272
+ errors.push(`board.${key}: must be true or false (quote 'off'/'on' if you meant a string — bare ones are YAML booleans)`);
273
+ }
274
+ }
275
+ if ('port' in board) {
276
+ const port = board.port;
277
+ if (!Number.isInteger(port) || port <= 0 || port > 65535) {
278
+ errors.push('board.port: must be an integer in (0, 65535]');
279
+ }
280
+ }
281
+ const knownBoard = ['autostart', 'port', 'write', 'open'];
282
+ for (const key of Object.keys(board)) {
283
+ if (!knownBoard.includes(key)) errors.push(`board.${key}: unknown key`);
284
+ }
285
+ }
286
+ }
287
+
262
288
  return errors;
263
289
  }
264
290
 
291
+ /**
292
+ * The board's settings, with the defaults applied.
293
+ *
294
+ * ONE function, because three callers need this answer — the session-start
295
+ * hook that autostarts, the setup skill's command, and doctor — and three
296
+ * copies of "default the port to 4173" is ADR-21 with a port number in it.
297
+ *
298
+ * `autostart` and `write` default TRUE. The board was previously reached only
299
+ * by a human typing a blocking command, which meant that on any install where
300
+ * nobody typed it, every projection Tyran writes existed and nothing read
301
+ * them. Defaulting off would preserve exactly that.
302
+ */
303
+ export const BOARD_DEFAULTS = Object.freeze({ autostart: true, port: 4173, write: true, open: false });
304
+
305
+ export function boardSettings(doc) {
306
+ const board = isPlainObject(doc) && isPlainObject(doc.board) ? doc.board : {};
307
+ return {
308
+ autostart: typeof board.autostart === 'boolean' ? board.autostart : BOARD_DEFAULTS.autostart,
309
+ port: Number.isInteger(board.port) && board.port > 0 && board.port <= 65535 ? board.port : BOARD_DEFAULTS.port,
310
+ write: typeof board.write === 'boolean' ? board.write : BOARD_DEFAULTS.write,
311
+ open: typeof board.open === 'boolean' ? board.open : BOARD_DEFAULTS.open,
312
+ };
313
+ }
314
+
265
315
  export const LIMITS_MODES = Object.freeze(['off', 'warn', 'pause']);
266
316
  export const LIMITS_LONG_WAIT = Object.freeze(['hold', 'resume']);
267
317
 
@@ -452,6 +452,32 @@ open one.
452
452
  a lease still held by an agent that has already reported. An orphaned lease
453
453
  blocks the next initiative from a resource nobody is using, and the person
454
454
  who hits it has no way to know it is stale.
455
+ - **Close the initiative when it is closed**, with the retrospective recorded
456
+ and the leases released:
457
+
458
+ ```bash
459
+ node "${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs" append <abs-journal> checkpoint <init> \
460
+ --actor conductor --data '{"phase":"closed","next_steps":[]}'
461
+ ```
462
+
463
+ `append ... checkpoint`, not a `checkpoint` subcommand — there is no such
464
+ subcommand, and the first draft of this line invented one. It would have
465
+ printed a usage block and closed nothing.
466
+
467
+ This is one line and it is load-bearing. The projection closes every still-
468
+ open spawn on a closing checkpoint, which is what stops an agent that
469
+ finished weeks ago from reading as live work, and it is the only signal any
470
+ reader has that an initiative is DONE rather than abandoned mid-flight.
471
+
472
+ Measured across 63 real journals: **9 ever received one**, while 43 sat
473
+ waiting on a question nobody answered. Nothing had ever told you to write
474
+ it — the fold that consumes it shipped, and the event that triggers it was
475
+ never emitted by anything, so the feature has been inert since it landed.
476
+
477
+ A closing checkpoint is not the same as "every ticket merged". Say it when
478
+ the work is over, including when it is over because it was abandoned — an
479
+ initiative someone walked away from is finished too, and saying so is what
480
+ keeps the board honest about which of them are still waiting on you.
455
481
  - **A usage-gate refusal is a wind-down order, not an obstacle.** Near the
456
482
  subscription window the gate refuses everything except checkpointing;
457
483
  its refusal text IS the checklist — follow it verbatim, in order, then
@@ -168,9 +168,16 @@ files on disk; the board is where any of it becomes legible, and it was the
168
168
  one thing installation never actually reached.
169
169
 
170
170
  ```bash
171
- node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" --dir .tyran --serve --write --open
171
+ node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" --dir .tyran --detach --write --open
172
172
  ```
173
173
 
174
+ **`--detach`, never `--serve`.** They are the same server; `--serve` holds the
175
+ terminal until Ctrl-C, which is right for a human who typed it and fatal here
176
+ — an agent that runs it sits on the call until the platform's timeout, and
177
+ every step below this one silently never happens. That is what this step used
178
+ to do. `--detach` waits only until the board answers, prints the URL, and
179
+ returns; `--stop` ends it.
180
+
174
181
  `--open` launches their browser; `--write` is what makes the **Settings** tab
175
182
  able to edit `config.yaml` and the autonomy policy from the page. Tell them
176
183
  that tab exists and what it covers — profile, autonomy class, tiers,
@@ -178,8 +185,12 @@ validation commands, shared zones, overnight limits — because for someone who
178
185
  would rather not hand-edit YAML in their own repository, that tab is the
179
186
  entire configuration story and they will not guess it is there.
180
187
 
181
- It holds the terminal while it serves. Say so, and say that Ctrl-C stops it
182
- and the board is still there next time.
188
+ Say that they do not have to run this again: the scan wrote a `board:` block
189
+ with `autostart: true`, so every later session starts the board if it is not
190
+ already up, and prints the URL in its opening summary. Several repositories at
191
+ once each get their own — the port walks forward from 4173 when one is taken.
192
+ `node scripts/board.mjs --dir .tyran --status` says where it is; `--stop` ends
193
+ it; `autostart: false` in the config turns the whole thing off.
183
194
 
184
195
  ## 5. Validate and report
185
196
 
@@ -68,6 +68,24 @@ limits:
68
68
  resume_margin_minutes: 5
69
69
  keep_awake: false # a real boolean, so the bare-off trap above cannot apply
70
70
 
71
+ # The dashboard. Unlike everything above, this defaults ON: the board is where
72
+ # a journal, a projection and a spend report become something a person can
73
+ # read, and an install where nobody starts it is an install where none of that
74
+ # is ever seen. Set autostart: false to turn it down.
75
+ #
76
+ # autostart: true start it with the session, if it is not already up
77
+ # port: 4173 the first port tried; the next 9 are used if it is taken,
78
+ # so several repositories can each have their own board
79
+ # write: true lets the Settings tab edit config.yaml and the autonomy
80
+ # policy. false serves the same page read-only.
81
+ # open: false true also launches your browser on every session, which
82
+ # is a tab per session — the URL is printed either way.
83
+ board:
84
+ autostart: true
85
+ port: 4173
86
+ write: true
87
+ open: false
88
+
71
89
  # What a model costs, per MILLION tokens. Optional; absent means the spend
72
90
  # report counts tokens and shows no money, which is the honest default —
73
91
  # Tyran does not know what you pay. Operator-written from a vendor's price