@jjanczur/tyran 0.1.29 → 0.1.31

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.
@@ -11,7 +11,7 @@
11
11
  {
12
12
  "name": "tyran",
13
13
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
14
- "version": "0.1.29",
14
+ "version": "0.1.31",
15
15
  "source": "./",
16
16
  "author": {
17
17
  "name": "Jacek Janczura",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tyran",
3
- "version": "0.1.29",
3
+ "version": "0.1.31",
4
4
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
5
5
  "author": {
6
6
  "name": "Jacek Janczura",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,191 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.31 — 2026-08-17
4
+
5
+ Seven things the journal had recorded and nothing was reading. The theme is
6
+ one defect wearing different clothes: an answer that was available, a
7
+ consumer that never asked for it, and a surface that reported confidence
8
+ instead of the gap.
9
+
10
+ ### Four things the fold recorded and threw away
11
+
12
+ Each of these was a question an operator asked the board, got a confident
13
+ answer to, and the answer was wrong in the same direction: everything looked
14
+ fine.
15
+
16
+ **An agent the initiative moved on without now reads `stale`, not `running`.**
17
+ Nothing in the projection ever downgraded a spawn, so an agent that never
18
+ reported stayed `running` in every artefact for as long as the journal
19
+ survived, and the board's header counted week-old ghosts as live work. Doctor
20
+ had been calling those same spawns abandoned the whole time, from the same
21
+ events — two answers to one question, which is the defect ADR-21 is named
22
+ after and which `pairSpawns` had already been through once for the adjacent
23
+ question of who is still working.
24
+
25
+ There is now one predicate, `journal.spawnStaleness`, and both consumers call
26
+ it; doctor's copy is gone rather than kept in sync. It could not live in
27
+ doctor, which imports the projection, so it sits in `journal.mjs` beside
28
+ `pairSpawns` where both already reach.
29
+
30
+ The threshold is journal time — measured against the initiative's own latest
31
+ event, never the wall clock. That is what `spawn-stale` has always meant, and
32
+ it is the only version that keeps `board.json` byte-exact under `--check`.
33
+ `blocked` still outranks `stale`, because that is the agent's own account of
34
+ why it stopped. The `age-fresh/warm/cold/dead` colours on the page are a
35
+ different question and keep their own vocabulary: an agent can be quiet for
36
+ hours without being stale, and stale while chattering every minute.
37
+
38
+ **A closing checkpoint closes the spawns it leaves open.** No event type
39
+ closed an initiative, so one could be explicitly wound up with three agents
40
+ that never reported still running forever. `checkpoint` with `phase: closed`
41
+ — the one reserved value in an otherwise free-text field — now closes that
42
+ initiative's still-open spawns at fold time, and only the ones folded before
43
+ it, so an agent spawned afterwards keeps its own lifecycle. They are closed,
44
+ never reported: no verdict is invented for an agent that never filed one, and
45
+ each is named in the warnings rather than tidied away.
46
+
47
+ **A gate that passes after refusing no longer erases the refusal.** Results
48
+ are keyed by `kind`, so a re-run won the slot, and *"security denied this,
49
+ then someone re-ran it green"* rendered identically to *"security has only
50
+ ever passed"*. The event count always survived, so the volume was never lost
51
+ — only the verdict. The last refusal is kept beside the current result and
52
+ gets its own column in `STATE.md`. A refusal is a named set (`deny`, `fail`,
53
+ `rejected`, …) rather than "anything that is not a pass": the first draft was
54
+ the latter, and the demo fixture caught it at once, marking every `open` gate
55
+ as carrying a permanent objection it had never raised.
56
+
57
+ **A report carries what the agent said, not only its verdict.** `decision`
58
+ folds its `text` and `gate` folds its `evidence`; `report` was the one carrier
59
+ of description that wrote to nowhere, so a `changes-needed` card reached the
60
+ board with the reason it came back discarded at fold time. One field reads
61
+ `text`, then `note`, then `evidence`, because agents improvise the key.
62
+
63
+ The board header now says *open* rather than *running* and names the stale
64
+ count beside it — the agents are still counted and still in the strip, but an
65
+ open spawn and live work are not the same fact and the tile was asserting the
66
+ second from the first.
67
+
68
+ ### The two findings doctor could only ever report
69
+
70
+ `state-legacy-initiatives-dir` shipped with a remedy that read "relocate the
71
+ contents by hand, one initiative directory at a time". That is advice, not a
72
+ remedy, and the installs carrying the finding are by definition the ones
73
+ nobody has touched since 0.1.8. `scripts/migrate.mjs` does the move.
74
+
75
+ It is explicit and never automatic, because it MOVES an append-only history
76
+ rather than seeding a file that does not exist yet — the same reason it is not
77
+ a step inside setup. It previews by default and does nothing until asked twice.
78
+ It never overwrites: a name that already exists under `state/` is a conflict,
79
+ reported and skipped and left untouched on **both** sides, because merging two
80
+ directories that share a name is a decision only the operator can make and
81
+ making it silently would destroy the evidence needed to make it correctly. It
82
+ never deletes anything it did not itself empty. It is idempotent, and it exits
83
+ 1 while any conflict stands, so an automated caller can tell "done" from "done
84
+ except for the part that mattered".
85
+
86
+ **`mistakes-file-missing`** (`info`) splits an absence that used to be one
87
+ thing. Deleting `MISTAKES.md` is the documented opt-out and still produces no
88
+ finding at all — a tool that nags about a file you deliberately removed is a
89
+ tool you switch off, and that would cost the gates sitting next to it. But an
90
+ install created before the ledger existed never declined anything; nobody
91
+ offered. Git is the only witness that can tell those apart, so the finding
92
+ fires only where git can answer AND has never seen the file. Where there is no
93
+ repository, or no git, it says nothing rather than guessing — a guess there
94
+ nags precisely the operator who already opted out.
95
+
96
+ Neither is an alarm, but for different reasons.
97
+ `state-legacy-initiatives-dir` stays a `warning` — a legacy layout genuinely
98
+ hides initiative files from every mechanical consumer — and what changed is
99
+ that it finally has a remedy rather than a paragraph of advice.
100
+ `mistakes-file-missing` is `info` because nothing is broken at all: it is an
101
+ offer, and the only absence it will ever break silence about is the one
102
+ nobody chose.
103
+
104
+ ### Accept-then-ignore, ended without nagging
105
+
106
+ `append` accepts any key inside `data` and always will: *"data may always
107
+ carry extra keys"* is a promise the envelope makes, the evidence gate relies
108
+ on it for four of its own, and turning it into a rule would fail every journal
109
+ ever written the moment they were re-validated. So this is a report, never a
110
+ refusal — and it is deliberately not the whole report.
111
+
112
+ Measured on one real install: **130 distinct (event, key) pairs across 39
113
+ initiatives**, and the long tail of that is deliberate annotation —
114
+ `init.created.hardware`, `retro.entry.proposed_as_diffs`, `spawn.stories`.
115
+ Naming all of it as findings would report the extension mechanism working as
116
+ designed, on every healthy repo, and doctor's own severity notes already argue
117
+ where that ends: a check that is red during normal operation is a check people
118
+ learn to skip — and this one sits next to the gates.
119
+
120
+ The defect hiding in that tail is narrower and worth a warning each.
121
+ **`journal-key-near-miss`** reports a key one edit from the key consumers
122
+ actually read: `next_step` for `next_steps` is accepted, never read, and never
123
+ reported, so the resume surface is empty while the agent that wrote it
124
+ believes it recorded something. Distance one and nothing looser — at two,
125
+ `note` matches `next` and the check starts inventing typos in correct
126
+ journals. Keys of three characters or fewer are exempt for the same reason.
127
+
128
+ **`journal-key-unread`** (`info`) counts and names the rest, so nothing is
129
+ dropped (ADR-19 correction 1) and "recorded" stays distinguishable from
130
+ "recorded AND read" — without turning a documented contract into 130 rows of
131
+ alarm.
132
+
133
+ `DATA_KNOWN` in `journal.mjs` is the map of what each event type's consumers
134
+ read, and it sits next to `DATA_REQUIRED` because both answer "what is in
135
+ `data`". It is descriptive: an incomplete entry can only under-report, never
136
+ invent a finding.
137
+
138
+ ## 0.1.30 — 2026-08-17
139
+
140
+ The first release built on an outside contribution. It fixes a spend ledger
141
+ that was confidently reporting the wrong session, and it is also the release
142
+ where the "change both surfaces" rule caught itself being broken.
143
+
144
+ ### Spend, when the conductor ran from somewhere else
145
+
146
+ Measured on a real run: a Claude Code Desktop session operated on a repo
147
+ through absolute paths and worktrees, but was itself started in a sibling
148
+ folder. `cost.mjs` derives a transcript directory from the repo path and falls
149
+ back to scanning every project directory for a `cwd` match — both assume the
150
+ conductor ran *from* the repo, and neither one held here. A different,
151
+ unrelated `claude` run had once been started inside the repo (for the trust
152
+ dialog), so the direct lookup found a directory and stopped there. The board's
153
+ Spend tab rendered that unrelated session — 17 requests, one model, "0 agents
154
+ attributed", conductor overhead 100% — as if it were the whole initiative,
155
+ with nothing on the page saying that ~66 agent transcripts and 2 300 requests
156
+ were sitting elsewhere.
157
+
158
+ Two operator-named overrides, both resolved by `cost.mjs` itself so
159
+ `board.mjs --serve` gets them for free: a repeatable `--transcripts <dir>` on
160
+ the command line, and `spend.transcript_dirs` in `.tyran/config.yaml`. Either
161
+ replaces the derived-slug / cwd-probe resolution outright; a given directory
162
+ that does not exist is reported in the new `transcript_dirs_missing` field
163
+ rather than dropped. The Spend tab now shows a hint — pointing at both
164
+ overrides — whenever it finds zero agent transcripts while the board itself
165
+ lists running agents, which is the shape this failure actually has: a tab that
166
+ renders, with honest numbers about the wrong session.
167
+
168
+ Contributed by [@FreddyFormosa](https://github.com/FreddyFormosa) in
169
+ [#66](https://github.com/jjanczur/tyran/pull/66), found on a 14-ticket
170
+ production run — the failure above is his measurement, not a constructed one.
171
+
172
+ ### The half of "change both, always" that got left out
173
+
174
+ That contribution updated `docs/board.md`, `docs/configuration.md` and
175
+ `docs/cost.md` and left `board.mdx`, `configuration.mdx` and `cost.mdx`
176
+ untouched, which is precisely the divergence `CLAUDE.md` names — "docs/*.md
177
+ and site/src/content/docs/*.mdx publish the same claims. Change both, always."
178
+ All three pages are now mirrored, cross-links rewritten relative
179
+ (`../cost/#when-resolution-fails`) so the Pages build keeps its `/tyran` base
180
+ prefix.
181
+
182
+ Worth naming because of *how* it was caught: not by review, but by CI going
183
+ red on a different claim entirely. The README said 1405 unit tests and the
184
+ suite had 1417, and that check lives in the workflow rather than in the suite
185
+ — no test inside the suite can run the suite — so `node --test` reported green
186
+ locally right up to the point the pull request was opened. The number is now
187
+ 1417, measured rather than typed. The .mdx gap was found while fixing it.
188
+
3
189
  ## 0.1.29 — 2026-08-16
4
190
 
5
191
  Tyran has videos. Five cuts, and a page that says which one to send.
package/README.md CHANGED
@@ -297,7 +297,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
297
297
  fires and who invokes it, is in
298
298
  [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
299
299
  themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
300
- it: 1405 unit tests, run with `node --test "tests/**/*.test.mjs"`.
300
+ it: 1451 unit tests, run with `node --test "tests/**/*.test.mjs"`.
301
301
 
302
302
  ## Documentation
303
303
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.29",
3
+ "version": "0.1.31",
4
4
  "description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -98,6 +98,12 @@ h3{font-family:var(--font);color:var(--heading);font-size:.85rem;margin:1.1rem 0
98
98
  .agent .age-fresh{color:var(--sage)}
99
99
  .agent .age-warm{color:var(--brass-bright)}
100
100
  .agent .age-cold{color:var(--clay)}
101
+ /* Stale is a SERVER verdict in journal time, so it marks the whole chip rather
102
+ than joining the wall-clock age colours below — two different questions must
103
+ not share one vocabulary. Muted border, not red: an abandoned agent is a
104
+ bookkeeping fact, while the red below is "this died mid-flight". */
105
+ .agent.stale{border-left-color:var(--brass);opacity:.82}
106
+ .agent .stale-mark{color:var(--brass-bright);font-weight:600}
101
107
  /* A dead agent gets the only bold red on the page: three hours of silence is
102
108
  a different event from thirty minutes, and it used to share a colour. */
103
109
  .agent .age-dead{color:var(--clay-bright);font-weight:700}
@@ -423,9 +429,20 @@ if (data.schema !== 1) {
423
429
  var strip = el('div', 'agents');
424
430
  if (agents.length === 0) strip.appendChild(el('div', 'empty', 'none running'));
425
431
  agents.forEach(function (a) {
426
- var chip = el('div', 'agent');
432
+ var chip = el('div', 'agent' + (a.stale ? ' stale' : ''));
427
433
  chip.appendChild(el('div', 'name', a.agent + (a.role ? ' · ' + a.role : '')));
428
434
  chip.appendChild(el('div', null, (a.init ? a.init + ' · ' : '') + (a.ticket || 'no ticket') + ' · ' + a.state));
435
+ // NOT the same statement as the age lines below, and the wording keeps
436
+ // them apart on purpose. Those are wall-clock: "how long since it spoke,
437
+ // right now, where you are sitting". This one is journal time and comes
438
+ // from the server, where doctor's own threshold computed it — "the
439
+ // initiative moved on without it", which is still true tomorrow and is
440
+ // the same for every reader of this journal. An agent can be quiet for
441
+ // hours without being stale, and stale while chattering every minute.
442
+ if (a.stale) {
443
+ chip.appendChild(el('div', 'stale-mark',
444
+ 'STALE — open ' + (a.open_hours === null ? '?' : a.open_hours) + ' h of journal time'));
445
+ }
429
446
  if (a.detail) chip.appendChild(el('div', 'note', a.detail));
430
447
  // What the agent said it would do next. It has been in board.json since
431
448
  // the fold learned to read progress events, and the strip has never
@@ -473,7 +490,16 @@ if (data.schema !== 1) {
473
490
  var ovTiles = el('div', 'tiles');
474
491
  ovTiles.appendChild(tile('waiting on you', String(asks.length),
475
492
  asks.length === 0 ? 'nothing blocked on a decision' : 'answer them on the next tab', asks.length > 0 ? 'lead' : null));
476
- ovTiles.appendChild(tile('agents running', String(agents.length), 'across ' + (totals.initiatives || 0) + ' initiative(s)'));
493
+ // The headline number is the LIVE one. "Agents running" counted every open
494
+ // spawn, so an initiative abandoned a week ago reported a busy fleet; the
495
+ // stale ones are still counted, still listed in the strip, and now said out
496
+ // loud rather than folded into a figure that reads as live work.
497
+ var staleCount = totals.agents_stale || 0;
498
+ ovTiles.appendChild(tile('agents running', String(agents.length - staleCount),
499
+ staleCount > 0
500
+ ? staleCount + ' more stale · across ' + (totals.initiatives || 0) + ' initiative(s)'
501
+ : 'across ' + (totals.initiatives || 0) + ' initiative(s)',
502
+ staleCount > 0 ? 'lead' : null));
477
503
  // An initiative with no tickets used to read "0% · 0 of 0 merged", which is
478
504
  // exactly what a fully stalled one reads. Nothing-started and
479
505
  // nothing-finished are different situations and deserve different words.
@@ -605,6 +631,10 @@ if (data.schema !== 1) {
605
631
  // is already done — precisely when the running-agents list is empty.
606
632
  row('worked by', card.worked_by && card.worked_by.length ? card.worked_by.join(', ') : null);
607
633
  row('note', card.annotation);
634
+ // What the agent SAID when it handed this back. The verdict alone told you
635
+ // a ticket had come back and never why, which is the one thing the card is
636
+ // opened for.
637
+ row('reported', card.report_text);
608
638
  row('last event', card.since ? ago(card.since) + ' (' + card.since + ')' : null);
609
639
  if (cost) {
610
640
  var hit = (cost.by_ticket || []).filter(function (r) { return r.ticket === card.id; })[0];
@@ -858,6 +888,37 @@ if (data.schema !== 1) {
858
888
  return box;
859
889
  };
860
890
 
891
+ // A PURE function on purpose: no DOM, so a test can extract this one
892
+ // function's source out of the page and evaluate it standalone, without a
893
+ // browser, and check what it decides for a payload it never had to fetch.
894
+ //
895
+ // Two callers, one decision. renderSpend calls this once spend loaded
896
+ // normally; the cost-fetch handler below calls it BEFORE the early return
897
+ // on a payload with transcripts_found false — a directory named in
898
+ // transcript_dirs_missing is exactly as real a fact when nothing was
899
+ // found at all as when something was, and a single function neither call
900
+ // site can restate differently is what keeps that true.
901
+ var spendResolutionHints = function (payload) {
902
+ var hints = [];
903
+ var missing = (payload && payload.transcript_dirs_missing) || [];
904
+ if (missing.length > 0) {
905
+ var noun = missing.length === 1 ? 'directory' : 'directories';
906
+ hints.push('Given transcript ' + noun + ' not found: ' + missing.join(', ') + '.');
907
+ }
908
+ // Only on the branch that never reaches renderSpend at all: when spend
909
+ // WAS found, "no transcripts" would be false and misleading — the tab
910
+ // renders its own numbers and, if it turns out zero agents were among
911
+ // them, the separate agents-vs-coverage hint inside renderSpend covers it.
912
+ if (payload && payload.transcripts_found === false) {
913
+ hints.push(
914
+ 'No transcripts found for this repo. If the conductor ran from another working directory, ' +
915
+ 'point the board at that session: board.mjs --serve --transcripts <dir> or set ' +
916
+ 'spend.transcript_dirs in .tyran/config.yaml.'
917
+ );
918
+ }
919
+ return hints;
920
+ };
921
+
861
922
  var renderSpend = function (into, metric) {
862
923
  clear(into);
863
924
  var t = cost.totals || {};
@@ -932,6 +993,27 @@ if (data.schema !== 1) {
932
993
  ' oversized record(s) were skipped; their tokens are missing from every figure here.');
933
994
  }
934
995
  into.appendChild(el('div', 'caveat', notes.join(' ')));
996
+
997
+ // Zero agent transcripts while the board itself lists agents is not "no
998
+ // agents ran" — it is the resolved directory being the WRONG one. A
999
+ // conductor session started from a working directory other than the repo
1000
+ // it operates on files its transcript under a project directory no
1001
+ // derivation from the repo path reaches, and this is the one place an
1002
+ // operator would otherwise have no reason to suspect it: the tab renders,
1003
+ // the totals are honest numbers, and they are honest numbers about the
1004
+ // wrong session.
1005
+ if ((cov.agent_transcripts || 0) === 0 && agents.length > 0) {
1006
+ into.appendChild(el('div', 'hint',
1007
+ 'No agent transcripts found where this repo\\u2019s transcripts are expected. If the conductor ' +
1008
+ 'ran from another working directory, point the board at that session: board.mjs --serve ' +
1009
+ '--transcripts <dir> or set spend.transcript_dirs in .tyran/config.yaml.'));
1010
+ }
1011
+ // cost.transcripts_found is true whenever this function runs at all, so
1012
+ // spendResolutionHints only ever contributes the missing-dirs line here
1013
+ // — the "no transcripts found" line is reachable exclusively through the
1014
+ // fetch handler's own call below, on the branch that never reaches this
1015
+ // function.
1016
+ spendResolutionHints(cost).forEach(function (h) { into.appendChild(el('div', 'hint', h)); });
935
1017
  };
936
1018
 
937
1019
  // Spend is FETCHED, never embedded: it is derived from transcripts under
@@ -973,7 +1055,21 @@ if (data.schema !== 1) {
973
1055
  ((payload && payload.schema) || 'absent') + ') — regenerate the board with the Tyran that served it.');
974
1056
  return;
975
1057
  }
976
- if (!payload.transcripts_found) return; // genuinely nothing to show
1058
+ if (!payload.transcripts_found) {
1059
+ // Genuinely nothing to roll up — but the explanation still has to
1060
+ // reach the page. This used to be a silent early return that left
1061
+ // spBody carrying the "open with --serve" hint written before the
1062
+ // fetch even started, unconditionally wrong once the fetch answers:
1063
+ // it made the everyday single-typo spend.transcript_dirs case
1064
+ // (payload carries transcript_dirs_missing but no coverage at all,
1065
+ // since renderSpend — the only other place that hint used to live
1066
+ // — never runs on this branch) look exactly like a repo that had
1067
+ // never been served at all. Reviewed and reproduced live via
1068
+ // cost.json before this fix.
1069
+ clear(spBody);
1070
+ spendResolutionHints(payload).forEach(function (h) { spBody.appendChild(el('div', 'hint', h)); });
1071
+ return;
1072
+ }
977
1073
  cost = payload;
978
1074
  renderSpend(spBody, 'tokens');
979
1075
  var t = cost.totals || {};
package/scripts/board.mjs CHANGED
@@ -20,7 +20,8 @@
20
20
  * initiative reads as "all is well" exactly when it is not.
21
21
  *
22
22
  * CLI:
23
- * node board.mjs [--dir <.tyran>] [--check] [--serve [--port <n>] [--write]]
23
+ * node board.mjs [--dir <.tyran>] [--check]
24
+ * [--serve [--port <n>] [--write] [--transcripts <dir>]...]
24
25
  * Exit: 0 ok · 1 drift (--check) · 2 usage/IO
25
26
  */
26
27
  import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
@@ -262,6 +263,12 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
262
263
  totals: {
263
264
  initiatives: initiatives.length,
264
265
  agents: agents.length,
266
+ // Of those, how many the journal has moved on without. `agents` counts
267
+ // OPEN spawns, which is what it has always counted and what the strip
268
+ // lists — but presenting that number as "running" made a week-old ghost
269
+ // indistinguishable from an agent working right now, and an overnight
270
+ // operator reads this tile before anything else on the page.
271
+ agents_stale: agents.filter((a) => a.stale === true).length,
265
272
  merged,
266
273
  tickets,
267
274
  percent: tickets === 0 ? 0 : Math.round((merged / tickets) * 100),
@@ -305,8 +312,12 @@ export function crossJson(payload) {
305
312
  export function renderCrossMd(payload) {
306
313
  const parts = [GENERATED_MD_HEADER, '# BOARD — all initiatives\n\n'];
307
314
  const t = payload.totals;
315
+ // "open", not "running": the headline used to assert that every open spawn
316
+ // was live work, and the stale ones are named right after it rather than
317
+ // being quietly dropped from the count (ADR-19 correction 1).
308
318
  parts.push(
309
- `**${t.agents} agent(s) running across ${t.initiatives} initiative(s) · ` +
319
+ `**${t.agents} agent(s) open across ${t.initiatives} initiative(s)` +
320
+ `${t.agents_stale > 0 ? `, ${t.agents_stale} stale` : ''} · ` +
310
321
  `${t.merged}/${t.tickets} tickets merged (${t.percent}%) · as of ${inline(payload.as_of)}**\n`,
311
322
  );
312
323
  // First, and above the pause: a STOP outranks everything. It is the one
@@ -561,9 +572,12 @@ function handleSettingsWrite(dir, route, body) {
561
572
 
562
573
  const BOOLEAN_FLAGS = ['check', 'serve', 'write'];
563
574
  const VALUE_FLAGS = ['dir', 'port'];
575
+ // Repeatable, unlike VALUE_FLAGS: sources are the union over every directory
576
+ // given, exactly like cost.mjs's own `--transcripts`.
577
+ const REPEATABLE_FLAGS = ['transcripts'];
564
578
 
565
579
  function parseArgs(argv) {
566
- const flags = { dir: '.tyran', port: 4173, check: false, serve: false, write: false };
580
+ const flags = { dir: '.tyran', port: 4173, check: false, serve: false, write: false, transcripts: [] };
567
581
  for (let i = 0; i < argv.length; i += 1) {
568
582
  const arg = argv[i];
569
583
  if (!arg.startsWith('--')) throw new UsageError(`unexpected argument "${arg}"`);
@@ -574,6 +588,11 @@ function parseArgs(argv) {
574
588
  if (value === undefined) throw new UsageError(`flag --${name} needs a value`);
575
589
  flags[name] = name === 'port' ? Number(value) : value;
576
590
  i += 1;
591
+ } else if (REPEATABLE_FLAGS.includes(name)) {
592
+ const value = argv[i + 1];
593
+ if (value === undefined) throw new UsageError(`flag --${name} needs a value`);
594
+ flags[name].push(value);
595
+ i += 1;
577
596
  } else throw new UsageError(`unknown flag --${name}`);
578
597
  }
579
598
  if (!Number.isInteger(flags.port) || flags.port <= 0 || flags.port > 65535) {
@@ -589,13 +608,23 @@ function main() {
589
608
  } catch (err) {
590
609
  if (!(err instanceof UsageError)) throw err;
591
610
  console.error(`board: ${err.message}`);
592
- console.error('usage: board.mjs [--dir <.tyran>] [--check] [--serve [--port <n>] [--write]]');
611
+ console.error(
612
+ 'usage: board.mjs [--dir <.tyran>] [--check] ' +
613
+ '[--serve [--port <n>] [--write] [--transcripts <dir>]...]'
614
+ );
593
615
  process.exit(2);
594
616
  }
595
617
  if (flags.write && !flags.serve) {
596
618
  console.error('board: --write only means anything with --serve (it is what the served page may edit)');
597
619
  process.exit(2);
598
620
  }
621
+ if (flags.transcripts.length > 0 && !flags.serve) {
622
+ console.error(
623
+ 'board: --transcripts only means anything with --serve (it is what /cost.json reads instead of ' +
624
+ 'the derived transcript directory)'
625
+ );
626
+ process.exit(2);
627
+ }
599
628
  const dir = resolve(flags.dir);
600
629
  if (!existsSync(dir)) {
601
630
  console.error(`board: no such directory ${dir}`);
@@ -717,7 +746,11 @@ function main() {
717
746
  if (req.url === '/cost.json') {
718
747
  let body;
719
748
  try {
720
- body = costJson(costReport({ tyranDir: dir }));
749
+ // `flags.transcripts` is [] unless the operator started this
750
+ // server with `--transcripts`; costReport falls through to
751
+ // `spend.transcript_dirs` and then the derived directory on its
752
+ // own, so an empty array here changes nothing for the common case.
753
+ body = costJson(costReport({ tyranDir: dir, transcriptDirs: flags.transcripts }));
721
754
  } catch (err) {
722
755
  // A cost failure must never take the board down with it: the
723
756
  // board answers "what is going on", and that answer does not