@jjanczur/tyran 0.1.19 → 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.19",
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.19",
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,177 @@
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
+
79
+ ## 0.1.20 — 2026-08-14
80
+
81
+ ### `.tyran/` was tracked, and an entire initiative inside it was not
82
+
83
+ `untrackedTyranDir` was all-or-nothing: one tracked file anywhere under
84
+ `.tyran/` and the whole directory reported healthy. Measured on a real install
85
+ whose `.tyran/` had been tracked for weeks — one initiative directory of six
86
+ files, its plan and the gate event recording two production database migrations
87
+ among them, had NEVER been committed, and a second was 33 events behind its
88
+ committed copy. Both passed. `journal.mjs append` writes the working tree and
89
+ nothing else, so an initiative nobody committed is one `git clean -fd` from
90
+ having never happened.
91
+
92
+ `doctor --state` now reads each initiative's ledger separately, in three states
93
+ rather than two:
94
+
95
+ - `initiative-untracked` (**warning**) — git has never seen it.
96
+ - `initiative-ignored` (**warning**) — a `.gitignore` rule covers it. Split out
97
+ because `git add` on an ignored path exits 0 and stages nothing, so the
98
+ untracked fix would have read as success while changing nothing.
99
+ - `initiative-uncommitted` (**info**, never fails the check) — tracked with
100
+ local changes, which is what an initiative in flight looks like ten seconds
101
+ after any append. It earns its keep at a merge boundary.
102
+
103
+ Two git invocations for the whole tree, not two per initiative: both listings
104
+ are read once and classified by path prefix in JS, so a repo with forty
105
+ initiatives costs the same three subprocesses as one with a single initiative
106
+ — and a test counts them, because that regression passes every behavioural
107
+ test there is. Under a wholly untracked `.tyran/` the directory-level finding
108
+ still reports alone rather than repeating itself once per initiative with
109
+ narrower advice each time.
110
+
111
+ ### Four things the conductor skill was letting agents rediscover
112
+
113
+ - **Interactive shell aliases hang an agent until the tool timeout.** An
114
+ agent's shell starts from the user's profile, so `alias cp='cp -i'` asks a
115
+ question nobody answers. The symptom is a timeout, which points at the
116
+ machine rather than at the alias, so it gets rediscovered every time: three
117
+ agents in one session, then again in a later one that had already read the
118
+ file it is now written in. STEP 0 probes for it.
119
+ - **A `Test timed out` measured under concurrency is not evidence.** The
120
+ hardware ceiling bounds agent count, not concurrent heavy phases. Re-run
121
+ serially and report the serial result. One overnight test failed exactly
122
+ that way inside the full suite while this release was being verified, and
123
+ passed alone.
124
+ - **An agent that dies on a terminal API error is resumed, not respawned** —
125
+ its context, its corrected premises and its uncommitted diff all survive.
126
+ - **Gitignored env files are absent from a fresh worktree too, and fail
127
+ quieter than dependencies**: 127 is loud, a skipped gated spec is not, so the
128
+ worktree reports a *cleaner* baseline than the repo has.
129
+
130
+ ### The README says what Tyran is, and the docs it links are the published ones
131
+
132
+ - **"What Tyran is" rewritten** to open on the failure a reader recognises — a
133
+ full context window, a plan somewhere in the scrollback, "the tests pass" as
134
+ a sentence rather than a result — before naming the mechanism that answers
135
+ it.
136
+ - **The named comparison is back on the front page.** Five rows of the eleven
137
+ in the FAQ, copied verbatim, plus a test that fails if a verdict moves in one
138
+ and not the other. The `Skills · agents it ships` row and the guard pinning
139
+ it were deleted rather than updated: the table under it and the sentence
140
+ under that already carry the same count, and three spellings of one answer is
141
+ the defect this repo calls ADR-21 — a test can hold one in place as easily as
142
+ prose can.
143
+ - **Every documentation link now points at the published site** rather than at
144
+ a markdown file: twenty in the README, three inside skills, and four in
145
+ `doctor`'s own fix lines — which reach repos that have no `docs/` directory
146
+ at all, where `see docs/journal.md` was a dead reference.
147
+ - **The Node version is stated once, where it applies.** It sat in the lede and
148
+ in the install section, neither of which runs Node: the scripts ship with the
149
+ plugin and Claude Code runs them. It now sits beside the one command that
150
+ needs it, `npx @jjanczur/tyran board`.
151
+ - **The dashboard GIF runs at 4 fps instead of 8.3** — the same recording, at a
152
+ speed a tab can actually be read at.
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
+
3
175
  ## 0.1.19 — 2026-08-14
4
176
 
5
177
  ### The board answered four questions on one scroll
