@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +172 -0
- package/README.md +109 -57
- package/package.json +1 -1
- package/scripts/board-html.mjs +137 -9
- package/scripts/board.mjs +85 -9
- package/scripts/doctor.mjs +118 -4
- package/skills/retro/SKILL.md +1 -1
- package/skills/run/SKILL.md +22 -1
- package/skills/setup/SKILL.md +1 -1
- package/templates/config.yaml +2 -2
|
@@ -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.
|
|
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.
|
|
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
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|

|
|
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](
|
|
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](
|
|
76
|
+
survived them is what shipped. See [overnight mode](https://jjanczur.github.io/tyran/overnight/).
|
|
65
77
|
|
|
66
|
-
## Tyran
|
|
78
|
+
## Tyran vs. an ordinary session
|
|
67
79
|
|
|
68
|
-
The axis, not the winner
|
|
69
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
-
|
|
134
|
-
|
|
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,
|
|
137
|
-
|
|
138
|
-
|
|
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
|
|
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
|
-
|
|
149
|
-
|
|
150
|
-
and
|
|
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
|
-
|
|
|
161
|
-
|
|
|
162
|
-
|
|
|
163
|
-
|
|
|
164
|
-
|
|
|
165
|
-
|
|
|
166
|
-
|
|
|
167
|
-
|
|
|
168
|
-
|
|
|
169
|
-
|
|
|
170
|
-
|
|
|
171
|
-
|
|
|
172
|
-
|
|
|
173
|
-
|
|
|
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,
|
|
181
|
-
invokes it, is in
|
|
182
|
-
|
|
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](
|
|
192
|
-
| [Architecture](
|
|
193
|
-
| [Skills and agents](
|
|
194
|
-
| [Configuration](
|
|
195
|
-
| [Self-improvement](
|
|
196
|
-
| [Journal](
|
|
197
|
-
| [The board](
|
|
198
|
-
| [Overnight mode](
|
|
199
|
-
| [Hook runtime](
|
|
200
|
-
| [FAQ](
|
|
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.
|
|
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": {
|
package/scripts/board-html.mjs
CHANGED
|
@@ -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
|
-
|
|
288
|
-
|
|
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
|
-
|
|
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
|
|
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) {
|
|
526
|
-
|
|
527
|
-
|
|
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 () {
|
|
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)}
|
|
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
|
-
|
|
322
|
-
|
|
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
|
package/scripts/doctor.mjs
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
}
|
package/skills/retro/SKILL.md
CHANGED
|
@@ -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
|
-
|
|
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
|
package/skills/run/SKILL.md
CHANGED
|
@@ -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 —
|
|
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`.
|
package/skills/setup/SKILL.md
CHANGED
|
@@ -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 (
|
|
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
|
package/templates/config.yaml
CHANGED
|
@@ -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
|
|
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 (
|
|
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.
|