@jjanczur/tyran 0.1.20 → 0.1.22

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.22",
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.22",
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,151 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.22 — 2026-08-15
4
+
5
+ ### A sandbox board you can click, published with the docs
6
+
7
+ A screenshot cannot be clicked and a GIF cannot be paused, so the docs now
8
+ publish the **real page** at
9
+ [jjanczur.github.io/tyran/sandbox/](https://jjanczur.github.io/tyran/sandbox/)
10
+ — rendered by the same `scripts/board.mjs` an operator runs, from two invented
11
+ initiatives committed under `site/sandbox/`. Click the tabs, filter the lanes,
12
+ select a card.
13
+
14
+ Two things a static copy has to solve, and both are solved in the generator
15
+ rather than by hand. **Ages**: the agent strip is aged in the reader's browser
16
+ against event timestamps, so a frozen page would read as a graveyard within a
17
+ month — every timestamp is shifted at build time so the newest event lands six
18
+ minutes before the build, with the original spacing intact. **Honesty**: the
19
+ 30-second refresh is stripped (it would also snap a reader back to the first
20
+ tab mid-click) and a banner says what the page is. Both replacements throw if
21
+ their anchor moves, because a silent no-op there publishes a page that claims
22
+ to be someone's live board.
23
+
24
+ ### The board, for someone who left it running overnight
25
+
26
+ - **The queue count is in the browser tab title.** The page is meant to be left
27
+ open while agents work; a background tab was saying nothing at all, because
28
+ the count existed only on a tab you had to be looking at.
29
+ - **"Changed since you marked seen."** The board is a snapshot and the journal
30
+ is a timeline: coming back to ten lanes meant re-reading all of them to find
31
+ the two that moved. Press **Mark seen** and the next visit names how many
32
+ tickets changed lane, badges each one, and says in the detail panel which
33
+ lane it came from. The baseline moves only on that press — never on load,
34
+ because the page reloads itself every 30 seconds and an auto-updating
35
+ baseline would make "since you last looked" mean "in the last half minute",
36
+ which is the same as showing nothing.
37
+ - **A filter over the lanes**, matching ticket id, title and initiative. Ten
38
+ lanes across dozens of initiatives is a pile; the lane headings keep their
39
+ counts as `n of N`, so a filtered zero still reads as a fact rather than an
40
+ absence.
41
+ - **A merged ticket names who did it.** The card's agent list empties the
42
+ moment an agent reports, so every `done` card showed nobody — and "who
43
+ touched this" is a question asked about finished work, not running work. The
44
+ fold has kept the list since spawns learned to name a ticket; only the board
45
+ dropped it. `worked_by` is deduplicated and naturally ordered, because
46
+ `board.json` is compared byte for byte and spawn order is not an order.
47
+ - **Nothing-started no longer looks like nothing-finished.** A fresh
48
+ initiative and a fully stalled one both rendered `0% · 0 of 0 merged`.
49
+ - **A 404 on spend is an answer, not a failure.** No such route means the page
50
+ is not being served by the board server — a copy on a docs site, a file
51
+ behind some other host — and it now says so calmly, while a 503 stays loud.
52
+
53
+ ### The client script is now proved to parse
54
+
55
+ Every other assertion about the page matches strings in the rendered HTML,
56
+ which a page that cannot run would satisfy just as well. The whole client is
57
+ one template literal, so a backtick inside a **comment** terminates it and the
58
+ module stops loading — which is exactly how this was found, by a comment that
59
+ quoted an identifier. The suite now compiles the emitted script.
60
+
61
+ ### Documentation
62
+
63
+ The GIF is larger (1180px), and under it, in the README and on both doc
64
+ surfaces, a link to the sandbox. `docs/board.md`'s **Opening it** section is
65
+ the one place that says how to open the dashboard: the serve command and the
66
+ URL it prints, the `open`/`xdg-open`/`start` line for the file, what differs
67
+ between them, and that `/tyran:status` does it for you inside a session.
68
+
69
+ `CLAUDE.md` now specifies `npm run build` for the site rather than
70
+ `npx astro build` — the sandbox is generated first, and calling astro directly
71
+ publishes a site whose sandbox link 404s.
72
+
73
+ ## 0.1.21 — 2026-08-14
74
+
75
+ ### The board said "all is well" in five different ways it should not have
76
+
77
+ An audit read the page against its own promise — that it never shows a healthy
78
+ board over an unhealthy repo — and it failed that promise five times.
79
+
80
+ **A partially damaged journal rendered as a healthy initiative.** The existing
81
+ guard fires only when NOTHING was readable. Three good tickets plus one
82
+ unparseable line folded to a board with `errors: []` on it, and the lost line
83
+ left no mark anywhere. `project.mjs` has produced exactly the right sentences
84
+ for this since the projection layer existed — `board.mjs` had simply never
85
+ asked for them. It asks now, and the page carries a **Warnings** section
86
+ naming the initiative and what could not be accounted for: a skipped line, a
87
+ lease released by a non-holder, an override for a ticket that does not exist.
88
+ The likelier damage is the partial kind, because a crash mid-write takes the
89
+ tail, not the file.
90
+
91
+ **"Needs a human" counted lanes, not humans.** A ticket parked by a
92
+ `ticket.status` override leaves no card in the `blocked` lane — `boardOf`
93
+ resolves the override before the blockage — so an agent could sit blocked on
94
+ that ticket while the tile read **0**. Measured on the shipped fixture: the
95
+ tile now reads 2 where it read 0, and both are agents rather than lanes. It
96
+ counts from both sources, on the server, and the sub-label breaks out which is
97
+ which.
98
+
99
+ **Staleness was shown and never escalated.** Agents rendered in the order the
100
+ journals spawned them, so the one that had said nothing longest could be last.
101
+ They are now sorted stalest-first, said so above the strip, and three hours of
102
+ silence gets its own bucket and its own red — "468 HOURS since last signal —
103
+ likely dead" is not the same event as thirty minutes, and the two used to
104
+ share a colour. Each chip also carries **what the agent said it would do
105
+ next**, which has been in `board.json` since the fold learned to read
106
+ `progress` events and had never been rendered.
107
+
108
+ **A spend failure was indistinguishable from having no server.** A crashed
109
+ reader, an unparseable rate card and a page opened over `file://` all ended as
110
+ the same silently missing section — and the server had already built the
111
+ sentence that tells them apart, for a 503 nothing displayed. Each now says
112
+ which it was; `file://` still says nothing, because there it is not a failure.
113
+
114
+ **Over the initiative ceiling, the served page was a plain-text 500 that the
115
+ page's own 30-second refresh re-fetched twice a minute.** It is now a readable
116
+ page that names the cause and does not reload itself. The CLI still refuses
117
+ loudly with exit 2 — that is right when a human is reading exit codes.
118
+
119
+ ### The drill-down reaches the files an initiative actually has
120
+
121
+ Selecting a card now lists that initiative's `PLAN.md`, `NOTES.md`, `RETRO.md`,
122
+ `STATE.md` and `PROGRESS.md` — **the ones that exist**, checked with
123
+ `existsSync`, never a list of what a well-run initiative ought to contain and
124
+ never created to satisfy a link.
125
+
126
+ The recorded path is repo-relative, and that is not cosmetic. `board.json` is
127
+ committed and compared byte for byte, so an absolute path would make two
128
+ clones of one journal disagree and fail `--check` on any machine whose home
129
+ directory is spelled differently — the same reason spend is served rather than
130
+ embedded. It was nearly shipped absolute; there is now a test that fails on
131
+ any `"path"` starting at the filesystem root.
132
+
133
+ Nothing is served: `--serve` still answers exactly three URLs and derives a
134
+ filesystem path from none of them, which is worth more than a clickable link.
135
+
136
+ ### How to open the dashboard, said once, plainly
137
+
138
+ `docs/board.md` gains an **Opening it** section, mirrored on the site: the
139
+ serve command and the URL it prints, the `open`/`xdg-open`/`start` line for
140
+ the file, what the difference between them is (spend, and only spend), and the
141
+ fact that inside a session you type neither, because `/tyran:status`
142
+ regenerates the board and tells you where it is. The README says the same in
143
+ three lines instead of implying it.
144
+
145
+ Verified in a browser against a two-initiative tree, one of whose journals was
146
+ deliberately corrupted: 0 console errors, 0 failed requests, the tile at 2,
147
+ three warnings listed, the file rows repo-relative.
148
+
3
149
  ## 0.1.20 — 2026-08-14
4
150
 
5
151
  ### `.tyran/` was tracked, and an entire initiative inside it was not
@@ -75,6 +221,27 @@ narrower advice each time.
75
221
  - **The dashboard GIF runs at 4 fps instead of 8.3** — the same recording, at a
76
222
  speed a tab can actually be read at.
77
223
 
224
+ ### The dist-tag is earned, not inherited from the last run
225
+
226
+ Creating GitHub Releases for sixteen historical tags in one batch fired
227
+ `npm-publish.yml` sixteen times. The workflow's safety argument was that npm
228
+ refuses a version that already exists — true, and too small: **npm refusing a
229
+ DUPLICATE version is not npm refusing an OLD one.** Four of those versions had
230
+ never reached npm, so they published cleanly and each took the `latest`
231
+ dist-tag on the way past. For roughly a minute `npm i @jjanczur/tyran` served
232
+ **0.1.2**. Found within two minutes, by checking the registry rather than the
233
+ sixteen green workflow runs, and self-corrected when 0.1.20's own publish
234
+ landed last.
235
+
236
+ The workflow now asks the registry which version is highest and publishes
237
+ `--tag latest` only when the version in hand IS that one; anything older
238
+ gets `--tag historical` and moves nothing. The comparison is `sort -V`, not
239
+ string order — `0.1.9` sorts above `0.1.10` alphabetically, which would have
240
+ mis-tagged every 0.1.x release past the ninth.
241
+
242
+ Side effect, kept: 0.1.1, 0.1.2, 0.1.15 and 0.1.16 are now on npm, so the
243
+ registry finally carries every released version.
244
+
78
245
  ## 0.1.19 — 2026-08-14
79
246
 
80
247
  ### The board answered four questions on one scroll
package/README.md CHANGED
@@ -27,30 +27,49 @@ plan is somewhere in the scrollback, and *"the tests pass"* is a sentence
27
27
  rather than something you can check. Start a new session and you start
28
28
  explaining from the beginning.
29
29
 
30
- Tyran is a plugin that moves the work off the chat window. You describe a task;
31
- it interviews you until the goal is unambiguous, sizes it, and drives
32
- **fresh-context subagents** through it — a scout that only reads, an
33
- implementer per story on its own branch, a reviewer holding no editing tools so
34
- it cannot patch what it is grading. Every decision, spawn, report, merge and
35
- open question is appended to a journal **committed to your repo**, and every
36
- file you read afterwards is generated from that journal. A restart, a
37
- compaction and a colleague on another branch all read the same thing.
38
-
39
- Two rules are what make that worth the trouble. A report containing no raw
40
- command output is **rejected by a hook**, not by good intentions. And every
41
- write is classified against a policy file you own **before it happens**, so
42
- *autonomous* is a setting with a blast radius rather than a promise.
43
-
44
- ![The Tyran dashboard, recorded live, moving through its four tabs: Overview with what is waiting on you and the strip of running agents each showing the time since it last signalled; Board, where selecting a ticket opens its initiative, agents and spend; Waiting on you, the open questions above the commands that answer them; and Spend, toggling the same split between tokens and cost](assets/board-demo.gif)
30
+ Tyran is an orchestrator. You describe a task; it interviews you until the goal
31
+ is unambiguous, sizes it, plans it, and hands each piece to a **dedicated
32
+ subagent with fresh context and a model tier matched to how hard that piece
33
+ actually is** — cheap for a mechanical sweep, expensive for a security
34
+ boundary, never one model for a whole session. They run in parallel, as an
35
+ Agent Team where the platform offers one.
36
+
37
+ That is a cost lever and a quality lever at the same time. The conductor holds
38
+ the plan and never accumulates its agents' transcripts, which is where the
39
+ tokens in a long session actually go; and an agent that never saw the last six
40
+ failed attempts cannot inherit them, so the second opinion is a real one.
41
+
42
+ **It learns your repo while it works.** Setup reads how the repo is really
43
+ worked — stack, validation commands, how things get deployed — rather than
44
+ asking you to describe it. A retrospective after every initiative writes what
45
+ it learnt into `.tyran/knowledge/`, and a failure that repeats graduates out of
46
+ `MISTAKES.md` into a rule. Meanwhile every decision, spawn, report, merge and
47
+ open question is appended to a journal **committed to your repo**, so a
48
+ restart, a compaction and a colleague on another branch all read the same
49
+ thing.
50
+
51
+ All of it is one plugin, and it comes with a **dashboard**: what every agent is
52
+ doing right now, which questions are waiting on you, and what the work cost —
53
+ in the tokens the platform itself reported, per model, per agent and per
54
+ ticket.
55
+
56
+ Underneath, **deterministic hooks hold the line**: a report with no raw command
57
+ output is rejected, every write is classified against a policy file you own
58
+ before it happens, and a commit carrying a secret is refused. Mechanisms rather
59
+ than instructions — which is the whole argument.
60
+
61
+ <p align="center">
62
+ <img src="assets/board-demo.gif" width="100%" alt="The Tyran dashboard, recorded live, moving through its four tabs: Overview with what is waiting on you and the strip of running agents each showing the time since it last signalled; Board, where selecting a ticket opens its initiative, agents and spend; Waiting on you, the open questions above the commands that answer them; and Spend, toggling the same split between tokens and cost">
63
+ </p>
64
+
65
+ <p align="center">
66
+ <b><a href="https://jjanczur.github.io/tyran/sandbox/">▶ Open the sandbox board</a></b> —
67
+ the real page with sample data, in your browser. Click the tabs, filter the
68
+ lanes, select a card.
69
+ </p>
45
70
 
46
71
  ## What it gives you
47
72
 
48
- - **A model tier per role, resolved from one config file.** Model names appear
49
- in exactly one place; skills, agents and policies are written in role names.
50
- The expensive tier is kept for security review, arbitration and final
51
- acceptance, and the first two sit on a floor no profile or risk flag crosses.
52
- - **Fresh context for every subagent.** Handoffs are self-contained, so the
53
- conductor holds the plan and never accumulates its agents' transcripts.
54
73
  - **Reports that carry evidence, or are refused.** A `SubagentStop` hook
55
74
  rejects a report with no raw command output — measured on 55 real reports
56
75
  from this project's own agents: 53 pass, and both misses were not reports. It
@@ -59,9 +78,11 @@ write is classified against a policy file you own **before it happens**, so
59
78
  - **State you can read without a session.** The journal is the single source of
60
79
  truth; `STATE.md`, `PROGRESS.md`, `BOARD.md`, `board.json` and `board.html`
61
80
  are generated projections of it.
62
- - **A retrospective after every initiative.** It writes durable facts about
63
- your repo into `.tyran/knowledge/`, and repeated failures graduate out of
64
- `MISTAKES.md` into rules.
81
+ - **The routing table is one file.** Model names appear in exactly one place;
82
+ skills, agents and policies are written in role names, so a deprecation is a
83
+ one-line edit. The expensive tier is reserved for security review,
84
+ arbitration and final acceptance, and those two sit on a floor no cost
85
+ profile or risk flag can cross.
65
86
  - **A spend ledger.** `npx @jjanczur/tyran cost` reports what the work cost, in
66
87
  the tokens the platform itself reported, per model, per agent type and per
67
88
  ticket — read out of the transcripts Claude Code already writes. Money
@@ -162,16 +183,32 @@ echo "wrong branch — hold everything" > .tyran/STOP
162
183
  npx @jjanczur/tyran board --dir .tyran --serve
163
184
  ```
164
185
 
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:
186
+ It prints `board: serving http://127.0.0.1:4173/` — **open that URL.** The
187
+ board is read-only, bound to loopback, re-rendered on every request, and it
188
+ reloads itself every 30 seconds; `--port <n>` if 4173 is taken, `Ctrl-C` to
189
+ stop. That command is the one place a Node version matters, because `npx` runs
190
+ the scripts outside Claude Code and they need **Node ≥ 22**.
191
+
192
+ No terminal, no server: the same page is written to **`.tyran/state/board.html`**
193
+ after every agent, so you can just open the file —
194
+
195
+ ```bash
196
+ open .tyran/state/board.html # xdg-open on Linux, start on Windows
197
+ ```
198
+
199
+ — and inside a session you need neither command, because **`/tyran:status`
200
+ regenerates the board and tells you where it is.**
201
+
202
+ Four tabs, because the page answers four questions:
169
203
 
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.
204
+ - **Overview** — what is waiting on you, agents running, progress, and what
205
+ needs a human (blocked lanes **and** blocked agents); then the agent strip,
206
+ stalest first, each chip carrying its last signal and what it said it would
207
+ do next. Anything a journal could not account for is listed here rather than
208
+ quietly dropped.
173
209
  - **Board** — every ticket in exactly one of ten kanban lanes, strongest verdict
174
- first. Click a card for its initiative, agents, note and spend.
210
+ first. Click a card for its initiative, agents, note, spend, and the files
211
+ that initiative actually has on disk.
175
212
  - **Waiting on you** — the open questions with their recommendations and
176
213
  recorded defaults, above the commands that answer them. The count sits in the
177
214
  tab label, so a pending question survives being on another tab.
@@ -179,9 +216,9 @@ questions:
179
216
  composition bar across input / cache write / cache read / output, and three
180
217
  ranked charts (by model, agent type, ticket) with a tokens/cost toggle.
181
218
 
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.
219
+ Spend is served rather than embedded, so it is the one thing missing when you
220
+ open the file directly — [the board](https://jjanczur.github.io/tyran/board/)
221
+ says why, and covers the lanes, the drill-down and answering a question.
185
222
 
186
223
  ## What ships
187
224
 
@@ -215,7 +252,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
215
252
  fires and who invokes it, is in
216
253
  [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
217
254
  themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
218
- it: 1297 unit tests, run with `node --test "tests/**/*.test.mjs"`.
255
+ it: 1313 unit tests, run with `node --test "tests/**/*.test.mjs"`.
219
256
 
220
257
  ## Documentation
221
258
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.20",
3
+ "version": "0.1.22",
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,30 @@ 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
+ /* ---- what moved while you were away ---- */
109
+ .moved{background:var(--brass-low);border:1px solid var(--brass-edge);border-radius:var(--radius);padding:.5rem .75rem;margin:.6rem 0;display:flex;gap:.6rem;align-items:center;flex-wrap:wrap;color:var(--brass-bright);font-size:.85rem}
110
+ .markseen{background:var(--bg-raised);color:var(--text);border:1px solid var(--hairline);border-radius:.4rem;padding:.25rem .6rem;font:inherit;font-size:.78rem;cursor:pointer}
111
+ .markseen:hover{border-color:var(--brass-edge);color:var(--brass-bright)}
112
+ .card .movedtag{display:inline-block;background:var(--brass-low);color:var(--brass-bright);border:1px solid var(--brass-edge);border-radius:.3rem;padding:0 .3rem;font-size:.65rem;margin-left:.3rem;letter-spacing:.04em}
113
+
114
+ /* ---- filter ---- */
115
+ .filter{display:flex;gap:.6rem;align-items:center;margin:.5rem 0 .7rem}
116
+ .filter input{background:var(--bg-sunken);color:var(--text);border:1px solid var(--hairline);border-radius:.4rem;padding:.35rem .6rem;font:inherit;font-size:.82rem;min-width:20rem;max-width:100%}
117
+ .filter input:focus{outline:none;border-color:var(--steel-edge)}
118
+
119
+ /* ---- the files an initiative actually has ---- */
120
+ .files{display:flex;flex-direction:column;gap:.2rem;margin-top:.3rem}
121
+ .file{display:flex;gap:.5rem;align-items:baseline;flex-wrap:wrap;font-size:.76rem}
122
+ .file .fname{color:var(--steel-bright);font-family:var(--mono);font-weight:600;min-width:6rem}
123
+ .file code{color:var(--muted);font-size:.72rem;word-break:break-all}
100
124
 
101
125
  /* ---- lanes ---- */
102
126
  .lanes{display:grid;grid-template-columns:repeat(auto-fill,minmax(15rem,1fr));gap:.6rem;align-items:start}
@@ -206,6 +230,55 @@ if (data.schema !== 1) {
206
230
  var lanes = data.lanes || {};
207
231
  var errors = data.errors || [];
208
232
  var cost = null;
233
+ var costError = null;
234
+
235
+ // The queue count, in the browser tab. The whole point of this page is that
236
+ // you can leave it open while agents work overnight, and a background tab
237
+ // was saying nothing at all — the count existed only on a tab you had to be
238
+ // looking at to see.
239
+ try {
240
+ document.title = (asks.length > 0 ? '(' + asks.length + ') ' : '') + 'Tyran board';
241
+ } catch (e) { /* a title is a nicety; never let it take the page down */ }
242
+
243
+ // ---- what moved since you last acknowledged it ------------------------
244
+ //
245
+ // The page is a snapshot; the journal is a timeline. Someone who leaves
246
+ // agents running overnight comes back to ten lanes and has to re-read all
247
+ // of them to find the two that moved.
248
+ //
249
+ // The baseline is only replaced when the operator presses "Mark seen" —
250
+ // deliberately NOT on load, because the page reloads itself every 30
251
+ // seconds and an auto-updating baseline would mean "since you last looked"
252
+ // was always "since half a minute ago", which is the same as nothing.
253
+ // localStorage can throw outright (Safari over file://, a private window),
254
+ // so every access degrades to "no baseline" rather than to a broken page.
255
+ var SEEN_KEY = 'tyran-board-seen-v1';
256
+ var laneOfCard = {};
257
+ Object.keys(lanes).forEach(function (lane) {
258
+ (lanes[lane] || []).forEach(function (c) { laneOfCard[(c.init || '') + '/' + c.id] = lane; });
259
+ });
260
+ var readSeen = function () {
261
+ try {
262
+ var raw = localStorage.getItem(SEEN_KEY);
263
+ return raw ? JSON.parse(raw) : null;
264
+ } catch (e) { return null; }
265
+ };
266
+ var writeSeen = function () {
267
+ try {
268
+ localStorage.setItem(SEEN_KEY, JSON.stringify({ at: new Date().toISOString(), cards: laneOfCard }));
269
+ return true;
270
+ } catch (e) { return false; }
271
+ };
272
+ var seen = readSeen();
273
+ var moved = {};
274
+ var movedCount = 0;
275
+ if (seen && seen.cards) {
276
+ Object.keys(laneOfCard).forEach(function (key) {
277
+ var was = seen.cards[key];
278
+ if (was === undefined) { moved[key] = 'new'; movedCount += 1; }
279
+ else if (was !== laneOfCard[key]) { moved[key] = was; movedCount += 1; }
280
+ });
281
+ }
209
282
 
210
283
  var app = document.getElementById('app');
211
284
  var head = el('div');
@@ -282,10 +355,20 @@ if (data.schema !== 1) {
282
355
  chip.appendChild(el('div', 'name', a.agent + (a.role ? ' · ' + a.role : '')));
283
356
  chip.appendChild(el('div', null, (a.init ? a.init + ' · ' : '') + (a.ticket || 'no ticket') + ' · ' + a.state));
284
357
  if (a.detail) chip.appendChild(el('div', 'note', a.detail));
358
+ // What the agent said it would do next. It has been in board.json since
359
+ // the fold learned to read progress events, and the strip has never
360
+ // shown it — so the chip could say an agent went quiet without saying
361
+ // what it went quiet in the middle of.
362
+ if (a.next) chip.appendChild(el('div', 'note', 'next: ' + a.next));
285
363
  var ageMs = a.last_signal ? Date.now() - Date.parse(a.last_signal) : null;
286
364
  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));
365
+ // Four buckets, not three. The old top bucket was "30 minutes or six
366
+ // hours", which are not the same event: one is a long test run, the
367
+ // other is an agent that is not coming back.
368
+ var ageText = ageMs === null ? 'no signal recorded'
369
+ : ageMs >= 10800000 ? Math.round(ageMs / 3600000) + ' HOURS since last signal — likely dead'
370
+ : Math.round(ageMs / 60000) + ' min since last signal';
371
+ chip.appendChild(el('div', ageMs !== null && ageMs >= 10800000 ? 'age-dead' : cls, ageText));
289
372
  strip.appendChild(chip);
290
373
  });
291
374
  return strip;
@@ -301,12 +384,54 @@ if (data.schema !== 1) {
301
384
  ovTiles.appendChild(tile('waiting on you', String(asks.length),
302
385
  asks.length === 0 ? 'nothing blocked on a decision' : 'answer them on the next tab', asks.length > 0 ? 'lead' : null));
303
386
  ovTiles.appendChild(tile('agents running', String(agents.length), 'across ' + (totals.initiatives || 0) + ' initiative(s)'));
304
- ovTiles.appendChild(tile('progress', (totals.percent || 0) + '%', (totals.merged || 0) + ' of ' + (totals.tickets || 0) + ' merged'));
305
- var stuck = laneCount('blocked') + laneCount('changes-requested');
387
+ // An initiative with no tickets used to read "0% · 0 of 0 merged", which is
388
+ // exactly what a fully stalled one reads. Nothing-started and
389
+ // nothing-finished are different situations and deserve different words.
390
+ ovTiles.appendChild((totals.tickets || 0) === 0
391
+ ? tile('progress', '—', (totals.initiatives || 0) === 0
392
+ ? 'no initiatives yet — run /tyran to start one'
393
+ : 'no tickets declared yet')
394
+ : tile('progress', (totals.percent || 0) + '%', (totals.merged || 0) + ' of ' + totals.tickets + ' merged'));
395
+ // Counted by the server, from the lanes AND the agents. Counting lanes here
396
+ // read zero while an agent chip on the same screen said "blocked", because a
397
+ // ticket parked by an override leaves no card in the blocked lane.
398
+ var blockedAgents = agents.filter(function (a) { return a.state === 'blocked'; }).length;
399
+ var stuck = totals.blocked !== undefined ? totals.blocked
400
+ : laneCount('blocked') + laneCount('changes-requested') + blockedAgents;
306
401
  ovTiles.appendChild(tile('needs a human', String(stuck),
307
- laneCount('blocked') + ' blocked · ' + laneCount('changes-requested') + ' changes requested', stuck > 0 ? 'warn' : null));
402
+ laneCount('blocked') + ' blocked · ' + laneCount('changes-requested') + ' changes requested · '
403
+ + blockedAgents + ' agent(s) blocked', stuck > 0 ? 'warn' : null));
308
404
  ov.appendChild(ovTiles);
