@jjanczur/tyran 0.1.30 → 0.1.32
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 +427 -0
- package/README.md +16 -4
- package/agents/reviewer.md +56 -9
- package/agents/scout.md +8 -2
- package/bin/tyran.mjs +8 -0
- package/hooks/scripts/policy-gate.mjs +22 -1
- package/hooks/scripts/secrets-gate.mjs +147 -11
- package/hooks/scripts/usage-gate.mjs +46 -12
- package/package.json +1 -1
- package/scripts/board-html.mjs +166 -9
- package/scripts/board.mjs +70 -8
- package/scripts/cost.mjs +392 -23
- package/scripts/doctor.mjs +302 -24
- package/scripts/ensure-gitleaks.mjs +254 -0
- package/scripts/journal.mjs +216 -0
- package/scripts/knowledge.mjs +89 -2
- package/scripts/migrate.mjs +191 -0
- package/scripts/overnight.mjs +2 -2
- package/scripts/pricing.mjs +255 -0
- package/scripts/project.mjs +159 -7
- package/scripts/scan-repo.mjs +120 -1
- package/scripts/schema.mjs +30 -6
- package/scripts/statusline.mjs +4 -1
- package/scripts/tiers.mjs +24 -0
- package/scripts/usage-source.mjs +135 -0
- package/skills/code-review/SKILL.md +1 -1
- package/skills/setup/SKILL.md +96 -10
|
@@ -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.32",
|
|
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.32",
|
|
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,432 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.32 — 2026-08-17
|
|
4
|
+
|
|
5
|
+
### Overnight mode could never fire, on any install
|
|
6
|
+
|
|
7
|
+
The pause depended on `.tyran/state/usage.json`; only the statusline writes
|
|
8
|
+
it; the statusline writes only when the platform payload carries
|
|
9
|
+
`rate_limits`; and that block is not always sent. Measured on an install
|
|
10
|
+
running `limits: mode: 'pause'` — **no sidecar had ever been written anywhere
|
|
11
|
+
on the machine**, so the configured pause had never once been able to fire.
|
|
12
|
+
The gate fails open, which is why nothing ever said so.
|
|
13
|
+
|
|
14
|
+
The gate now falls back to the platform's own cache in `~/.claude.json`, which
|
|
15
|
+
also removes the one onboarding step no script can perform: registering a
|
|
16
|
+
statusline means writing the operator's settings file, and the plugin is
|
|
17
|
+
refused there by design.
|
|
18
|
+
|
|
19
|
+
**A stale reading is acted on, deliberately.** That cache is refreshed on the
|
|
20
|
+
platform's schedule — measured 83 minutes old during continuous heavy use — so
|
|
21
|
+
under the gate's ten-minute freshness rule it would be discarded every time.
|
|
22
|
+
It is sound because usage inside a window only ever goes UP: a reading taken
|
|
23
|
+
inside the window that is still running is a LOWER BOUND on usage now. If it
|
|
24
|
+
already says 97%, the truth is at least that and pausing is correct; if it
|
|
25
|
+
says less, the gate may fail to pause, which is exactly today's behaviour and
|
|
26
|
+
the safe direction. A reading whose own `resets_at` has passed is discarded —
|
|
27
|
+
that check is what makes the rest safe. Pauses derived this way record
|
|
28
|
+
`lower_bound: true`, because "at least 97%" is a reason to stop and never a
|
|
29
|
+
reason to start.
|
|
30
|
+
|
|
31
|
+
Verified against live telemetry: at the shipped 97% nothing trips (the account
|
|
32
|
+
was at 32%/68%); at a 30% test threshold the weekly window trips with the
|
|
33
|
+
correct resume time.
|
|
34
|
+
|
|
35
|
+
`SIDECAR_RELPATH` had three spellings and `SIDECAR_FRESH_MS` two, across the
|
|
36
|
+
writer, the scheduler and the gate. Nothing fails while they agree, and when
|
|
37
|
+
they stop agreeing the symptom is a pause that silently never fires — the bug
|
|
38
|
+
above. They collapse into `scripts/usage-source.mjs`.
|
|
39
|
+
|
|
40
|
+
Only the two usage windows are read from that file. It also holds the account
|
|
41
|
+
uuid and the email address; a test asserts neither reaches the output.
|
|
42
|
+
|
|
43
|
+
### Three lifecycle leaks, each measured on real journals first
|
|
44
|
+
|
|
45
|
+
- **`lease-expired` was dead code that looked alive.** It read
|
|
46
|
+
`expires`/`expires_at`/`until`; across every journal on a real machine agents
|
|
47
|
+
wrote **`expiry` 33 times against `expires` 3**, so 33 of 36 recorded
|
|
48
|
+
expiries were invisible.
|
|
49
|
+
- **The schema flagged the field that would have made it work.** No expiry
|
|
50
|
+
spelling was in `DATA_KNOWN`, so recording one tripped `journal-key-unread`
|
|
51
|
+
— the ledger reporting an agent's own diligence back as an anomaly. Same for
|
|
52
|
+
the descriptions agents attach: `purpose` 28, `story` 21, `text` 21.
|
|
53
|
+
- **Worktrees accumulate and nothing had ever looked.** No removal path exists
|
|
54
|
+
in any skill, agent or script, and the journal has no event that can
|
|
55
|
+
represent one being destroyed. Measured: **26 worktrees in one repository,
|
|
56
|
+
33 GB under another's `.worktrees/`**. New `worktree-accumulating` warning
|
|
57
|
+
above a ceiling of 8 — a handful is the parallel model working as designed.
|
|
58
|
+
|
|
59
|
+
It **reports and does not remove**. Most of those worktrees hold work that
|
|
60
|
+
never CONCLUDED rather than work that finished, so removing the merged ones
|
|
61
|
+
would clear almost nothing while being able to delete something wanted.
|
|
62
|
+
|
|
63
|
+
### Spend answers "how much", with no configuration
|
|
64
|
+
|
|
65
|
+
The Spend tab could say how many tokens and never how much: `pricing:` was
|
|
66
|
+
hand-authored, the scanner never writes one, so absent was every install.
|
|
67
|
+
|
|
68
|
+
The published list prices now ship as `list-2026-08`. Cache rates are
|
|
69
|
+
published as fixed multiples of base input (1.25x, 2x, 0.1x), so only input
|
|
70
|
+
and output are written down and a test checks all fifteen rows against an
|
|
71
|
+
independently transcribed table. Overriding is per MODEL, not all-or-nothing.
|
|
72
|
+
|
|
73
|
+
This reverses an earlier rule — "Tyran does not know what anyone pays" — which
|
|
74
|
+
conflated two quantities. A subscriber's marginal cost is zero and unknowable;
|
|
75
|
+
what the tokens would list-price at on the API is published and fixed. The
|
|
76
|
+
reversal is conditional on the figure never claiming to be the other, so
|
|
77
|
+
`rate_card` still travels with every amount.
|
|
78
|
+
|
|
79
|
+
**Cache writes are billed at two rates and were counted as one.** A 1-hour
|
|
80
|
+
write costs 2x base input against a 5-minute write's 1.25x, and the transcripts
|
|
81
|
+
carry the split. Reading both the aggregate and the split would double-count,
|
|
82
|
+
so exactly one is read — verified across 1168 consecutive live records where
|
|
83
|
+
the two summed to the aggregate every time. Measured on 1.8 B real tokens: the
|
|
84
|
+
1-hour line is $175 against the 5-minute line's $70.
|
|
85
|
+
|
|
86
|
+
**A window you choose, because a plan is billed monthly.** `--window
|
|
87
|
+
30d|period|all`, and three buttons on the tab. `30d` is the default since it
|
|
88
|
+
needs nothing from the account; `period` runs from the subscription
|
|
89
|
+
anniversary and is offered only when that date is readable. The anniversary
|
|
90
|
+
arithmetic clamps short months — a subscription created on the 31st has no
|
|
91
|
+
31st in February, and naive maths yields a period that has not begun.
|
|
92
|
+
|
|
93
|
+
The plan price sits beside the API figure, and the multiple is shown only
|
|
94
|
+
under a month-shaped window: measured, an all-time total read as "6.9x what
|
|
95
|
+
you pay" where the honest monthly figure was about 11x.
|
|
96
|
+
|
|
97
|
+
**A per-day series**, which this page never had — every other view is a
|
|
98
|
+
snapshot, so nothing could answer "am I getting cheaper". It shows the full
|
|
99
|
+
history whatever window is selected, since a chart that shrank with the window
|
|
100
|
+
could not show you that last month was worse.
|
|
101
|
+
|
|
102
|
+
### The reviewer can fix what it finds
|
|
103
|
+
|
|
104
|
+
The property worth protecting was never "a reviewer cannot type" — it is that
|
|
105
|
+
nobody approves their own code, and those come apart. The reviewer holds
|
|
106
|
+
`Edit`, and the verdict is three-valued: a diff it touched can only come back
|
|
107
|
+
`REVISED`, which still owes a second read, and that read is cheap because the
|
|
108
|
+
fix is already written. No `Write` or `NotebookEdit`: authoring files is
|
|
109
|
+
designing, not reviewing.
|
|
110
|
+
|
|
111
|
+
An open operator ask now goes in the verdict LINE. Field-measured: a reviewer
|
|
112
|
+
raised a gate inside the body of an APPROVE, the conductor read the first
|
|
113
|
+
word, merged, and the question sat unanswered for thirty minutes.
|
|
114
|
+
|
|
115
|
+
**Subagents could not reach MCP at all.** `tools:` is an exhaustive allowlist,
|
|
116
|
+
so naming six built-ins silently stripped every `mcp__*` tool from the scout
|
|
117
|
+
and the reviewer — the scout's own description promises reconnaissance over
|
|
118
|
+
"its data", which was unreachable. Grants stay gated: write-guard's matcher
|
|
119
|
+
already carries `mcp__.*`.
|
|
120
|
+
|
|
121
|
+
### Two gate refusals that were wrong
|
|
122
|
+
|
|
123
|
+
- A backslash-escaped separator started a new segment, so `grep -nE 'A\|B' f`
|
|
124
|
+
split in two and an ordinary read was refused. `\<sep>` is never an operator
|
|
125
|
+
in any shell quoting context — verified against `/bin/sh` with a side-effect
|
|
126
|
+
oracle over 34 join constructions, zero divergences. The lexer stays
|
|
127
|
+
quote-BLIND on purpose: a naive quote tracker is broken by one apostrophe,
|
|
128
|
+
which swallows a `;` and makes a `git push` invisible to the deployment
|
|
129
|
+
check.
|
|
130
|
+
- `^id_[a-z0-9]+$` was really "any identifier starting with id_", and these
|
|
131
|
+
rules run over every literal WORD of a command — so `ID_ISSUED` and
|
|
132
|
+
`ID_TOKEN` were refused as ssh private keys. Now anchored on OpenSSH's own
|
|
133
|
+
key-type names, keeping hardware keys and per-host suffixes. Declared cost: a
|
|
134
|
+
key with an invented stem is no longer matched by name, though `.ssh/` still
|
|
135
|
+
catches it and so does gitleaks at push.
|
|
136
|
+
|
|
137
|
+
### Setup asks one question, in words a non-engineer can answer
|
|
138
|
+
|
|
139
|
+
Sales and marketing people run this now, and four entries shaped
|
|
140
|
+
`field: source` is where they stop. The scan carries a `plain` object: one
|
|
141
|
+
question, its evidence restated without jargon, at most two options, and a
|
|
142
|
+
list of what the repository already answered. P3 is not offered — a menu makes
|
|
143
|
+
every item look like a normal choice, and it stays something a person says in
|
|
144
|
+
their own words.
|
|
145
|
+
|
|
146
|
+
### Installation reaches the dashboard now
|
|
147
|
+
|
|
148
|
+
Install was four steps, a restart, and then a board nobody opened. Every one
|
|
149
|
+
of those is a place to stop, and the last one mattered most: `--serve` printed
|
|
150
|
+
a URL to a terminal and **nothing ever launched a browser**, so the screen
|
|
151
|
+
where Tyran becomes legible was the one thing installation never reached.
|
|
152
|
+
|
|
153
|
+
`install.sh` does everything a machine can:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
curl -fsSL https://raw.githubusercontent.com/jjanczur/tyran/main/install.sh | sh
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Node version check first, because every hook shells out to `node` and an old
|
|
160
|
+
one does not fail at install time — it fails later as a gate that cannot run,
|
|
161
|
+
which is the hardest thing for a non-technical operator to read. Then the
|
|
162
|
+
plugin, then the pinned scanner, then the prompt to paste after the restart.
|
|
163
|
+
|
|
164
|
+
The restart is the one step that stays manual and it is not a shortcut not
|
|
165
|
+
taken: Claude Code loads plugins at startup and nothing inside a session can
|
|
166
|
+
make the app reload itself. So it is stated plainly and put last.
|
|
167
|
+
|
|
168
|
+
`board.mjs --serve --open` launches the browser, best-effort and never fatal —
|
|
169
|
+
a headless machine or an SSH session leaves the server running and the URL
|
|
170
|
+
printed, exactly where things were before. `--open` without `--serve` is a
|
|
171
|
+
usage error, like `--write`.
|
|
172
|
+
|
|
173
|
+
Setup gained two steps: install the scanner before anything needs it, and
|
|
174
|
+
**look for pre-existing secrets before the operator hits them**. A repository
|
|
175
|
+
whose history already holds a key is common, and the gate handles it badly by
|
|
176
|
+
surprise — nothing is scanned until someone edits that file, and then every
|
|
177
|
+
commit touching it is refused, permanently, for a reason years old. Setup now
|
|
178
|
+
says what is there and explains the choice, including the part that is easy to
|
|
179
|
+
leave out: a tracked baseline makes the tool quiet, it does not make the key
|
|
180
|
+
safe, and if the repo is public that key is already burned.
|
|
181
|
+
|
|
182
|
+
### The knowledge store was write-only, and nothing said so
|
|
183
|
+
|
|
184
|
+
Measured on a real install: `knowledge.mjs brief '**'` returned **1 of 31
|
|
185
|
+
entries**. The other thirty were dropped by the 4000-codepoint budget, and
|
|
186
|
+
104,178 codepoints of hard-won detail — migration-number races, TEST/PROD
|
|
187
|
+
schema drift, a deploy gate that silently blocks on the commit author — had
|
|
188
|
+
been accumulating for months and reaching nobody.
|
|
189
|
+
|
|
190
|
+
That is the opposite of the failure people expect from a growing store. It is
|
|
191
|
+
not expensive to read; it is **unread**, while growing without bound.
|
|
192
|
+
|
|
193
|
+
Every piece of the machinery was already correct and none of it added up. The
|
|
194
|
+
budget is deliberately the pressure that keeps entries scoped. Each brief
|
|
195
|
+
already names what it omitted. `doctor` already warned per oversized entry —
|
|
196
|
+
five times on that install. What nobody had was the total, and five local
|
|
197
|
+
tidy-up notes are not the same message as "your knowledge store is 97%
|
|
198
|
+
unread". Only the second one gets acted on.
|
|
199
|
+
|
|
200
|
+
`knowledge.mjs audit` reports it: how many entries could reach ONE brief, how
|
|
201
|
+
many could not, and — the diagnostic that matters most — which entries are so
|
|
202
|
+
wide they cannot appear **even alone**, where no budget any caller passes will
|
|
203
|
+
ever reach them. Eight of that install's thirty-one are in that state; the
|
|
204
|
+
widest is 10,210 codepoints, two and a half times the whole budget.
|
|
205
|
+
`doctor --state` carries the same number as `knowledge-store-unreachable`
|
|
206
|
+
(`info` — a store outgrows the budget in the ordinary course of being useful).
|
|
207
|
+
|
|
208
|
+
It measures and never edits. Which of two overlapping entries is the true one
|
|
209
|
+
is a judgement, and a script that guessed would delete exactly the detail the
|
|
210
|
+
store exists to hold — so consolidation is a retrospective step that writes a
|
|
211
|
+
**new** file for review and leaves the original untouched.
|
|
212
|
+
|
|
213
|
+
### The prerequisite that blocked day one
|
|
214
|
+
|
|
215
|
+
The secrets gate refuses every commit and push until `gitleaks` exists, and
|
|
216
|
+
it refuses rather than warning for a reason that has not changed. What had
|
|
217
|
+
been left with the operator is the *installing*: some people adopting Tyran
|
|
218
|
+
have no Homebrew, no admin rights, or are on Windows, and their realistic
|
|
219
|
+
answer to "install it and re-run" is not a safer repository — it is switching
|
|
220
|
+
the hook off. A gate nobody can satisfy protects nothing, which is the same
|
|
221
|
+
argument that made `.tyran/config.yaml` AUTO.
|
|
222
|
+
|
|
223
|
+
`scripts/ensure-gitleaks.mjs` fetches it: pinned version **and** pinned
|
|
224
|
+
SHA-256 per platform, taken from the release's own checksums, which is the
|
|
225
|
+
thing `ci.yml` has always done moved to where a user can reach it. A mismatch
|
|
226
|
+
deletes the download and installs nothing — this writes an executable that
|
|
227
|
+
something else later runs, and a scanner that has been replaced reports clean
|
|
228
|
+
on everything.
|
|
229
|
+
|
|
230
|
+
It installs to `~/.tyran/bin/`. The first version of this put it under
|
|
231
|
+
`<repo>/.tyran/bin/`, which is worse in a way worth recording: a path inside
|
|
232
|
+
the repository travels with a clone, so a planted binary reporting clean on
|
|
233
|
+
everything would arrive **with the checkout** — the attack the tracked-only
|
|
234
|
+
rule for `.gitleaksignore` already prevents, reopened through a file that is
|
|
235
|
+
not even in a diff. Under HOME the scanner is the operator's machine, exactly
|
|
236
|
+
like PATH, and one install serves every repository on it. PATH is still
|
|
237
|
+
consulted first: a gitleaks you installed yourself is never silently
|
|
238
|
+
displaced by whatever version this repo pins.
|
|
239
|
+
|
|
240
|
+
### Writing a prompt is now a top-tier job
|
|
241
|
+
|
|
242
|
+
`retro` was routed at `work` and reached `deep` only under `--profile full`,
|
|
243
|
+
so the agent that writes skills, agents and prompts — the text every later
|
|
244
|
+
session obeys — ran on the middle model, and `--profile eco` kept it there.
|
|
245
|
+
|
|
246
|
+
A new `authoring` role sits at `top` at every profile, with `top` and `max`
|
|
247
|
+
floors under it. Separated from `retro` rather than raising the whole of it,
|
|
248
|
+
because retro does two unlike things with one agent: folding a ledger, which
|
|
249
|
+
the middle model does fine, and authoring. The argument is `security-review`'s
|
|
250
|
+
in a stronger form — a bad security verdict costs one merge, while a bad
|
|
251
|
+
prompt misroutes every run that reads it for as long as it ships, and it is
|
|
252
|
+
the one output nothing downstream checks, because a skill that reads plausibly
|
|
253
|
+
passes review.
|
|
254
|
+
|
|
255
|
+
### A duplicate ledger id is refused
|
|
256
|
+
|
|
257
|
+
Measured in the field: two implementers running in parallel each worked out an
|
|
258
|
+
id for themselves, both were honoured, and the ledger kept two `F-7`s. History
|
|
259
|
+
is append-only, so "see F-7" stays ambiguous forever and nothing detects it
|
|
260
|
+
later.
|
|
261
|
+
|
|
262
|
+
`append` now refuses a caller-supplied `id` that is **already used for that
|
|
263
|
+
event type**. Deliberately not the broader fix of refusing every explicit id:
|
|
264
|
+
that removes a documented capability — an explicit id still wins, and a test
|
|
265
|
+
pins it — to prevent a failure that only occurs on collision. A fresh explicit
|
|
266
|
+
id still passes, `ticket.created` is unaffected because its ids come from the
|
|
267
|
+
plan, and the check runs under the write lock so two concurrent writers cannot
|
|
268
|
+
both pass it.
|
|
269
|
+
|
|
270
|
+
### Refusals you can paste
|
|
271
|
+
|
|
272
|
+
The multi-remote push refusal is correct — excluding commits present on ANY
|
|
273
|
+
remote let a key held on a private upstream reach a public origin unscanned —
|
|
274
|
+
but it was reported twice, from two installs, as a false positive, and both
|
|
275
|
+
reporters routed around it instead of satisfying it. The old text handed over
|
|
276
|
+
`git push <remote> <branch>`, a shape to translate rather than a line to run.
|
|
277
|
+
|
|
278
|
+
Everything needed to write the real command was already in hand, so it is
|
|
279
|
+
written: one runnable line per remote, with the branch filled in.
|
|
280
|
+
|
|
281
|
+
### Reviewers stop retyping evidence
|
|
282
|
+
|
|
283
|
+
`tyran:reviewer` has no MCP tools, so a database row or an API response
|
|
284
|
+
someone else fetched reaches it as text in a handoff — and text in a handoff
|
|
285
|
+
gets retyped. Measured on a production run: **1.6% of hand-copied values were
|
|
286
|
+
silently wrong**, which makes a reviewer that mistranscribes evidence worse
|
|
287
|
+
than no reviewer, because the verdict carries authority the numbers do not.
|
|
288
|
+
|
|
289
|
+
The roster is unchanged, because it cannot express the fix: `tools:` is a
|
|
290
|
+
static list shipped in the plugin and MCP tool names differ on every install.
|
|
291
|
+
The prompt closes it instead — require the raw bytes on disk and `Read` them,
|
|
292
|
+
rather than reasoning about a retyped copy. A value read from a file is
|
|
293
|
+
evidence; a value pasted into a sentence is a claim about evidence.
|
|
294
|
+
|
|
295
|
+
## 0.1.31 — 2026-08-17
|
|
296
|
+
|
|
297
|
+
Seven things the journal had recorded and nothing was reading. The theme is
|
|
298
|
+
one defect wearing different clothes: an answer that was available, a
|
|
299
|
+
consumer that never asked for it, and a surface that reported confidence
|
|
300
|
+
instead of the gap.
|
|
301
|
+
|
|
302
|
+
### Four things the fold recorded and threw away
|
|
303
|
+
|
|
304
|
+
Each of these was a question an operator asked the board, got a confident
|
|
305
|
+
answer to, and the answer was wrong in the same direction: everything looked
|
|
306
|
+
fine.
|
|
307
|
+
|
|
308
|
+
**An agent the initiative moved on without now reads `stale`, not `running`.**
|
|
309
|
+
Nothing in the projection ever downgraded a spawn, so an agent that never
|
|
310
|
+
reported stayed `running` in every artefact for as long as the journal
|
|
311
|
+
survived, and the board's header counted week-old ghosts as live work. Doctor
|
|
312
|
+
had been calling those same spawns abandoned the whole time, from the same
|
|
313
|
+
events — two answers to one question, which is the defect ADR-21 is named
|
|
314
|
+
after and which `pairSpawns` had already been through once for the adjacent
|
|
315
|
+
question of who is still working.
|
|
316
|
+
|
|
317
|
+
There is now one predicate, `journal.spawnStaleness`, and both consumers call
|
|
318
|
+
it; doctor's copy is gone rather than kept in sync. It could not live in
|
|
319
|
+
doctor, which imports the projection, so it sits in `journal.mjs` beside
|
|
320
|
+
`pairSpawns` where both already reach.
|
|
321
|
+
|
|
322
|
+
The threshold is journal time — measured against the initiative's own latest
|
|
323
|
+
event, never the wall clock. That is what `spawn-stale` has always meant, and
|
|
324
|
+
it is the only version that keeps `board.json` byte-exact under `--check`.
|
|
325
|
+
`blocked` still outranks `stale`, because that is the agent's own account of
|
|
326
|
+
why it stopped. The `age-fresh/warm/cold/dead` colours on the page are a
|
|
327
|
+
different question and keep their own vocabulary: an agent can be quiet for
|
|
328
|
+
hours without being stale, and stale while chattering every minute.
|
|
329
|
+
|
|
330
|
+
**A closing checkpoint closes the spawns it leaves open.** No event type
|
|
331
|
+
closed an initiative, so one could be explicitly wound up with three agents
|
|
332
|
+
that never reported still running forever. `checkpoint` with `phase: closed`
|
|
333
|
+
— the one reserved value in an otherwise free-text field — now closes that
|
|
334
|
+
initiative's still-open spawns at fold time, and only the ones folded before
|
|
335
|
+
it, so an agent spawned afterwards keeps its own lifecycle. They are closed,
|
|
336
|
+
never reported: no verdict is invented for an agent that never filed one, and
|
|
337
|
+
each is named in the warnings rather than tidied away.
|
|
338
|
+
|
|
339
|
+
**A gate that passes after refusing no longer erases the refusal.** Results
|
|
340
|
+
are keyed by `kind`, so a re-run won the slot, and *"security denied this,
|
|
341
|
+
then someone re-ran it green"* rendered identically to *"security has only
|
|
342
|
+
ever passed"*. The event count always survived, so the volume was never lost
|
|
343
|
+
— only the verdict. The last refusal is kept beside the current result and
|
|
344
|
+
gets its own column in `STATE.md`. A refusal is a named set (`deny`, `fail`,
|
|
345
|
+
`rejected`, …) rather than "anything that is not a pass": the first draft was
|
|
346
|
+
the latter, and the demo fixture caught it at once, marking every `open` gate
|
|
347
|
+
as carrying a permanent objection it had never raised.
|
|
348
|
+
|
|
349
|
+
**A report carries what the agent said, not only its verdict.** `decision`
|
|
350
|
+
folds its `text` and `gate` folds its `evidence`; `report` was the one carrier
|
|
351
|
+
of description that wrote to nowhere, so a `changes-needed` card reached the
|
|
352
|
+
board with the reason it came back discarded at fold time. One field reads
|
|
353
|
+
`text`, then `note`, then `evidence`, because agents improvise the key.
|
|
354
|
+
|
|
355
|
+
The board header now says *open* rather than *running* and names the stale
|
|
356
|
+
count beside it — the agents are still counted and still in the strip, but an
|
|
357
|
+
open spawn and live work are not the same fact and the tile was asserting the
|
|
358
|
+
second from the first.
|
|
359
|
+
|
|
360
|
+
### The two findings doctor could only ever report
|
|
361
|
+
|
|
362
|
+
`state-legacy-initiatives-dir` shipped with a remedy that read "relocate the
|
|
363
|
+
contents by hand, one initiative directory at a time". That is advice, not a
|
|
364
|
+
remedy, and the installs carrying the finding are by definition the ones
|
|
365
|
+
nobody has touched since 0.1.8. `scripts/migrate.mjs` does the move.
|
|
366
|
+
|
|
367
|
+
It is explicit and never automatic, because it MOVES an append-only history
|
|
368
|
+
rather than seeding a file that does not exist yet — the same reason it is not
|
|
369
|
+
a step inside setup. It previews by default and does nothing until asked twice.
|
|
370
|
+
It never overwrites: a name that already exists under `state/` is a conflict,
|
|
371
|
+
reported and skipped and left untouched on **both** sides, because merging two
|
|
372
|
+
directories that share a name is a decision only the operator can make and
|
|
373
|
+
making it silently would destroy the evidence needed to make it correctly. It
|
|
374
|
+
never deletes anything it did not itself empty. It is idempotent, and it exits
|
|
375
|
+
1 while any conflict stands, so an automated caller can tell "done" from "done
|
|
376
|
+
except for the part that mattered".
|
|
377
|
+
|
|
378
|
+
**`mistakes-file-missing`** (`info`) splits an absence that used to be one
|
|
379
|
+
thing. Deleting `MISTAKES.md` is the documented opt-out and still produces no
|
|
380
|
+
finding at all — a tool that nags about a file you deliberately removed is a
|
|
381
|
+
tool you switch off, and that would cost the gates sitting next to it. But an
|
|
382
|
+
install created before the ledger existed never declined anything; nobody
|
|
383
|
+
offered. Git is the only witness that can tell those apart, so the finding
|
|
384
|
+
fires only where git can answer AND has never seen the file. Where there is no
|
|
385
|
+
repository, or no git, it says nothing rather than guessing — a guess there
|
|
386
|
+
nags precisely the operator who already opted out.
|
|
387
|
+
|
|
388
|
+
Neither is an alarm, but for different reasons.
|
|
389
|
+
`state-legacy-initiatives-dir` stays a `warning` — a legacy layout genuinely
|
|
390
|
+
hides initiative files from every mechanical consumer — and what changed is
|
|
391
|
+
that it finally has a remedy rather than a paragraph of advice.
|
|
392
|
+
`mistakes-file-missing` is `info` because nothing is broken at all: it is an
|
|
393
|
+
offer, and the only absence it will ever break silence about is the one
|
|
394
|
+
nobody chose.
|
|
395
|
+
|
|
396
|
+
### Accept-then-ignore, ended without nagging
|
|
397
|
+
|
|
398
|
+
`append` accepts any key inside `data` and always will: *"data may always
|
|
399
|
+
carry extra keys"* is a promise the envelope makes, the evidence gate relies
|
|
400
|
+
on it for four of its own, and turning it into a rule would fail every journal
|
|
401
|
+
ever written the moment they were re-validated. So this is a report, never a
|
|
402
|
+
refusal — and it is deliberately not the whole report.
|
|
403
|
+
|
|
404
|
+
Measured on one real install: **130 distinct (event, key) pairs across 39
|
|
405
|
+
initiatives**, and the long tail of that is deliberate annotation —
|
|
406
|
+
`init.created.hardware`, `retro.entry.proposed_as_diffs`, `spawn.stories`.
|
|
407
|
+
Naming all of it as findings would report the extension mechanism working as
|
|
408
|
+
designed, on every healthy repo, and doctor's own severity notes already argue
|
|
409
|
+
where that ends: a check that is red during normal operation is a check people
|
|
410
|
+
learn to skip — and this one sits next to the gates.
|
|
411
|
+
|
|
412
|
+
The defect hiding in that tail is narrower and worth a warning each.
|
|
413
|
+
**`journal-key-near-miss`** reports a key one edit from the key consumers
|
|
414
|
+
actually read: `next_step` for `next_steps` is accepted, never read, and never
|
|
415
|
+
reported, so the resume surface is empty while the agent that wrote it
|
|
416
|
+
believes it recorded something. Distance one and nothing looser — at two,
|
|
417
|
+
`note` matches `next` and the check starts inventing typos in correct
|
|
418
|
+
journals. Keys of three characters or fewer are exempt for the same reason.
|
|
419
|
+
|
|
420
|
+
**`journal-key-unread`** (`info`) counts and names the rest, so nothing is
|
|
421
|
+
dropped (ADR-19 correction 1) and "recorded" stays distinguishable from
|
|
422
|
+
"recorded AND read" — without turning a documented contract into 130 rows of
|
|
423
|
+
alarm.
|
|
424
|
+
|
|
425
|
+
`DATA_KNOWN` in `journal.mjs` is the map of what each event type's consumers
|
|
426
|
+
read, and it sits next to `DATA_REQUIRED` because both answer "what is in
|
|
427
|
+
`data`". It is descriptive: an incomplete entry can only under-report, never
|
|
428
|
+
invent a finding.
|
|
429
|
+
|
|
3
430
|
## 0.1.30 — 2026-08-17
|
|
4
431
|
|
|
5
432
|
The first release built on an outside contribution. It fixes a spend ledger
|
package/README.md
CHANGED
|
@@ -123,8 +123,10 @@ Mechanisms rather than instructions — which is the whole argument.
|
|
|
123
123
|
profile or risk flag can cross.
|
|
124
124
|
- **A spend ledger.** `npx @jjanczur/tyran cost` reports what the work cost, in
|
|
125
125
|
the tokens the platform itself reported, per model, per agent type and per
|
|
126
|
-
ticket — read out of the transcripts Claude Code already writes.
|
|
127
|
-
|
|
126
|
+
ticket — read out of the transcripts Claude Code already writes. Dollars
|
|
127
|
+
need no setup: the published list prices ship, so a fresh install shows what
|
|
128
|
+
the run would have cost through the API, next to what your plan costs a
|
|
129
|
+
month. Write a rate card only to override them.
|
|
128
130
|
- **It can run overnight, because the usage limit is a wind-down and not a
|
|
129
131
|
crash.** The platform's own behaviour at the limit is a cliff: calls start
|
|
130
132
|
failing mid-flight and agents die between a write and its commit. Near the
|
|
@@ -176,7 +178,17 @@ count, not the price of a model.
|
|
|
176
178
|
|
|
177
179
|
## Install
|
|
178
180
|
|
|
179
|
-
|
|
181
|
+
One command, then one restart, then one paste:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
curl -fsSL https://raw.githubusercontent.com/jjanczur/tyran/main/install.sh | sh
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
It checks Node, installs the plugin, installs the secrets scanner the write
|
|
188
|
+
gate needs, and prints the prompt to paste after you restart — which runs
|
|
189
|
+
setup and opens the dashboard in your browser.
|
|
190
|
+
|
|
191
|
+
Or do it by hand, inside Claude Code:
|
|
180
192
|
|
|
181
193
|
```text
|
|
182
194
|
/plugin marketplace add jjanczur/tyran
|
|
@@ -297,7 +309,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
|
|
|
297
309
|
fires and who invokes it, is in
|
|
298
310
|
[skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
|
|
299
311
|
themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
|
|
300
|
-
it:
|
|
312
|
+
it: 1526 unit tests, run with `node --test "tests/**/*.test.mjs"`.
|
|
301
313
|
|
|
302
314
|
## Documentation
|
|
303
315
|
|
package/agents/reviewer.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: reviewer
|
|
3
|
-
description: Independent quality control on another agent's work - reads the whole diff, runs its OWN verification rather than trusting the author's report, checks that the claimed optimization is actually in the code, and returns
|
|
4
|
-
tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
|
|
3
|
+
description: Independent quality control on another agent's work - reads the whole diff, runs its OWN verification rather than trusting the author's report, checks that the claimed optimization is actually in the code, and returns APPROVE, REVISED or CHANGES-REQUESTED with numbered, executable counterexamples. May fix what it finds, which forfeits APPROVE. Never reviews its own code.
|
|
4
|
+
tools: Read, Grep, Glob, Bash, Edit, WebFetch, WebSearch, mcp__*
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
You are a reviewer. You review ANOTHER agent's work, never your own.
|
|
@@ -9,10 +9,47 @@ You are a reviewer. You review ANOTHER agent's work, never your own.
|
|
|
9
9
|
**Reply in the language the conductor writes to you in. Anything written to
|
|
10
10
|
disk is in English.**
|
|
11
11
|
|
|
12
|
-
You
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
12
|
+
**You may fix what you find. Fixing costs you the right to approve it.**
|
|
13
|
+
|
|
14
|
+
You have `Edit`, and it is there because describing a one-line fix in prose,
|
|
15
|
+
waiting for the conductor to route it, and having the author re-derive it from
|
|
16
|
+
your description is a slow way to reach a change you had already worked out.
|
|
17
|
+
Write it instead.
|
|
18
|
+
|
|
19
|
+
What you may never do is bless your own work. So the verdict is three-valued,
|
|
20
|
+
and the rule is mechanical rather than a matter of judgement: **if you touched
|
|
21
|
+
the diff, `APPROVE` is not available to you.** Your verdict is `REVISED`, and
|
|
22
|
+
the second pair of eyes is cheap precisely because the fix is already written —
|
|
23
|
+
someone reads a small concrete delta instead of re-deriving one from a
|
|
24
|
+
paragraph. A reviewer who edits and then approves has reviewed nothing; that is
|
|
25
|
+
the entire failure this rule exists to stop, and it is the only one.
|
|
26
|
+
|
|
27
|
+
Two boundaries on the grant, both narrow on purpose:
|
|
28
|
+
|
|
29
|
+
- **`Edit` only — no `Write`, no `NotebookEdit`.** You change lines that exist.
|
|
30
|
+
A reviewer who creates files has stopped reviewing and started designing, and
|
|
31
|
+
the tool list says so rather than a paragraph asking you to be disciplined.
|
|
32
|
+
- **Fix what you found. Do not redesign.** If the right answer is "this whole
|
|
33
|
+
approach is wrong", that is `CHANGES-REQUESTED` with the argument, not a
|
|
34
|
+
rewrite. The pull toward patching a symptom you can reach, instead of
|
|
35
|
+
reporting a cause you cannot, is the real cost of holding this tool — notice
|
|
36
|
+
it.
|
|
37
|
+
|
|
38
|
+
`Bash` can still write, and so can an MCP tool whose name this plugin has never
|
|
39
|
+
seen. **Verify, never mutate**: query the database, do not migrate it; read the
|
|
40
|
+
issue, do not close it.
|
|
41
|
+
|
|
42
|
+
**Never retype evidence. Go and get it.** A database row or an API response
|
|
43
|
+
someone else fetched reaches you as text in the handoff, and text in a handoff
|
|
44
|
+
gets retyped. Measured on a production run: 1.6% of hand-copied values were
|
|
45
|
+
silently wrong, which makes a reviewer that mistranscribes evidence worse than
|
|
46
|
+
no reviewer, because the verdict carries authority the numbers do not deserve.
|
|
47
|
+
You have the operator's MCP servers, so the first move is to re-run the query
|
|
48
|
+
yourself and compare. When you genuinely cannot obtain the output — the tool
|
|
49
|
+
is absent, the credential is not yours — require the raw bytes on disk and
|
|
50
|
+
`Read` them: reply asking for the path, do not reason about the retyped copy.
|
|
51
|
+
A value you fetched or read is evidence; a value someone pasted into a
|
|
52
|
+
sentence is a claim about evidence.
|
|
16
53
|
|
|
17
54
|
1. **Read the whole diff** plus the story file that holds the acceptance
|
|
18
55
|
criteria. **Follow the `code-review` skill for the sweep** — it carries the
|
|
@@ -47,9 +84,13 @@ that keeps you.
|
|
|
47
84
|
without one loses the author's work with no record of what was in it.
|
|
48
85
|
3. **Check the optimization section** — whether what the author claims is
|
|
49
86
|
genuinely in the code, not just in the write-up.
|
|
50
|
-
4. **The verdict is
|
|
51
|
-
|
|
52
|
-
|
|
87
|
+
4. **The verdict is one of three words**, and the first line of your report is
|
|
88
|
+
that word alone. APPROVE, with minor notes routed to `NOTES.md`; REVISED if
|
|
89
|
+
you edited anything, listing every file you touched and why; or
|
|
90
|
+
CHANGES-REQUESTED with a numbered list — what, where, why. No generalities.
|
|
91
|
+
- **REVISED is not a soft APPROVE.** It means the work is now partly yours
|
|
92
|
+
and still owes someone a read. Say in one line what a second reader should
|
|
93
|
+
look at hardest, because you are the one person who cannot judge it.
|
|
53
94
|
- **Every counterexample must be EXECUTABLE**: concrete input, expected
|
|
54
95
|
behaviour, so it can be pinned as a test. A finding that cannot be pinned
|
|
55
96
|
cannot be verified as fixed.
|
|
@@ -66,6 +107,12 @@ that keeps you.
|
|
|
66
107
|
'...' --default '...'` — name the `Q-<n>` in your review, and give a
|
|
67
108
|
verdict on everything else. Holding a whole review open on one question
|
|
68
109
|
the operator has not seen is how a queue becomes a stall.
|
|
110
|
+
- **An open ask goes in the verdict LINE, not the body**: write
|
|
111
|
+
`APPROVE — BLOCKED ON Q-3` and nothing else on that line. Measured on a
|
|
112
|
+
field run: a reviewer raised an operator gate inside the body of an
|
|
113
|
+
APPROVE, the conductor read the first word, merged, and the question sat
|
|
114
|
+
unanswered for thirty minutes. Anything a merge must wait for has to
|
|
115
|
+
survive being read by someone who reads one line.
|
|
69
116
|
5. **Say what you did NOT check.** Platform you did not run on, concurrency
|
|
70
117
|
you did not exercise, the input class you skipped. This section is a merge
|
|
71
118
|
gate, not a courtesy: the conductor resolves every item as measured,
|
package/agents/scout.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: scout
|
|
3
3
|
description: Fast, cheap reconnaissance over a repo, its documentation, its data or external sources, changing nothing. Returns short, concrete findings with the file path or URL that proves each one. Used by the conductor at the start of a task and through the research phase of a large initiative.
|
|
4
|
-
tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
|
|
4
|
+
tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, mcp__*
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
You are the scout. You find things out. You change nothing.
|
|
@@ -28,7 +28,13 @@ disk is in English.**
|
|
|
28
28
|
4. **Verify premises about DATA by measuring, read-only.** "The field is in
|
|
29
29
|
the schema" is not "the field is in the data". If the handoff assumes
|
|
30
30
|
something about a real dataset, check the dataset and report what you
|
|
31
|
-
actually saw.
|
|
31
|
+
actually saw. You have the operator's MCP servers for exactly this — a
|
|
32
|
+
database, an issue tracker, a browser — and they are the only way to reach
|
|
33
|
+
data that is not a file. Rule 1 governs them and it governs them harder:
|
|
34
|
+
the tool list cannot tell a read from a write, because an MCP server names
|
|
35
|
+
its own tools and this plugin has never seen yours. `execute_sql` reads
|
|
36
|
+
until the statement is an `INSERT`. Run the query; never the migration,
|
|
37
|
+
the mutation, the deploy or the delete.
|
|
32
38
|
5. **Distinguish what you measured from what you inferred.** Label them. An
|
|
33
39
|
inference presented as an observation is the most expensive thing you can
|
|
34
40
|
hand back, because it survives review by sounding like a fact.
|
package/bin/tyran.mjs
CHANGED
|
@@ -56,6 +56,14 @@ export const COMMANDS = {
|
|
|
56
56
|
'scan-repo.mjs',
|
|
57
57
|
'Deterministic repo scan for /tyran:setup — establishes what it can, marks what needs confirmation, never guesses.',
|
|
58
58
|
],
|
|
59
|
+
'ensure-gitleaks': [
|
|
60
|
+
'ensure-gitleaks.mjs',
|
|
61
|
+
'Install the pinned, checksummed gitleaks the secrets gate needs, for a machine that has none.',
|
|
62
|
+
],
|
|
63
|
+
migrate: [
|
|
64
|
+
'migrate.mjs',
|
|
65
|
+
'Move a pre-0.1.9 .tyran/initiatives/ directory under state/. Previews by default; never overwrites.',
|
|
66
|
+
],
|
|
59
67
|
tiers: [
|
|
60
68
|
'tiers.mjs',
|
|
61
69
|
'Resolve a Tyran role to a model alias via .tyran/config.yaml, the one place model names are allowed to live.',
|
|
@@ -234,7 +234,28 @@ export const SECRET_READ_RULES = Object.freeze([
|
|
|
234
234
|
match: (b) => /^\.env(\.[^/]*)?$/i.test(b) && !/\.(example|sample|template|dist|defaults?|schema)$/i.test(b),
|
|
235
235
|
},
|
|
236
236
|
{ id: 'private-key-file', on: 'basename', match: (b) => /\.(pem|key|p12|pfx|jks|keystore|kdbx|asc|ppk)$/i.test(b) },
|
|
237
|
-
|
|
237
|
+
// Anchored on OpenSSH's actual key-type names. `^id_[a-z0-9]+$` was really
|
|
238
|
+
// "any identifier starting with id_", and because `shellPathFindings` runs
|
|
239
|
+
// these rules over every literal WORD of a command — not only over things
|
|
240
|
+
// shaped like paths — it refused `ID_ISSUED`, `ID_TOKEN`, `ID_SPEND`, and
|
|
241
|
+
// any other SCREAMING_SNAKE constant in that namespace. Measured live: a
|
|
242
|
+
// grep for `ID_ISSUED` was refused as an ssh private key.
|
|
243
|
+
//
|
|
244
|
+
// `_sk` covers FIDO/hardware keys; the trailing group covers the very common
|
|
245
|
+
// per-host naming (`id_rsa_github`, `id_ed25519_work`, `id_rsa-personal`).
|
|
246
|
+
// Case-folding stays: on macOS and Windows `ID_RSA` and `id_rsa` are one
|
|
247
|
+
// file, and dropping /i would let a rename walk past this rule.
|
|
248
|
+
//
|
|
249
|
+
// DECLARED COST: a private key with a non-algorithm stem — `id_deploy`,
|
|
250
|
+
// `id_ci` — no longer matches HERE. Inside any `.ssh/` directory the
|
|
251
|
+
// `ssh-directory` rule below still catches it, and the secrets gate still
|
|
252
|
+
// catches the key's BYTES at commit and push. This list is a denylist and
|
|
253
|
+
// has always been documented as incomplete.
|
|
254
|
+
{
|
|
255
|
+
id: 'ssh-private-key',
|
|
256
|
+
on: 'basename',
|
|
257
|
+
match: (b) => /^id_(rsa1?|dsa|ecdsa|ed25519|xmss)(_sk)?([_-][a-z0-9_-]+)?$/i.test(b),
|
|
258
|
+
},
|
|
238
259
|
{ id: 'credentials-file', on: 'basename', match: (b) => /^\.?credentials(\.[a-z0-9]+)?$/i.test(b) },
|
|
239
260
|
{ id: 'netrc', on: 'basename', match: (b) => /^_?\.?netrc$/i.test(b) },
|
|
240
261
|
{ id: 'registry-auth', on: 'basename', match: (b) => /^\.(npmrc|pypirc|pgpass|dockercfg)$/i.test(b) },
|