package/README.md CHANGED
@@ -22,12 +22,24 @@
22
22
 
23
23
  ## What Tyran is
24
24
 
25
- Tyran is a Claude Code plugin that runs a task as a **team of agents instead of
26
- one long chat**. You describe the work; it interviews you briefly, plans, and
27
- drives fresh-context subagents through it. Execution state lives in an
28
- append-only journal committed to your repo rather than in the session window, so
29
- a restart, a compaction and a colleague on another branch read the same thing.
30
- Zero runtime dependencies, no build step, Node ≥ 22.
25
+ Every long Claude Code session ends the same way. The context fills up, the
26
+ plan is somewhere in the scrollback, and *"the tests pass"* is a sentence
27
+ rather than something you can check. Start a new session and you start
28
+ explaining from the beginning.
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.
31
43
 
32
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)
33
45
 
@@ -42,7 +54,7 @@ Zero runtime dependencies, no build step, Node ≥ 22.
42
54
  - **Reports that carry evidence, or are refused.** A `SubagentStop` hook
43
55
  rejects a report with no raw command output — measured on 55 real reports
44
56
  from this project's own agents: 53 pass, and both misses were not reports. It
45
- blocks silence, not forgery; [the evidence gate](docs/evidence-gate.md) is
57
+ blocks silence, not forgery; [the evidence gate](https://jjanczur.github.io/tyran/evidence-gate/) is
46
58
  precise about the difference.
47
59
  - **State you can read without a session.** The journal is the single source of
48
60
  truth; `STATE.md`, `PROGRESS.md`, `BOARD.md`, `board.json` and `board.html`
@@ -61,12 +73,12 @@ Zero runtime dependencies, no build step, Node ≥ 22.
61
73
  resume and stops — then a watcher wakes at the window reset and continues the
62
74
  same session. Leave it working and read the board in the morning. Both
63
75
  windows were hit live while the feature was being built; the protocol that
64
- survived them is what shipped. See [overnight mode](docs/overnight.md).
76
+ survived them is what shipped. See [overnight mode](https://jjanczur.github.io/tyran/overnight/).
65
77
 
66
- ## Tyran compared
78
+ ## Tyran vs. an ordinary session
67
79
 
68
- The axis, not the winner. These rows compare against an ordinary agent session
69
- — a comparison that can be made without guessing at another tool's internals.
80
+ The axis, not the winner — a comparison that can be made without guessing at
81
+ anyone's internals.
70
82
 
71
83
  | | An ordinary agent session | Tyran |
72
84
  |---|---|---|
@@ -75,15 +87,33 @@ The axis, not the winner. These rows compare against an ordinary agent session
75
87
  | Which model does which job | one model for the whole session | four tiers resolved from `.tyran/config.yaml`, per role, with a floor under the judgements everything downstream trusts |
76
88
  | What happens after the work | nothing | a retrospective writes what this repo taught it back into this repo |
77
89
  | What it adds to your install | — | zero runtime dependencies, no build step |
78
- | Skills · agents it ships | — | 14 · 4 |
90
+
91
+ ## Tyran vs. other Claude Code orchestrators
92
+
93
+ Five rows of eleven, verified against those projects' **code and public issue
94
+ trackers** (July 2026) rather than their READMEs. ✅ shipped and enforced ·
95
+ ⚠️ partial or prompt-only · ❌ absent or broken · 🎯 committed in the design,
96
+ ships test-gated.
97
+
98
+ | Capability | **Tyran** | oh-my-claudecode | metaswarm | pilotfish | pro-workflow |
99
+ |---|:---:|:---:|:---:|:---:|:---:|
100
+ | Evidence contract that **blocks**: no raw command output → report rejected | ✅ | ⚠️ advisory¹ | ⚠️ prompt | ⚠️ prompt | ❌ |
101
+ | Execution state survives restart & compaction (journal + re-inject) | ✅ | ⚠️ | ❌² | ❌ | ⚠️ |
102
+ | Plugin update **never** destroys local learning (3 layers + delta agent) | 🎯 | ❌³ | — | — | ⚠️ |
103
+ | Secret gate on commit/push with verified scan coverage, no `--no-verify` escape | ✅ | ❌ | ❌ | ❌ | ⚠️ |
104
+ | Clean install: 2 commands, **never writes into your `~/.claude`** | ✅ | ❌³ | ⚠️ | ❌ | ⚠️ |
105
+
106
+ ¹ Their deliverable check is explicitly non-blocking. ² Their issues
107
+ #32/#33/#36: a crash loses loop state. ³ Open issues #3535/#3536: an update
108
+ deletes user files from `~/.claude`. The other six rows — repo-specific
109
+ learning, cost tiers, independent review, context budget, safe parallelism, OSS
110
+ hygiene — and every footnote in full are in
111
+ [the FAQ](https://jjanczur.github.io/tyran/faq/#how-tyran-compares-to-other-claude-code-orchestrators).
79
112
 
80
113
  Worth knowing before tuning anything: cache reads were measured at roughly
81
114
  three quarters of a real session's cost, and the conductor's own context at
82
115
  between 44% and 86% of a tree's tokens — so the lever is context size and turn
83
- count, not the price of a model. A cell-by-cell comparison against four other
84
- Claude Code orchestrators, verified against their code and public issue
85
- trackers, is in
86
- [the FAQ](docs/faq.md#how-tyran-compares-to-other-claude-code-orchestrators).
116
+ count, not the price of a model.
87
117
 
88
118
  ## Install
89
119
 
@@ -97,11 +127,13 @@ Inside Claude Code:
97
127
 
98
128
  Restart Claude Code afterwards — hooks and agents are read when a session
99
129
  starts, so an install you have not restarted into is an install you are not
100
- running. `/tyran:hello` is the smoke test. Requirements: Claude Code ≥ 2.1;
101
- Tyran's scripts are plain Node ≥ 22 and ship with the plugin, so you never run
102
- npm. `/plugin` is a slash command a human has to type — the prompt that has
103
- Claude Code install itself, the npm package for a shell or a CI job, updating
104
- and uninstalling are all in [getting started](docs/getting-started.md).
130
+ running. `/tyran:hello` is the smoke test. The only requirement is **Claude
131
+ Code ≥ 2.1**: the scripts ship with the plugin and Claude Code runs them, so
132
+ there is nothing to install and no version of anything else to match.
133
+ `/plugin` is a slash command a human has to type — the prompt that has Claude
134
+ Code install itself, the npm package for a shell or a CI job, updating and
135
+ uninstalling are all in
136
+ [getting started](https://jjanczur.github.io/tyran/getting-started/).
105
137
 
106
138
  ## Use it
107
139
 
@@ -130,14 +162,32 @@ echo "wrong branch — hold everything" > .tyran/STOP
130
162
  npx @jjanczur/tyran board --dir .tyran --serve
131
163
  ```
132
164
 
133
- A read-only board on loopback, re-rendered on every request. Four tabs, because
134
- the page answers four questions:
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:
135
182
 
136
- - **Overview** — what is waiting on you, agents running, progress, tickets that
137
- need a human; then the agent strip, each chip carrying the time since that
138
- agent last signalled.
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.
139
188
  - **Board** — every ticket in exactly one of ten kanban lanes, strongest verdict
140
- 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.
141
191
  - **Waiting on you** — the open questions with their recommendations and
142
192
  recorded defaults, above the commands that answer them. The count sits in the
143
193
  tab label, so a pending question survives being on another tab.
@@ -145,9 +195,9 @@ the page answers four questions:
145
195
  composition bar across input / cache write / cache read / output, and three
146
196
  ranked charts (by model, agent type, ticket) with a tokens/cost toggle.
147
197
 
148
- The same page is written to `.tyran/state/board.html` and refreshed after every
149
- agent, so you can also just open the file. Spend is served rather than embedded
150
- and absent over `file://` — [the board](docs/board.md) 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.
151
201
 
152
202
  ## What ships
153
203
 
@@ -157,29 +207,31 @@ repo, initiative or not — and the other eight are standalone protocols.
157
207
 
158
208
  | Skill | What it does |
159
209
  |---|---|
160
- | [`run`](skills/run/SKILL.md) | the conductor — interviews, sizes, plans, delegates, merges |
161
- | [`setup`](skills/setup/SKILL.md) | reads the repo and writes `.tyran/config.yaml`, provenance per value |
162
- | [`status`](skills/status/SKILL.md) | where an initiative got to, from the journal rather than from memory |
163
- | [`doctor`](skills/doctor/SKILL.md) | is any gate installed but unable to fire; is the state self-consistent |
164
- | [`retro`](skills/retro/SKILL.md) | the anti-bloat curator that changes Tyran, never your product code |
165
- | [`hello`](skills/hello/SKILL.md) | proves the plugin is installed and its paths resolve |
166
- | [`code-review`](skills/code-review/SKILL.md) | the dimensions a diff is read against, and the rule that you refute a finding before reporting it |
167
- | [`root-cause`](skills/root-cause/SKILL.md) | reproduce first, one variable per experiment, exit by naming the mechanism |
168
- | [`browser-check`](skills/browser-check/SKILL.md) | a UI pass that returns counts — console errors, failed responses, computed styles |
169
- | [`deslop`](skills/deslop/SKILL.md) | the optimization pass: delete before you add, behaviour pinned by a test that ran first |
170
- | [`pr-feedback`](skills/pr-feedback/SKILL.md) | all three of GitHub's comment surfaces, a disposition for every comment |
171
- | [`fidelity-gate`](skills/fidelity-gate/SKILL.md) | build 1:1 against a frozen mockup, measured rather than eyeballed |
172
- | [`prompt-tuning`](skills/prompt-tuning/SKILL.md) | tune a non-deterministic output without chasing noise — noise baseline first |
173
- | [`skill-writing`](skills/skill-writing/SKILL.md) | what a skill has to earn before it ships, and the test that proves it fires |
210
+ | `run` | the conductor — interviews, sizes, plans, delegates, merges |
211
+ | `setup` | reads the repo and writes `.tyran/config.yaml`, provenance per value |
212
+ | `status` | where an initiative got to, from the journal rather than from memory |
213
+ | `doctor` | is any gate installed but unable to fire; is the state self-consistent |
214
+ | `retro` | the anti-bloat curator that changes Tyran, never your product code |
215
+ | `hello` | proves the plugin is installed and its paths resolve |
216
+ | `code-review` | the dimensions a diff is read against, and the rule that you refute a finding before reporting it |
217
+ | `root-cause` | reproduce first, one variable per experiment, exit by naming the mechanism |
218
+ | `browser-check` | a UI pass that returns counts — console errors, failed responses, computed styles |
219
+ | `deslop` | the optimization pass: delete before you add, behaviour pinned by a test that ran first |
220
+ | `pr-feedback` | all three of GitHub's comment surfaces, a disposition for every comment |
221
+ | `fidelity-gate` | build 1:1 against a frozen mockup, measured rather than eyeballed |
222
+ | `prompt-tuning` | tune a non-deterministic output without chasing noise — noise baseline first |
223
+ | `skill-writing` | what a skill has to earn before it ships, and the test that proves it fires |
174
224
 
175
225
  Agents: `tyran:scout` (recon, read-only), `tyran:implementer` (one story, own
176
226
  branch), `tyran:reviewer` (no editing tools — it cannot patch what it is
177
227
  grading), `tyran:retro`. A skill is admitted only when something already asks
178
228
  for the protocol by name, and every description is loaded into every session
179
229
  whether the skill fires or not — so the combined length is capped and CI
180
- enforces the cap (4352 of 5000 characters). What each one assumes, and who
181
- invokes it, is in [skills and agents](docs/skills.md). Behind all of it: 1289
182
- unit tests, run with `node --test "tests/**/*.test.mjs"`.
230
+ enforces the cap (4352 of 5000 characters). What each one assumes, when it
231
+ fires and who invokes it, is in
232
+ [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
233
+ themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
234
+ it: 1306 unit tests, run with `node --test "tests/**/*.test.mjs"`.
183
235
 
184
236
  ## Documentation
185
237
 
@@ -188,16 +240,16 @@ Everything below also reads as a site, with search and rendered diagrams:
188
240
 
189
241
  | | |
190
242
  |---|---|
191
- | [Getting started](docs/getting-started.md) | install, first run, the command line, updating |
192
- | [Architecture](docs/architecture.md) | the four failures, the three layers, the hooks, the principles, the roadmap |
193
- | [Skills and agents](docs/skills.md) · [the roster](docs/agents.md) | what each one assumes and who invokes it; the tier and effort table, the `.tyran/STOP` brake |
194
- | [Configuration](docs/configuration.md) | `.tyran/config.yaml`, cost profiles, the rate card, autonomy classes |
195
- | [Self-improvement](docs/self-improvement.md) | how Tyran learns your repo, and its guardrails |
196
- | [Journal](docs/journal.md) · [projections](docs/projections.md) | the append-only event schema, and what is generated from it |
197
- | [The board](docs/board.md) · [the spend ledger](docs/cost.md) | lanes, answering a question, and what a run cost |
198
- | [Overnight mode](docs/overnight.md) · [doctor](docs/doctor.md) | usage-limit pause and scheduled resume; the `--state` and `--hooks` checks |
199
- | [Hook runtime](docs/hooks.md) · [evidence gate](docs/evidence-gate.md) · [policy gate](docs/policy-gate.md) | gates versus probes and why hooks fail open; the criterion and its limits; path classes and where each stops |
200
- | [FAQ](docs/faq.md) | short answers, the comparison table, and where this came from |
243
+ | [Getting started](https://jjanczur.github.io/tyran/getting-started/) | install, first run, the command line, updating |
244
+ | [Architecture](https://jjanczur.github.io/tyran/architecture/) | the four failures, the three layers, the hooks, the principles, the roadmap |
245
+ | [Skills and agents](https://jjanczur.github.io/tyran/skills/) · [the roster](https://jjanczur.github.io/tyran/agents/) | what each one assumes and who invokes it; the tier and effort table, the `.tyran/STOP` brake |
246
+ | [Configuration](https://jjanczur.github.io/tyran/configuration/) | `.tyran/config.yaml`, cost profiles, the rate card, autonomy classes |
247
+ | [Self-improvement](https://jjanczur.github.io/tyran/self-improvement/) | how Tyran learns your repo, and its guardrails |
248
+ | [Journal](https://jjanczur.github.io/tyran/journal/) · [projections](https://jjanczur.github.io/tyran/projections/) | the append-only event schema, and what is generated from it |
249
+ | [The board](https://jjanczur.github.io/tyran/board/) · [the spend ledger](https://jjanczur.github.io/tyran/cost/) | lanes, answering a question, and what a run cost |
250
+ | [Overnight mode](https://jjanczur.github.io/tyran/overnight/) · [doctor](https://jjanczur.github.io/tyran/doctor/) | usage-limit pause and scheduled resume; the `--state` and `--hooks` checks |
251
+ | [Hook runtime](https://jjanczur.github.io/tyran/hooks/) · [evidence gate](https://jjanczur.github.io/tyran/evidence-gate/) · [policy gate](https://jjanczur.github.io/tyran/policy-gate/) | gates versus probes and why hooks fail open; the criterion and its limits; path classes and where each stops |
252
+ | [FAQ](https://jjanczur.github.io/tyran/faq/) | short answers, the comparison table, and where this came from |
201
253
  | [Contributing](CONTRIBUTING.md) | the dev loop, the test commands, the enforced rules |
202
254
 
203
255
  ## License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.19",
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
@@ -206,6 +206,12 @@ export const SEVERITY_BY_CODE = Object.freeze(
206
206
  'state-stray-file': 'warning',
207
207
  'state-legacy-initiatives-dir': 'warning',
208
208
  'lease-file-tracked': 'warning',
209
+ // the ledger in git. `uncommitted` is INFO on purpose: every append
210
+ // produces that state within seconds, and a warning that is on during
211
+ // normal operation is a warning people learn to scroll past.
212
+ 'initiative-untracked': 'warning',
213
+ 'initiative-ignored': 'warning',
214
+ 'initiative-uncommitted': 'info',
209
215
  // the mistakes ledger. `mistakes-unreadable` is a WARNING, not the `error`
210
216
  // that `knowledge-unreadable` and `config-unreadable` carry: nothing
211
217
  // mechanical consumes MISTAKES.md at write time, so an unreadable one
@@ -1162,6 +1168,98 @@ export function untrackedTyranDir(repoRoot, run, tyranDirName = '.tyran') {
1162
1168
  return run(['ls-files', '--', tyranDirName]).trim() === '';
1163
1169
  }
1164
1170
 
1171
+ /**
1172
+ * Which initiative ledgers git has never seen, and which carry local changes.
1173
+ *
1174
+ * `untrackedTyranDir` above is all-or-nothing: one tracked file anywhere under
1175
+ * `.tyran/` and the whole directory reports healthy. That is the wrong
1176
+ * granularity for what iron rule 1 actually asks for. Measured on a real
1177
+ * install whose `.tyran/` had been tracked for weeks: one initiative directory
1178
+ * of six files — its plan, and the gate event recording two production
1179
+ * database migrations — had NEVER been committed, and a second was 33 events
1180
+ * behind its committed copy. The directory-level check passed on both.
1181
+ * `journal.mjs append` writes the working tree and nothing else, so an
1182
+ * initiative nobody committed is one `git clean -fd` from having never
1183
+ * happened.
1184
+ *
1185
+ * Three states, because the same loss needs three different sentences:
1186
+ *
1187
+ * - `untracked` — git has never seen this ledger. Wrong at any moment.
1188
+ * - `ignored` — a rule in some `.gitignore` covers it. The same loss, but
1189
+ * `git add` on a path git is ignoring is a SILENT no-op, so the advice the
1190
+ * untracked case gives would look like it worked and change nothing.
1191
+ * - `uncommitted` — tracked, with local changes. What an initiative in
1192
+ * flight looks like ten seconds after any append, so it is worth saying
1193
+ * only at a merge boundary, and never worth failing a check over.
1194
+ *
1195
+ * Two git invocations for the whole tree rather than two per initiative: the
1196
+ * listings are read once and classified by path prefix in JS. A repo can hold
1197
+ * dozens of initiatives and this runs behind the SessionStart deadline. The
1198
+ * prefix is built in git's own output convention (repo-relative, forward
1199
+ * slashes) for the same reason `trackedLeaseFiles` filters in JS instead of
1200
+ * trusting pathspec globbing.
1201
+ *
1202
+ * No second `rev-parse`: the caller reaches this only when `untrackedTyranDir`
1203
+ * returned a boolean rather than null, which is already the answer to whether
1204
+ * git can answer.
1205
+ */
1206
+ export function initiativeGitStates(run, tyranDirName, names) {
1207
+ const lines = (out) => out.split('\n').filter((line) => line !== '');
1208
+ const tracked = lines(run(['ls-files', '--', tyranDirName]));
1209
+ // `--ignored` costs nothing on a call being made anyway and is the whole
1210
+ // difference between "you forgot" and "a rule you wrote is hiding it".
1211
+ // Porcelain v1 is `XY<space>path`; git collapses a wholly untracked or
1212
+ // ignored DIRECTORY into a single entry, so a recorded path can be shorter
1213
+ // than the prefix as well as longer — hence the check in both directions.
1214
+ const status = lines(run(['status', '--porcelain', '--ignored', '--', tyranDirName]));
1215
+ const paths = (keep) => status.filter((l) => l.startsWith('!! ') === keep).map((l) => l.slice(3));
1216
+ const ignored = paths(true);
1217
+ const dirty = paths(false);
1218
+ const covers = (entries, prefix) =>
1219
+ entries.some((path) => path.startsWith(prefix) || prefix.startsWith(path));
1220
+ const states = new Map();
1221
+ for (const name of names) {
1222
+ const prefix = `${tyranDirName}/state/${name}/`;
1223
+ if (tracked.some((path) => path.startsWith(prefix))) {
1224
+ states.set(name, covers(dirty, prefix) ? 'uncommitted' : 'committed');
1225
+ } else {
1226
+ states.set(name, covers(ignored, prefix) ? 'ignored' : 'untracked');
1227
+ }
1228
+ }
1229
+ return states;
1230
+ }
1231
+
1232
+ /** The finding for one non-`committed` ledger state, or null for `committed`. */
1233
+ function ledgerFinding(state, path, name, gitPath) {
1234
+ if (state === 'untracked') {
1235
+ return finding(
1236
+ 'initiative-untracked',
1237
+ show(path),
1238
+ 'git has never seen this ledger — `journal.mjs append` writes the working tree and nothing ' +
1239
+ 'else, so an initiative nobody committed is one `git clean -fd` from having never happened, ' +
1240
+ 'and a worktree carries tracked files only, so the agents working in one never read it',
1241
+ `git add ${sq(gitPath)} && git commit -m ${sq(`chore(tyran): record the ${name} ledger`)}`,
1242
+ );
1243
+ }
1244
+ if (state === 'ignored') {
1245
+ return finding(
1246
+ 'initiative-ignored',
1247
+ show(path),
1248
+ 'a .gitignore rule covers this ledger, so nothing under it can be committed — the journal is ' +
1249
+ 'the copy that is supposed to outlive the session, and this one exists on one machine only',
1250
+ `git check-ignore -v ${sq(`${gitPath}/journal.jsonl`)} # the rule doing it; ` +
1251
+ '`git add` alone is a silent no-op on an ignored path',
1252
+ );
1253
+ }
1254
+ return finding(
1255
+ 'initiative-uncommitted',
1256
+ show(path),
1257
+ 'the ledger has uncommitted changes — ordinary mid-initiative, a gap at a merge boundary: ' +
1258
+ 'rule 1 asks for the ledger to travel with the work, not to be committed once at the end',
1259
+ `git add ${sq(gitPath)} && git commit -m ${sq(`chore(tyran): ${name} ledger`)}`,
1260
+ );
1261
+ }
1262
+
1165
1263
  /**
1166
1264
  * Lease files committed to git. A lease records who holds a worktree or a
1167
1265
  * heavy slot RIGHT NOW; committing one makes every parallel merge conflict on
@@ -1258,7 +1356,7 @@ export function mistakesFindings(repoRoot) {
1258
1356
  show(claudePath),
1259
1357
  `${lawEntries} entr${lawEntries === 1 ? 'y' : 'ies'} in ${MISTAKES_FILE} ` +
1260
1358
  `claim${lawEntries === 1 ? 's' : ''} status \`law\`, and ${why}`,
1261
- `node scripts/mistakes.mjs repeats --file ${sq(path)} # see docs/self-improvement.md for the fence`,
1359
+ `node scripts/mistakes.mjs repeats --file ${sq(path)} # see https://jjanczur.github.io/tyran/self-improvement/ for the fence`,
1262
1360
  ),
1263
1361
  );
1264
1362
  }
@@ -1371,7 +1469,7 @@ export function overnightFindings(dir, { now = null, configDoc = null } = {}) {
1371
1469
  show(sidecarPath),
1372
1470
  `limits.mode is "${show(limits.mode)}" but the usage telemetry sidecar is ${sidecar === null ? 'absent' : 'over a day old'} — ` +
1373
1471
  'the gate fails open without it, so the configured pause protects nothing. The statusline ' +
1374
- 'helper is operator-installed; see docs/overnight.md',
1472
+ 'helper is operator-installed; see https://jjanczur.github.io/tyran/overnight/',
1375
1473
  `node scripts/statusline.mjs --sidecar-only # wired into the user-settings statusLine command`,
1376
1474
  ),
1377
1475
  );
@@ -1506,6 +1604,18 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1506
1604
  finding('state-unreadable', show(stateDir), `cannot list state/ (${errText(err)})`),
1507
1605
  );
1508
1606
  }
1607
+ // Only when `.tyran/` as a whole IS tracked. Under a wholly untracked
1608
+ // directory every initiative would repeat the finding above, each time
1609
+ // with narrower advice than the one that already covers it, and a check
1610
+ // that says the same thing N+1 times is a check people learn to skip.
1611
+ const gitStates =
1612
+ untracked === false
1613
+ ? initiativeGitStates(
1614
+ gitRun,
1615
+ basename(root),
1616
+ sortedNames(names).filter((name) => isDirectory(join(stateDir, name))),
1617
+ )
1618
+ : null;
1509
1619
  for (const name of sortedNames(names)) {
1510
1620
  const path = join(stateDir, name);
1511
1621
  if (!isDirectory(path)) {
@@ -1526,6 +1636,10 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1526
1636
  }
1527
1637
  const result = checkInitiative(stateDir, name, { now, staleHours });
1528
1638
  findings.push(...result.findings);
1639
+ const ledger = gitStates?.get(name) ?? 'committed';
1640
+ if (ledger !== 'committed') {
1641
+ findings.push(ledgerFinding(ledger, path, name, `${basename(root)}/state/${name}`));
1642
+ }
1529
1643
  initiatives.push(`${show(name)} (${result.events} event(s))`);
1530
1644
  }
1531
1645
  }
@@ -1542,7 +1656,7 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1542
1656
  'legacy layout — initiative files (PLAN.md, NOTES.md, RETRO.md, locks/) live under ' +
1543
1657
  'state/<initiative>/ since 0.1.9. Mechanical consumers read only state/, so anything ' +
1544
1658
  'kept here is invisible to the projections, the retrospective and the session summary',
1545
- `ls -la ${sq(legacyDir)} # relocate the contents by hand, one initiative directory at a time, into ${sq(join(dir, 'state'))} — see docs/journal.md`,
1659
+ `ls -la ${sq(legacyDir)} # relocate the contents by hand, one initiative directory at a time, into ${sq(join(dir, 'state'))} — see https://jjanczur.github.io/tyran/journal/`,
1546
1660
  ),
1547
1661
  );
1548
1662
  }
@@ -1564,7 +1678,7 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1564
1678
  `${trackedLeases.length} lease file(s) committed to git — a lease records who holds a resource ` +
1565
1679
  'RIGHT NOW, so a committed one conflicts on every parallel merge and resurrects as a phantom ' +
1566
1680
  'holder on every checkout',
1567
- `git ls-files -- ${sq(basename(root))} # list them; keep 'state/*/locks/' in .tyran/.gitignore and un-track the files by hand — see docs/configuration.md`,
1681
+ `git ls-files -- ${sq(basename(root))} # list them; keep 'state/*/locks/' in .tyran/.gitignore and un-track the files by hand — see https://jjanczur.github.io/tyran/configuration/`,
1568
1682
  ),
1569
1683
  );
1570
1684
  }
@@ -101,7 +101,7 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/mistakes.mjs" repeats
101
101
  It prints one line per signature that has crossed a graduation threshold,
102
102
  ending in what that signature has earned. Act on that recommendation — the
103
103
  thresholds themselves, and why they are where they are, live in
104
- `docs/self-improvement.md`.
104
+ https://jjanczur.github.io/tyran/self-improvement/.
105
105
 
106
106
  - **`promote to .tyran/knowledge/`** — write the rule into
107
107
  `.tyran/knowledge/<topic>.yaml`, scoped with `applies_to` so it reaches only
@@ -70,6 +70,13 @@ English regardless.
70
70
  server start vanish on restart, so restarts stop being deterministic;
71
71
  - probe the toolchain with `command -v` for every tool the plan names, and
72
72
  confirm your own file-writing path works before you rely on it;
73
+ - **probe for interactive aliases** — `alias cp mv rm 2>/dev/null` — because
74
+ an agent's shell is started from the user's profile, so `alias cp='cp -i'`
75
+ turns a copy into a question with nobody to answer it and the call burns
76
+ its whole timeout. Put `command cp` in the handoff when one is set. The
77
+ symptom is a timeout, which points at the machine rather than the alias,
78
+ so it is rediscovered every time: measured three times in one session, in
79
+ three different agents, and again in a later one that had read this file;
73
80
  - **dry-run every automaton** for one no-op iteration before you trust it
74
81
  with unattended work. Trust dialogs and missing dependencies surface
75
82
  then, not at 3am.
@@ -227,6 +234,15 @@ open one.
227
234
  carries an explicit **"NO INDEPENDENT REVIEW"** stamp; staying quiet about
228
235
  it is forbidden. Tests for every non-trivial change. Repo validation per
229
236
  the project configuration. You merge, sequentially.
237
+ - **A `Test timed out` measured while another heavy phase was running is
238
+ not evidence of a defect.** Re-run it serially, report the serial result,
239
+ and say the first run was concurrent. The hardware ceiling bounds AGENT
240
+ count, not concurrent heavy phases, so an agent can respect it and still
241
+ produce a red only the machine caused — five such failures in one session,
242
+ all green on a serial re-run.
243
+ - **An agent that dies on a terminal API error is RESUMED, not respawned.**
244
+ Its context, its corrected premises and its uncommitted diff all survive
245
+ the death; a fresh agent on the same handoff redoes work already on disk.
230
246
  - **How a diff is read is the `code-review` skill**; what the verdict looks
231
247
  like stays in `tyran:reviewer`. The part you enforce as conductor is that
232
248
  a finding arrives as an input and an expected result — anything vaguer
@@ -345,6 +361,11 @@ open one.
345
361
  manifest and lockfile are already a SHARED ZONE nobody may edit, so the
346
362
  dependencies are guaranteed identical, and a per-worktree install is how
347
363
  a lockfile drifts. Say in the handoff which directory you linked.
364
+ **Gitignored environment files are missing for the same reason, and they
365
+ fail QUIETER**: a missing dependency exits 127, a missing `.env` makes the
366
+ gated specs SKIP — so the worktree reports a *cleaner* baseline than the
367
+ repo has and the difference reads as good news. Link those too, and name
368
+ them in the handoff.
348
369
  - **`.tyran/state/**` lives in the main checkout only.** An agent told to
349
370
  append to `NOTES.md` from inside a worktree must use the absolute
350
371
  main-repo path, or it writes into a copy nobody reads.
@@ -437,6 +458,6 @@ open one.
437
458
  stop. Never route around the allowlist: the point of pausing at 97% is
438
459
  that the last 3% pays for a clean checkpoint instead of a corpse. The
439
460
  scheduler resumes the session after the reset (or notifies and holds on a
440
- long, weekly-shaped wait — `docs/overnight.md`); a resumed session starts
461
+ long, weekly-shaped wait — https://jjanczur.github.io/tyran/overnight/); a resumed session starts
441
462
  from the `usage-limit-pause` checkpoint and first closes the open
442
463
  usage-limit gate with `result: passed`.
@@ -164,7 +164,7 @@ copies of the config. Stage explicit paths until this commit exists.
164
164
 
165
165
  ## 7. Offer overnight mode — and say plainly what the operator must do
166
166
 
167
- Overnight mode (`docs/overnight.md`) pauses autonomous work near the
167
+ Overnight mode (https://jjanczur.github.io/tyran/overnight/) pauses autonomous work near the
168
168
  subscription usage limit and resumes after the window resets. It is OFF by
169
169
  default because its telemetry is a statusline the plugin cannot install:
170
170
  `.claude/settings.json` in user scope is the operator's file, and the policy
@@ -11,7 +11,7 @@
11
11
  #
12
12
  # Validate after editing: node scripts/schema.mjs validate config .tyran/config.yaml
13
13
 
14
- # Cost mode: eco | balanced | full (see docs/configuration.md)
14
+ # Cost mode: eco | balanced | full (see https://jjanczur.github.io/tyran/configuration/)
15
15
  profile: balanced
16
16
 
17
17
  # Deployment autonomy: P1 branch-only · P2 staging · P3 merge to main.
@@ -44,7 +44,7 @@ validation:
44
44
  shared_zones: []
45
45
 
46
46
  # Overnight mode — pause autonomous work near the subscription usage limits
47
- # and resume after the window resets (docs/overnight.md). Requires the
47
+ # and resume after the window resets (https://jjanczur.github.io/tyran/overnight/). Requires the
48
48
  # operator-installed statusline helper (scripts/statusline.mjs), which is the
49
49
  # only place the platform exposes usage telemetry; without it the gate is
50
50
  # silent and doctor says so.