405
+
406
+ // The bar only appears once there IS a baseline: on a first visit nothing
407
+ // has "changed", and saying so would be noise on the one screen that is
408
+ // supposed to be only signal.
409
+ if (seen) {
410
+ var since = el('div', movedCount > 0 ? 'moved' : 'hint');
411
+ since.appendChild(el('span', null, movedCount > 0
412
+ ? movedCount + ' ticket(s) changed lane since you marked seen (' + seen.at + ')'
413
+ : 'Nothing has moved since you marked seen (' + seen.at + ').'));
414
+ var mark = el('button', 'markseen', 'Mark seen');
415
+ mark.addEventListener('click', function () {
416
+ if (writeSeen()) location.reload();
417
+ else since.appendChild(el('span', 'note', ' — this browser refused to store it'));
418
+ });
419
+ since.appendChild(mark);
420
+ ov.appendChild(since);
421
+ } else {
422
+ var first = el('div', 'hint');
423
+ first.appendChild(el('span', null, 'Mark this board seen and the next visit will tell you what moved while you were away.'));
424
+ var firstBtn = el('button', 'markseen', 'Mark seen');
425
+ firstBtn.addEventListener('click', function () { if (writeSeen()) location.reload(); });
426
+ first.appendChild(firstBtn);
427
+ ov.appendChild(first);
428
+ }
429
+
309
430
  ov.appendChild(el('h2', null, 'Agents'));
