@jjanczur/tyran 0.1.20 → 0.1.21

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.20",
14
+ "version": "0.1.21",
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.20",
3
+ "version": "0.1.21",
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,81 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.21 — 2026-08-14
4
+
5
+ ### The board said "all is well" in five different ways it should not have
6
+
7
+ An audit read the page against its own promise — that it never shows a healthy
8
+ board over an unhealthy repo — and it failed that promise five times.
9
+
10
+ **A partially damaged journal rendered as a healthy initiative.** The existing
11
+ guard fires only when NOTHING was readable. Three good tickets plus one
12
+ unparseable line folded to a board with `errors: []` on it, and the lost line
13
+ left no mark anywhere. `project.mjs` has produced exactly the right sentences
14
+ for this since the projection layer existed — `board.mjs` had simply never
15
+ asked for them. It asks now, and the page carries a **Warnings** section
16
+ naming the initiative and what could not be accounted for: a skipped line, a
17
+ lease released by a non-holder, an override for a ticket that does not exist.
18
+ The likelier damage is the partial kind, because a crash mid-write takes the
19
+ tail, not the file.
20
+
21
+ **"Needs a human" counted lanes, not humans.** A ticket parked by a
22
+ `ticket.status` override leaves no card in the `blocked` lane — `boardOf`
23
+ resolves the override before the blockage — so an agent could sit blocked on
24
+ that ticket while the tile read **0**. Measured on the shipped fixture: the
25
+ tile now reads 2 where it read 0, and both are agents rather than lanes. It
26
+ counts from both sources, on the server, and the sub-label breaks out which is
27
+ which.
28
+
29
+ **Staleness was shown and never escalated.** Agents rendered in the order the
30
+ journals spawned them, so the one that had said nothing longest could be last.
31
+ They are now sorted stalest-first, said so above the strip, and three hours of
32
+ silence gets its own bucket and its own red — "468 HOURS since last signal —
33
+ likely dead" is not the same event as thirty minutes, and the two used to
34
+ share a colour. Each chip also carries **what the agent said it would do
35
+ next**, which has been in `board.json` since the fold learned to read
36
+ `progress` events and had never been rendered.
37
+
38
+ **A spend failure was indistinguishable from having no server.** A crashed
39
+ reader, an unparseable rate card and a page opened over `file://` all ended as
40
+ the same silently missing section — and the server had already built the
41
+ sentence that tells them apart, for a 503 nothing displayed. Each now says
42
+ which it was; `file://` still says nothing, because there it is not a failure.
43
+
44
+ **Over the initiative ceiling, the served page was a plain-text 500 that the
45
+ page's own 30-second refresh re-fetched twice a minute.** It is now a readable
46
+ page that names the cause and does not reload itself. The CLI still refuses
47
+ loudly with exit 2 — that is right when a human is reading exit codes.
48
+
49
+ ### The drill-down reaches the files an initiative actually has
50
+
51
+ Selecting a card now lists that initiative's `PLAN.md`, `NOTES.md`, `RETRO.md`,
52
+ `STATE.md` and `PROGRESS.md` — **the ones that exist**, checked with
53
+ `existsSync`, never a list of what a well-run initiative ought to contain and
54
+ never created to satisfy a link.
55
+
56
+ The recorded path is repo-relative, and that is not cosmetic. `board.json` is
57
+ committed and compared byte for byte, so an absolute path would make two
58
+ clones of one journal disagree and fail `--check` on any machine whose home
59
+ directory is spelled differently — the same reason spend is served rather than
60
+ embedded. It was nearly shipped absolute; there is now a test that fails on
61
+ any `"path"` starting at the filesystem root.
62
+
63
+ Nothing is served: `--serve` still answers exactly three URLs and derives a
64
+ filesystem path from none of them, which is worth more than a clickable link.
65
+
66
+ ### How to open the dashboard, said once, plainly
67
+
68
+ `docs/board.md` gains an **Opening it** section, mirrored on the site: the
69
+ serve command and the URL it prints, the `open`/`xdg-open`/`start` line for
70
+ the file, what the difference between them is (spend, and only spend), and the
71
+ fact that inside a session you type neither, because `/tyran:status`
72
+ regenerates the board and tells you where it is. The README says the same in
73
+ three lines instead of implying it.
74
+
75
+ Verified in a browser against a two-initiative tree, one of whose journals was
76
+ deliberately corrupted: 0 console errors, 0 failed requests, the tile at 2,
77
+ three warnings listed, the file rows repo-relative.
78
+
3
79
  ## 0.1.20 — 2026-08-14