431
+ // Named, not implied by the order: the strip is sorted stalest-first by the
432
+ // server, and a reader who does not know that reads the first chip as the
433
+ // newest one.
434
+ if (agents.length > 1) ov.appendChild(el('div', 'hint', 'Stalest first — the agent that has said nothing longest is at the top.'));
310
435
  ov.appendChild(agentStrip());
311
436
  var ovSpend = el('div');
312
437
  ov.appendChild(ovSpend);
@@ -321,6 +446,22 @@ if (data.schema !== 1) {
321
446
  });
322
447
  }
323
448
 
449
+ // The same argument one step down. An initiative whose journal is PARTLY
450
+ // damaged folds to a board with nothing wrong on it — the lost half leaves
451
+ // no trace — so it used to render as an initiative in perfect health.
452
+ var warned = data.warned || [];
453
+ if (warned.length > 0) {
454
+ var warnCount = 0;
455
+ warned.forEach(function (d) { warnCount += d.warnings.length; });
456
+ ov.appendChild(el('h2', null, 'Warnings (' + warnCount + ')'));
457
+ 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.'));
458
+ warned.forEach(function (d) {
459
+ d.warnings.forEach(function (w) {
460
+ ov.appendChild(el('div', 'damaged', d.name + ': ' + w));
461
+ });
462
+ });
463
+ }
464
+
324
465
  // ---- board ------------------------------------------------------------
325
466
  var bd = panels.board;
326
467
  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.'));
@@ -341,24 +482,66 @@ if (data.schema !== 1) {
341
482
  dl.appendChild(el('dd', null, v));
342
483
  };
343
484
  row('lane', lane);
485
+ var was = moved[(card.init || '') + '/' + card.id];
486
+ if (was) row('since you marked seen', was === 'new' ? 'new ticket' : 'moved out of ' + was);
344
487
  row('initiative', card.init);
345
488
  row('agents', card.agents && card.agents.length ? card.agents.join(', ') : null);
489
+ // Who ever held it, which is the question people ask about a ticket that
490
+ // is already done — precisely when the running-agents list is empty.
491
+ row('worked by', card.worked_by && card.worked_by.length ? card.worked_by.join(', ') : null);
346
492
  row('note', card.annotation);
347
493
  if (cost) {
348
494
  var hit = (cost.by_ticket || []).filter(function (r) { return r.ticket === card.id; })[0];
349
495
  if (hit) row('spend', fmtTokens(hit.tokens) + ' tokens · ' + fmtUsd(hit.usd));
496
+ } else if (costError) {
497
+ row('spend', costError);
350
498
  }
351
499
  box.appendChild(dl);
500
+ // The files this initiative ACTUALLY has, listed by the server after an
501
+ // existsSync — never a fixed list of what a well-run initiative ought to
502
+ // contain. Paths, not links: the board serves three URLs and derives a
503
+ // filesystem path from none of them, which is worth more than a click.
504
+ var docs = (data.files || {})[card.init] || [];
505
+ if (docs.length > 0) {
506
+ box.appendChild(el('div', 'dt', 'Files'));
507
+ var list = el('div', 'files');
508
+ docs.forEach(function (f) {
509
+ var line = el('div', 'file');
510
+ line.appendChild(el('span', 'fname', f.name));
511
+ line.appendChild(el('code', null, f.path));
512
+ list.appendChild(line);
513
+ });
514
+ box.appendChild(list);
515
+ }
352
516
  detail.appendChild(box);