4
80
 
5
81
  ### `.tyran/` was tracked, and an entire initiative inside it was not
@@ -75,6 +151,27 @@ narrower advice each time.
75
151
  - **The dashboard GIF runs at 4 fps instead of 8.3** — the same recording, at a
76
152
  speed a tab can actually be read at.
77
153
 
154
+ ### The dist-tag is earned, not inherited from the last run
155
+
156
+ Creating GitHub Releases for sixteen historical tags in one batch fired
157
+ `npm-publish.yml` sixteen times. The workflow's safety argument was that npm
158
+ refuses a version that already exists — true, and too small: **npm refusing a
159
+ DUPLICATE version is not npm refusing an OLD one.** Four of those versions had
160
+ never reached npm, so they published cleanly and each took the `latest`
161
+ dist-tag on the way past. For roughly a minute `npm i @jjanczur/tyran` served
162
+ **0.1.2**. Found within two minutes, by checking the registry rather than the
163
+ sixteen green workflow runs, and self-corrected when 0.1.20's own publish
164
+ landed last.
165
+
166
+ The workflow now asks the registry which version is highest and publishes
167
+ `--tag latest` only when the version in hand IS that one; anything older
168
+ gets `--tag historical` and moves nothing. The comparison is `sort -V`, not
169
+ string order — `0.1.9` sorts above `0.1.10` alphabetically, which would have
170
+ mis-tagged every 0.1.x release past the ninth.
171
+
172
+ Side effect, kept: 0.1.1, 0.1.2, 0.1.15 and 0.1.16 are now on npm, so the
173
+ registry finally carries every released version.
174
+
78
175
  ## 0.1.19 — 2026-08-14
79
176
 
80
177
  ### The board answered four questions on one scroll
package/README.md CHANGED
@@ -162,16 +162,32 @@ echo "wrong branch — hold everything" > .tyran/STOP
162
162
  npx @jjanczur/tyran board --dir .tyran --serve
163
163
  ```
164
164
 
165
- A read-only board on loopback, re-rendered on every request. That command is
166
- the one place a Node version matters — `npx` runs the scripts outside Claude
167
- Code, and they need **Node ≥ 22**. Four tabs, because the page answers four
168
- questions:
169
-
170
- - **Overview** — what is waiting on you, agents running, progress, tickets that
171
- need a human; then the agent strip, each chip carrying the time since that
172
- agent last signalled.
165
+ It prints `board: serving http://127.0.0.1:4173/` — **open that URL.** The
166
+ board is read-only, bound to loopback, re-rendered on every request, and it
167
+ reloads itself every 30 seconds; `--port <n>` if 4173 is taken, `Ctrl-C` to
168
+ stop. That command is the one place a Node version matters, because `npx` runs
169
+ the scripts outside Claude Code and they need **Node ≥ 22**.
170
+
171
+ No terminal, no server: the same page is written to **`.tyran/state/board.html`**
172
+ after every agent, so you can just open the file —
173
+
174
+ ```bash
175
+ open .tyran/state/board.html # xdg-open on Linux, start on Windows
176
+ ```
177
+
178
+ — and inside a session you need neither command, because **`/tyran:status`
179
+ regenerates the board and tells you where it is.**
180
+
181
+ Four tabs, because the page answers four questions:
182
+
183
+ - **Overview** — what is waiting on you, agents running, progress, and what
184
+ needs a human (blocked lanes **and** blocked agents); then the agent strip,
185
+ stalest first, each chip carrying its last signal and what it said it would
186
+ do next. Anything a journal could not account for is listed here rather than
187
+ quietly dropped.
173
188
  - **Board** — every ticket in exactly one of ten kanban lanes, strongest verdict
174
- first. Click a card for its initiative, agents, note and spend.
189
+ first. Click a card for its initiative, agents, note, spend, and the files
190
+ that initiative actually has on disk.
175
191
  - **Waiting on you** — the open questions with their recommendations and
176
192
  recorded defaults, above the commands that answer them. The count sits in the
177
193
  tab label, so a pending question survives being on another tab.
@@ -179,9 +195,9 @@ questions:
179
195
  composition bar across input / cache write / cache read / output, and three