353
517
  };
518
+ // A filter, because ten lanes across dozens of initiatives is a pile.
519
+ // Substring over the id, the title and the initiative — no query language,
520
+ // nothing to learn, and it never hides a lane HEADING, so "0" after
521
+ // filtering still reads as a fact about the lane rather than as an
522
+ // absence.
523
+ var filterRow = el('div', 'filter');
524
+ var filterInput = el('input');
525
+ filterInput.setAttribute('type', 'search');
526
+ filterInput.setAttribute('placeholder', 'filter by ticket, title or initiative');
527
+ filterInput.setAttribute('aria-label', 'filter tickets');
528
+ var filterCount = el('span', 'note');
529
+ filterRow.appendChild(filterInput);
530
+ filterRow.appendChild(filterCount);
531
+ bd.appendChild(filterRow);
532
+
533
+ var allCards = [];
354
534
  Object.keys(lanes).forEach(function (lane) {
355
535
  var cards = lanes[lane];
356
536
  var box = el('div', 'lane ' + lane);
357
537
  var h = el('h4');
358
538
  h.appendChild(el('span', null, lane));
359
- h.appendChild(el('span', 'count', ' (' + cards.length + ')'));
539
+ var count = el('span', 'count', ' (' + cards.length + ')');
540
+ h.appendChild(count);
360
541
  box.appendChild(h);
361
- if (cards.length === 0) box.appendChild(el('div', 'empty', '—'));
542
+ var emptyMark = el('div', 'empty', '—');
543
+ if (cards.length === 0) box.appendChild(emptyMark);
544
+ var buttons = [];
362
545
  cards.forEach(function (c) {
363
546
  var button = el('button', 'card');
364
547
  button.setAttribute('type', 'button');
@@ -366,13 +549,36 @@ if (data.schema !== 1) {
366
549
  button.appendChild(el('span', 'id', c.id));
367
550
  if (c.title) button.appendChild(el('span', null, ' — ' + c.title));
368
551
  if (c.init) button.appendChild(el('span', 'init', ' ' + c.init));
552
+ // The badge is the whole point of the baseline: it puts what moved in
553
+ // front of you instead of asking you to compare ten lanes by eye.
554
+ if (moved[(c.init || '') + '/' + c.id]) button.appendChild(el('span', 'movedtag', 'moved'));
369
555
  if (c.agents && c.agents.length) button.appendChild(el('span', 'note', 'agents: ' + c.agents.join(', ')));
370
556
  if (c.annotation) button.appendChild(el('span', 'note', c.annotation));
371
557
  button.addEventListener('click', function () { showDetail(c, lane, button); });
372
558
  box.appendChild(button);
559
+ buttons.push(button);
560
+ allCards.push({ card: c, button: button, hay: ((c.id || '') + ' ' + (c.title || '') + ' ' + (c.init || '')).toLowerCase() });
373
561
  });
374
562
  lanesWrap.appendChild(box);
563
+ box.tyranApply = function (q) {
564
+ var shown = 0;
565
+ buttons.forEach(function (b, i) {
566
+ var hit = q === '' || ((cards[i].id || '') + ' ' + (cards[i].title || '') + ' ' + (cards[i].init || '')).toLowerCase().indexOf(q) !== -1;
567
+ b.style.display = hit ? '' : 'none';
568
+ if (hit) shown += 1;
569
+ });
570
+ count.textContent = q === '' ? ' (' + cards.length + ')' : ' (' + shown + ' of ' + cards.length + ')';
571
+ emptyMark.style.display = shown === 0 && cards.length > 0 ? '' : (cards.length === 0 ? '' : 'none');
572
+ return shown;
573
+ };
375
574
  });
575
+ var applyFilter = function () {
576
+ var q = filterInput.value.trim().toLowerCase();
577
+ var shown = 0;
578
+ [].forEach.call(lanesWrap.children, function (box) { shown += box.tyranApply(q); });
579
+ filterCount.textContent = q === '' ? '' : shown + ' of ' + allCards.length + ' ticket(s)';
580
+ };
581
+ filterInput.addEventListener('input', applyFilter);
376
582
  bd.appendChild(lanesWrap);
377
583
  bd.appendChild(detail);
378
584
 
@@ -520,11 +726,42 @@ if (data.schema !== 1) {
520
726
  // the operator's home directory — machine-local, different in every clone —
521
727
  // so writing it into board.json would break the byte-exact --check contract
522
728
  // and make two people with one journal disagree.
729
+ // Three different things used to look identical here: an unserved page, a
730
+ // crashed reader, and a rate card that does not parse. All three ended as a
731
+ // silently absent section, so the operator could not tell "there is nothing
732
+ // to show" from "the thing that shows it is broken". The server already
733
+ // builds an error string for the 503 and it was never displayed.
734
+ var showCostFailure = function (why) {
735
+ costError = why;
736
+ clear(spBody);
737
+ spBody.appendChild(el('div', 'err', why));
738
+ };
523
739
  if (typeof fetch === 'function') {
524
740
  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;
741
+ .then(function (r) {
742
+ // 404 is not a failure, it is an ANSWER: no such route, so this page
743
+ // is not being served by the board server — a copy on a docs site, a
744
+ // file behind some other static host. Distinct from a 503, which
745
+ // means the reader ran and could not finish.
746
+ if (r.status === 404) return { absent: true };
747
+ return r.json().then(function (body) { return { ok: r.ok, body: body }; });
748
+ })
749
+ .then(function (res) {
750
+ if (res.absent) {
751
+ showCostFailure('Spend is not served on this page. Run the board against your own repo to see it: npx @jjanczur/tyran board --dir .tyran --serve');
752
+ return;
753
+ }
754
+ var payload = res.body;
755
+ if (!res.ok) {
756
+ showCostFailure('Spend could not be read: ' + ((payload && payload.error) || 'the server refused the request') + '.');
757
+ return;
758
+ }
759
+ if (!payload || payload.schema !== 1) {
760
+ showCostFailure('Spend was served in a format this page does not know (schema ' +
761
+ ((payload && payload.schema) || 'absent') + ') — regenerate the board with the Tyran that served it.');
762
+ return;
763
+ }
764
+ if (!payload.transcripts_found) return; // genuinely nothing to show
528
765
  cost = payload;
529
766
  renderSpend(spBody, 'tokens');
530
767
  var t = cost.totals || {};
@@ -534,7 +771,12 @@ if (data.schema !== 1) {
534
771
  ovSpend.appendChild(el('h2', null, 'Spend'));
535
772
  ovSpend.appendChild(strip);
536
773
  })
537
- .catch(function () { /* no server: the board is complete without it */ });
774
+ .catch(function () {
775
+ // Over file:// there is no server to ask, which is not a failure —
776
+ // it is the documented shape of this page without one.
777
+ if (String(location.protocol) === 'file:') return;
778
+ 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');
779
+ });
538
780
  }
539
781
 
540
782
  select('overview');
@@ -550,6 +792,39 @@ if (data.schema !== 1) {
550
792
  * bytes of board.json, so the two artefacts can never disagree). The extra
551
793
  * `<` escape is the script-element breakout layer.
552
794
  */
795
+ /**
796
+ * The page for a board that could not be rendered at all.
797
+ *
798
+ * Built through the same JSON channel as the real page rather than by
799
+ * interpolating the message into markup: the text comes from an exception, an
800
+ * exception carries a path, and a path is attacker-adjacent input on a page
801
+ * the operator opens in a browser. `<` on the JSON, `textContent` on the
802
+ * other side, no innerHTML anywhere — the same three rules the board itself
803
+ * follows.
804
+ */
805
+ export function renderBoardError(message) {
806
+ const data = JSON.stringify({ message }).replace(/</g, '\\u003C');
807
+ return (
808
+ '<!doctype html>\n' +
809
+ '<html lang="en"><head><meta charset="utf-8">\n' +
810
+ '<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
811
+ '<title>Tyran board — cannot render</title>\n' +
812
+ `<style>${CSS}</style>\n` +
813
+ '</head><body><main id="app"></main>\n' +
814
+ `<script type="application/json" id="board-error">${data}</script>\n` +
815
+ '<script>\n' +
816
+ 'var d = JSON.parse(document.getElementById("board-error").textContent);\n' +
817
+ 'var app = document.getElementById("app");\n' +
818
+ 'var h = document.createElement("h1"); h.textContent = "The board cannot be rendered";\n' +
819
+ 'var p = document.createElement("p"); p.className = "err"; p.textContent = d.message;\n' +
820
+ 'var n = document.createElement("p");\n' +
821
+ 'n.textContent = "This page does not refresh itself \\u2014 fix the cause above, then reload.";\n' +
822
+ 'app.appendChild(h); app.appendChild(p); app.appendChild(n);\n' +
823
+ '</script>\n' +
824
+ '</body></html>\n'
825
+ );
826
+ }
827
+
553
828
  export function renderBoardHtml(payloadJsonText) {
554
829
  const embedded = payloadJsonText.replace(/</g, '\\u003C');
555
830
  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
@@ -171,6 +171,13 @@ export function naturalCompare(a, b) {
171
171
  }
172
172
 
173
173
  /** Stable sort by a natural key; ties keep their original (journal) order. */
174
+ /** Deduplicated and naturally ordered — a board.json array is compared byte
175
+ * for byte, so "the order the journal happened to spawn them in" is not a
176
+ * property this can rest on. */
177
+ function sortedUnique(values) {
178
+ return [...new Set(values)].sort(naturalCompare);
179
+ }
180
+
174
181
  function sortByKey(items, keyOf) {
175
182
  return items
176
183
  .map((item, i) => [item, i])
@@ -695,6 +702,13 @@ export function boardOf(state) {
695
702
  id: t.id,
696
703
  title: t.title,
697
704
  agents: runningByTicket.get(t.id) ?? [],
705
+ // Everyone who ever held it, not only whoever holds it now. `agents`
706
+ // empties the moment an agent reports, so a merged ticket carried no
707
+ // trace of who did the work — and "who touched this" is a question
708
+ // people ask about FINISHED tickets, never about running ones. The fold
709
+ // has kept the list since spawns learned to name a ticket; only the
710
+ // board dropped it.
711
+ worked_by: sortedUnique(t.agents),
698
712
  since: t.lastTs,
699
713
  annotation: annotations.length > 0 ? annotations.join(' · ') : null,
700
714
  });