180
196
  ranked charts (by model, agent type, ticket) with a tokens/cost toggle.
181
197
 
182
- The same page is written to `.tyran/state/board.html` and refreshed after every
183
- agent, so you can also just open the file. Spend is served rather than embedded
184
- and absent over `file://` — [the board](https://jjanczur.github.io/tyran/board/) says why.
198
+ Spend is served rather than embedded, so it is the one thing missing when you
199
+ open the file directly — [the board](https://jjanczur.github.io/tyran/board/)
200
+ says why, and covers the lanes, the drill-down and answering a question.
185
201
 
186
202
  ## What ships
187
203
 
@@ -215,7 +231,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
215
231
  fires and who invokes it, is in
216
232
  [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
217
233
  themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
218
- it: 1297 unit tests, run with `node --test "tests/**/*.test.mjs"`.
234
+ it: 1306 unit tests, run with `node --test "tests/**/*.test.mjs"`.
219
235
 
220
236
  ## Documentation
221
237
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.20",
3
+ "version": "0.1.21",
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": {
@@ -52,7 +52,7 @@ const CSS = `
52
52
  --hairline:#332e27;--hairline-soft:#26221d;
53
53
  --brass:#a8863c;--brass-bright:#cfae63;--brass-low:#221c11;--brass-edge:#5d4c22;
54
54
  --steel:#7d9ea9;--steel-bright:#9dbcc6;--steel-low:#17242a;--steel-edge:#3a545d;
55
- --clay:#c07a70;--clay-low:#2a1a18;--sage:#88a06a;
55
+ --clay:#c07a70;--clay-bright:#d9998f;--clay-low:#2a1a18;--sage:#88a06a;
56
56
  --display:ui-serif,'Iowan Old Style','Palatino Linotype',Palatino,'Book Antiqua',Georgia,'Times New Roman',serif;
57
57
  --font:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;
58
58
  --mono:ui-monospace,SFMono-Regular,'SF Mono',Menlo,Consolas,'Liberation Mono',monospace;
@@ -97,6 +97,19 @@ h3{font-family:var(--font);color:var(--heading);font-size:.85rem;margin:1.1rem 0
97
97
  .agent .age-fresh{color:var(--sage)}
98
98
  .agent .age-warm{color:var(--brass-bright)}
99
99
  .agent .age-cold{color:var(--clay)}
100
+ /* A dead agent gets the only bold red on the page: three hours of silence is
101
+ a different event from thirty minutes, and it used to share a colour. */
102
+ .agent .age-dead{color:var(--clay-bright);font-weight:700}
103
+
104
+ /* ---- what did not render ---- */
105
+ .damaged{background:var(--bg-raised);border-left:3px solid var(--brass);border-radius:.45rem;padding:.42rem .65rem;margin:.3rem 0;font-family:var(--mono);font-size:.78rem;color:var(--brass-bright)}
106
+ .err{background:var(--bg-raised);border-left:3px solid var(--clay);border-radius:.45rem;padding:.6rem .75rem;color:var(--clay-bright);font-size:.85rem}
107
+
108
+ /* ---- the files an initiative actually has ---- */
109
+ .files{display:flex;flex-direction:column;gap:.2rem;margin-top:.3rem}
110
+ .file{display:flex;gap:.5rem;align-items:baseline;flex-wrap:wrap;font-size:.76rem}
111
+ .file .fname{color:var(--steel-bright);font-family:var(--mono);font-weight:600;min-width:6rem}
112
+ .file code{color:var(--muted);font-size:.72rem;word-break:break-all}
100
113
 
101
114
  /* ---- lanes ---- */
102
115
  .lanes{display:grid;grid-template-columns:repeat(auto-fill,minmax(15rem,1fr));gap:.6rem;align-items:start}
@@ -206,6 +219,7 @@ if (data.schema !== 1) {
206
219
  var lanes = data.lanes || {};
207
220
  var errors = data.errors || [];
208
221
  var cost = null;
222
+ var costError = null;
209
223
 
210
224
  var app = document.getElementById('app');
211
225
  var head = el('div');
@@ -282,10 +296,20 @@ if (data.schema !== 1) {
282
296
  chip.appendChild(el('div', 'name', a.agent + (a.role ? ' · ' + a.role : '')));
283
297
  chip.appendChild(el('div', null, (a.init ? a.init + ' · ' : '') + (a.ticket || 'no ticket') + ' · ' + a.state));
284
298
  if (a.detail) chip.appendChild(el('div', 'note', a.detail));
299
+ // What the agent said it would do next. It has been in board.json since
300
+ // the fold learned to read progress events, and the strip has never
301
+ // shown it — so the chip could say an agent went quiet without saying
302
+ // what it went quiet in the middle of.
303
+ if (a.next) chip.appendChild(el('div', 'note', 'next: ' + a.next));
285
304
  var ageMs = a.last_signal ? Date.now() - Date.parse(a.last_signal) : null;
286
305
  var cls = ageMs === null ? 'age-cold' : ageMs < 600000 ? 'age-fresh' : ageMs < 1800000 ? 'age-warm' : 'age-cold';
287
- var ageText = ageMs === null ? 'no signal' : Math.round(ageMs / 60000) + ' min since last signal';
288
- chip.appendChild(el('div', cls, ageText));
306
+ // Four buckets, not three. The old top bucket was "30 minutes or six
307
+ // hours", which are not the same event: one is a long test run, the
308
+ // other is an agent that is not coming back.
309
+ var ageText = ageMs === null ? 'no signal recorded'
310
+ : ageMs >= 10800000 ? Math.round(ageMs / 3600000) + ' HOURS since last signal — likely dead'
311
+ : Math.round(ageMs / 60000) + ' min since last signal';
312
+ chip.appendChild(el('div', ageMs !== null && ageMs >= 10800000 ? 'age-dead' : cls, ageText));
289
313
  strip.appendChild(chip);
290
314
  });
291
315
  return strip;
@@ -302,11 +326,21 @@ if (data.schema !== 1) {
302
326
  asks.length === 0 ? 'nothing blocked on a decision' : 'answer them on the next tab', asks.length > 0 ? 'lead' : null));
303
327
  ovTiles.appendChild(tile('agents running', String(agents.length), 'across ' + (totals.initiatives || 0) + ' initiative(s)'));
304
328
  ovTiles.appendChild(tile('progress', (totals.percent || 0) + '%', (totals.merged || 0) + ' of ' + (totals.tickets || 0) + ' merged'));
305
- var stuck = laneCount('blocked') + laneCount('changes-requested');
329
+ // Counted by the server, from the lanes AND the agents. Counting lanes here
330
+ // read zero while an agent chip on the same screen said "blocked", because a
331
+ // ticket parked by an override leaves no card in the blocked lane.
332
+ var blockedAgents = agents.filter(function (a) { return a.state === 'blocked'; }).length;
333
+ var stuck = totals.blocked !== undefined ? totals.blocked
334
+ : laneCount('blocked') + laneCount('changes-requested') + blockedAgents;
306
335
  ovTiles.appendChild(tile('needs a human', String(stuck),
307
- laneCount('blocked') + ' blocked · ' + laneCount('changes-requested') + ' changes requested', stuck > 0 ? 'warn' : null));
336
+ laneCount('blocked') + ' blocked · ' + laneCount('changes-requested') + ' changes requested · '
337
+ + blockedAgents + ' agent(s) blocked', stuck > 0 ? 'warn' : null));
308
338
  ov.appendChild(ovTiles);
309
339
  ov.appendChild(el('h2', null, 'Agents'));
340
+ // Named, not implied by the order: the strip is sorted stalest-first by the
341
+ // server, and a reader who does not know that reads the first chip as the
342
+ // newest one.
343
+ if (agents.length > 1) ov.appendChild(el('div', 'hint', 'Stalest first — the agent that has said nothing longest is at the top.'));
310
344
  ov.appendChild(agentStrip());
311
345
  var ovSpend = el('div');
312
346
  ov.appendChild(ovSpend);
@@ -321,6 +355,22 @@ if (data.schema !== 1) {
321
355
  });
322
356
  }
323
357
 
358
+ // The same argument one step down. An initiative whose journal is PARTLY
359
+ // damaged folds to a board with nothing wrong on it — the lost half leaves
360
+ // no trace — so it used to render as an initiative in perfect health.
361
+ var warned = data.warned || [];
362
+ if (warned.length > 0) {
363
+ var warnCount = 0;
364
+ warned.forEach(function (d) { warnCount += d.warnings.length; });
365
+ ov.appendChild(el('h2', null, 'Warnings (' + warnCount + ')'));
366
+ ov.appendChild(el('div', 'hint', 'These initiatives rendered. What follows is what the fold could not account for — a skipped line is missing from every lane above, and a lease released by a non-holder is still open.'));
367
+ warned.forEach(function (d) {
368
+ d.warnings.forEach(function (w) {
369
+ ov.appendChild(el('div', 'damaged', d.name + ': ' + w));
370
+ });
371
+ });
372
+ }
373
+
324
374
  // ---- board ------------------------------------------------------------
325
375
  var bd = panels.board;
326
376
  bd.appendChild(el('div', 'hint', 'Every lane is derived from the journal — moving a ticket means appending an event, never editing this page. Select a card to see what the board knows about it.'));
@@ -347,8 +397,26 @@ if (data.schema !== 1) {
347
397
  if (cost) {
348
398
  var hit = (cost.by_ticket || []).filter(function (r) { return r.ticket === card.id; })[0];
349
399
  if (hit) row('spend', fmtTokens(hit.tokens) + ' tokens · ' + fmtUsd(hit.usd));
400
+ } else if (costError) {
401
+ row('spend', costError);
350
402
  }
351
403
  box.appendChild(dl);
404
+ // The files this initiative ACTUALLY has, listed by the server after an
405
+ // existsSync — never a fixed list of what a well-run initiative ought to
406
+ // contain. Paths, not links: the board serves three URLs and derives a
407
+ // filesystem path from none of them, which is worth more than a click.
408
+ var docs = (data.files || {})[card.init] || [];
409
+ if (docs.length > 0) {
410
+ box.appendChild(el('div', 'dt', 'Files'));
411
+ var list = el('div', 'files');
412
+ docs.forEach(function (f) {
413
+ var line = el('div', 'file');
414
+ line.appendChild(el('span', 'fname', f.name));
415
+ line.appendChild(el('code', null, f.path));
416
+ list.appendChild(line);
417
+ });
418
+ box.appendChild(list);
419
+ }
352
420
  detail.appendChild(box);
353
421
  };
354
422
  Object.keys(lanes).forEach(function (lane) {
@@ -520,11 +588,33 @@ if (data.schema !== 1) {
520
588
  // the operator's home directory — machine-local, different in every clone —
521
589
  // so writing it into board.json would break the byte-exact --check contract
522
590
  // and make two people with one journal disagree.
591
+ // Three different things used to look identical here: an unserved page, a
592
+ // crashed reader, and a rate card that does not parse. All three ended as a
593
+ // silently absent section, so the operator could not tell "there is nothing
594
+ // to show" from "the thing that shows it is broken". The server already
595
+ // builds an error string for the 503 and it was never displayed.
596
+ var showCostFailure = function (why) {
597
+ costError = why;
598
+ clear(spBody);
599
+ spBody.appendChild(el('div', 'err', why));
600
+ };
523
601
  if (typeof fetch === 'function') {
524
602
  fetch('cost.json', { headers: { accept: 'application/json' } })
525
- .then(function (r) { return r.ok ? r.json() : null; })
526
- .then(function (payload) {
527
- if (!payload || payload.schema !== 1 || !payload.transcripts_found) return;
603
+ .then(function (r) {
604
+ return r.json().then(function (body) { return { ok: r.ok, body: body }; });
605
+ })
606
+ .then(function (res) {
607
+ var payload = res.body;
608
+ if (!res.ok) {
609
+ showCostFailure('Spend could not be read: ' + ((payload && payload.error) || 'the server refused the request') + '.');
610
+ return;
611
+ }
612
+ if (!payload || payload.schema !== 1) {
613
+ showCostFailure('Spend was served in a format this page does not know (schema ' +
614
+ ((payload && payload.schema) || 'absent') + ') — regenerate the board with the Tyran that served it.');
615
+ return;
616
+ }
617
+ if (!payload.transcripts_found) return; // genuinely nothing to show
528
618
  cost = payload;
529
619
  renderSpend(spBody, 'tokens');
530
620
  var t = cost.totals || {};
@@ -534,7 +624,12 @@ if (data.schema !== 1) {
534
624
  ovSpend.appendChild(el('h2', null, 'Spend'));
535
625
  ovSpend.appendChild(strip);
536
626
  })
537
- .catch(function () { /* no server: the board is complete without it */ });
627
+ .catch(function () {
628
+ // Over file:// there is no server to ask, which is not a failure —
629
+ // it is the documented shape of this page without one.
630
+ if (String(location.protocol) === 'file:') return;
631
+ showCostFailure('Spend could not be read: the board server did not answer. It is served, never embedded — start it with: npx @jjanczur/tyran board --dir .tyran --serve');
632
+ });
538
633
  }
539
634
 
540
635
  select('overview');
@@ -550,6 +645,39 @@ if (data.schema !== 1) {
550
645
  * bytes of board.json, so the two artefacts can never disagree). The extra
551
646
  * `<` escape is the script-element breakout layer.
552
647
  */
648
+ /**
649
+ * The page for a board that could not be rendered at all.
650
+ *
651
+ * Built through the same JSON channel as the real page rather than by
652
+ * interpolating the message into markup: the text comes from an exception, an
653
+ * exception carries a path, and a path is attacker-adjacent input on a page
654
+ * the operator opens in a browser. `<` on the JSON, `textContent` on the
655
+ * other side, no innerHTML anywhere — the same three rules the board itself
656
+ * follows.
657
+ */
658
+ export function renderBoardError(message) {
659
+ const data = JSON.stringify({ message }).replace(/</g, '\\u003C');
660
+ return (
661
+ '<!doctype html>\n' +
662
+ '<html lang="en"><head><meta charset="utf-8">\n' +
663
+ '<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
664
+ '<title>Tyran board — cannot render</title>\n' +
665
+ `<style>${CSS}</style>\n` +
666
+ '</head><body><main id="app"></main>\n' +
667
+ `<script type="application/json" id="board-error">${data}</script>\n` +
668
+ '<script>\n' +
669
+ 'var d = JSON.parse(document.getElementById("board-error").textContent);\n' +
670
+ 'var app = document.getElementById("app");\n' +
671
+ 'var h = document.createElement("h1"); h.textContent = "The board cannot be rendered";\n' +
672
+ 'var p = document.createElement("p"); p.className = "err"; p.textContent = d.message;\n' +
673
+ 'var n = document.createElement("p");\n' +
674
+ 'n.textContent = "This page does not refresh itself \\u2014 fix the cause above, then reload.";\n' +
675
+ 'app.appendChild(h); app.appendChild(p); app.appendChild(n);\n' +
676
+ '</script>\n' +
677
+ '</body></html>\n'
678
+ );
679
+ }
680
+
553
681
  export function renderBoardHtml(payloadJsonText) {
554
682
  const embedded = payloadJsonText.replace(/</g, '\\u003C');
555
683
  return (
package/scripts/board.mjs CHANGED
@@ -25,7 +25,7 @@
25
25
  */
26
26
  import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
27
27
  import { createServer } from 'node:http';
28
- import { join, resolve } from 'node:path';
28
+ import { basename, join, resolve } from 'node:path';
29
29
  import { realpathSync } from 'node:fs';
30
30
  import { fileURLToPath } from 'node:url';
31
31
  import { readJournal } from './journal.mjs';
@@ -37,10 +37,11 @@ import {
37
37
  checkFile,
38
38
  fold,
39
39
  inline,
40
+ warnings,
40
41
  writeAllAtomic,
41
42
  } from './project.mjs';
42
43
  import { jsonEscapeInvisible } from './invisible.mjs';
43
- import { renderBoardHtml } from './board-html.mjs';
44
+ import { renderBoardError, renderBoardHtml } from './board-html.mjs';
44
45
  import { COST_SCHEMA, costJson, costReport } from './cost.mjs';
45
46
 
46
47
  export const BOARD_HTML_FILE = 'board.html';
@@ -80,11 +81,21 @@ export function readInitiativeBoards(tyranDir) {
80
81
  }
81
82
  const initiatives = [];
82
83
  const errors = [];
84
+ const warned = [];
83
85
  for (const name of dirs) {
84
86
  const journal = join(stateDir, name, 'journal.jsonl');
85
87
  if (!existsSync(journal)) continue;
86
88
  try {
87
89
  const state = fold(readJournal(journal));
90
+ // PARTIAL damage, which the guard below cannot see. That guard fires only
91
+ // when NOTHING was readable; three good tickets plus one unparseable line
92
+ // folds to a board with no errors on it and renders as an initiative in
93
+ // perfect health. `warnings()` has produced exactly the right sentences
94
+ // for this since the projection layer existed — the board simply never
95
+ // asked for them. A page whose stated reason to exist is not saying "all
96
+ // is well" when it is not cannot be silent about the damaged half.
97
+ const flaws = warnings(state);
98
+ if (flaws.length > 0) warned.push({ name, warnings: flaws });
88
99
  // `readJournal` does NOT throw on unparseable content — it returns zero
89
100
  // events and counts the damage — so the catch below never sees a corrupt
90
101
  // journal. Without this guard a damaged file renders as an initiative
@@ -102,36 +113,74 @@ export function readInitiativeBoards(tyranDir) {
102
113
  // `journal` is returned, not re-derived by consumers: answer.mjs writes
103
114
  // to the file this function already located, so there is one rule for
104
115
  // where an initiative's journal lives (ADR-21).
105
- initiatives.push({ name, journal, state, board: boardOf(state) });
116
+ initiatives.push({ name, journal, state, board: boardOf(state), files: initiativeFiles(tyranDir, name) });
106
117
  } catch (err) {
107
118
  errors.push({ name, error: String(err?.message ?? err) });
108
119
  }
109
120
  }
110
- return { initiatives, errors };
121
+ return { initiatives, errors, warned };
122
+ }
123
+
124
+ /**
125
+ * The files an initiative ACTUALLY has beside its journal.
126
+ *
127
+ * Named set, `existsSync`, no creation and no guessing: the operator asked to
128
+ * reach an agent's plan from the board and asked in the same breath that
129
+ * nothing be created to satisfy the link. A listed file that is not there is
130
+ * the same lie as a missing one, in the other direction.
131
+ *
132
+ * The recorded path is REPO-RELATIVE, and that is not cosmetic: `board.json`
133
+ * is a committed, byte-compared artefact, so an absolute path would make two
134
+ * clones of one journal disagree and fail `--check` on a machine whose home
135
+ * directory is spelled differently. It is the same reason spend is served
136
+ * rather than embedded. Relative is also the more useful form — it is what
137
+ * the reader pastes, from the repo root, into an editor.
138
+ *
139
+ * Nothing is served: `--serve` routes three URLs and derives a filesystem
140
+ * path from none of them, which is worth more than a clickable link.
141
+ */
142
+ export const INITIATIVE_FILES = Object.freeze(['PLAN.md', 'NOTES.md', 'RETRO.md', 'STATE.md', 'PROGRESS.md']);
143
+
144
+ export function initiativeFiles(tyranDir, name) {
145
+ const dir = join(tyranDir, 'state', name);
146
+ const shown = join(basename(resolve(tyranDir)), 'state', name);
147
+ return INITIATIVE_FILES.filter((file) => existsSync(join(dir, file))).map((file) => ({
148
+ name: file,
149
+ path: join(shown, file),
150
+ }));
111
151
  }
112
152
 
113
153
  /** Pure merge of per-initiative boards into the one payload. */
114
- export function crossBoard({ initiatives, errors }) {
154
+ export function crossBoard({ initiatives, errors, warned = [] }) {
115
155
  const asks = [];
116
156
  const agents = [];
117
157
  const paused = [];
158
+ const files = {};
118
159
  const lanes = Object.fromEntries(LANES.map((lane) => [lane, []]));
119
160
  let merged = 0;
120
161
  let tickets = 0;
121
162
  let asOf = null;
122
163
 
123
- for (const { name, state, board } of initiatives) {
164
+ for (const { name, state, board, files: docs } of initiatives) {
124
165
  merged += state.merged;
125
166
  tickets += state.ticketList.length;
126
167
  if (state.lastTs !== null && (asOf === null || state.lastTs > asOf)) asOf = state.lastTs;
127
168
  for (const a of board.asks) asks.push({ ...a, init: name });
128
169
  for (const a of board.agents) agents.push({ ...a, init: name });
129
170
  if (board.paused !== null) paused.push({ ...board.paused, init: name });
171
+ if (docs !== undefined && docs.length > 0) files[name] = docs;
130
172
  for (const lane of LANES) {
131
173
  for (const card of board.lanes.get(lane)) lanes[lane].push({ ...card, init: name });
132
174
  }
133
175
  }
134
176
  asks.sort((a, b) => String(a.since ?? '').localeCompare(String(b.since ?? '')));
177
+ // Stalest FIRST. Rendering agents in the order the journals happened to spawn
178
+ // them puts the one that has said nothing for six hours anywhere at all,
179
+ // including last — and the whole reason the strip carries a last-signal time
180
+ // is that the silent agent is the one worth looking at. `last_signal` is an
181
+ // ISO string from the journal, so ascending string order IS ascending time;
182
+ // an agent with no signal at all sorts to the front, where it belongs.
183
+ agents.sort((a, b) => String(a.last_signal ?? '').localeCompare(String(b.last_signal ?? '')));
135
184
 
136
185
  return {
137
186
  schema: 1,
@@ -142,12 +191,21 @@ export function crossBoard({ initiatives, errors }) {
142
191
  merged,
143
192
  tickets,
144
193
  percent: tickets === 0 ? 0 : Math.round((merged / tickets) * 100),
194
+ // Counted here rather than on the page, from BOTH sources of "a human is
195
+ // needed": the lanes, and the agents. A ticket parked by a `ticket.status`
196
+ // override leaves no card in `blocked` — the override is resolved before
197
+ // the blockage in `boardOf` — so an agent could sit blocked on it while a
198
+ // tile counting lanes alone read zero. It did.
199
+ blocked: lanes.blocked.length + lanes['changes-requested'].length
200
+ + agents.filter((a) => a.state === 'blocked').length,
145
201
  },
146
202
  paused,
147
203
  asks,
148
204
  agents,
205
+ files,
149
206
  lanes,
150
207
  errors,
208
+ warned,
151
209
  };
152
210
  }
153
211
 
@@ -168,6 +226,9 @@ export function renderCrossMd(payload) {
168
226
  for (const e of payload.errors) {
169
227
  parts.push(`\n**UNREADABLE** — ${inline(e.name)}: ${inline(e.error)}\n`);
170
228
  }
229
+ for (const d of payload.warned ?? []) {
230
+ for (const w of d.warnings) parts.push(`\n**WARNING** — ${inline(d.name)}: ${inline(w)}\n`);
231
+ }
171
232
 
172
233
  parts.push('\n## Waiting on you\n\n');
173
234
  if (payload.asks.length === 0) parts.push('_none — the agents have what they need_\n');
@@ -184,10 +245,19 @@ export function renderCrossMd(payload) {
184
245
  parts.push(
185
246
  `- \`${inline(a.agent)}\` (${inline(a.role)}) — ${inline(a.init)}` +
186
247
  `${a.ticket != null ? ` · \`${inline(a.ticket)}\`` : ''} · ${inline(a.state)}` +
187
- `${a.detail != null ? ` — ${inline(a.detail)}` : ''} · last signal ${inline(a.last_signal)}\n`,
248
+ `${a.detail != null ? ` — ${inline(a.detail)}` : ''} · last signal ${inline(a.last_signal)}` +
249
+ `${a.next != null ? ` · next: ${inline(a.next)}` : ''}\n`,
188
250
  );
189
251
  }
190
252
 
253
+ const withFiles = Object.keys(payload.files ?? {}).sort();
254
+ if (withFiles.length > 0) {
255
+ parts.push('\n## Files\n\n');
256
+ for (const name of withFiles) {
257
+ parts.push(`- ${inline(name)}: ${payload.files[name].map((f) => `\`${inline(f.name)}\``).join(', ')}\n`);
258
+ }
259
+ }
260
+
191
261
  for (const lane of LANES) {
192
262
  const cards = payload.lanes[lane];
193
263
  parts.push(`\n## ${lane} (${cards.length})\n\n`);
@@ -318,8 +388,14 @@ function main() {
318
388
  res.end('not found\n');
319
389
  }
320
390
  } catch (err) {
321
- res.writeHead(500, { 'content-type': 'text/plain' });
322
- res.end(`board render failed: ${String(err?.message ?? err)}\n`);
391
+ // Readable, and 200 on purpose. The page refreshes itself every 30
392
+ // seconds, so a plain-text 500 becomes a browser tab re-fetching an
393
+ // error nobody can act on twice a minute. The state that reaches here
394
+ // is real and fixable — over the initiative ceiling, an unreadable
395
+ // state directory — and the operator needs the sentence, not a status
396
+ // code they will never see.
397
+ res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
398
+ res.end(renderBoardError(String(err?.message ?? err)));
323
399
  }
324
400
  });
325
401
  // A busy port is an ordinary operator mistake, not a crash worth a stack