@jjanczur/tyran 0.1.31 → 0.1.33
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 +359 -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 +217 -7
- package/scripts/board.mjs +97 -7
- package/scripts/cost.mjs +392 -23
- package/scripts/doctor.mjs +155 -9
- package/scripts/ensure-gitleaks.mjs +254 -0
- package/scripts/journal.mjs +39 -2
- package/scripts/knowledge.mjs +89 -2
- package/scripts/overnight.mjs +26 -4
- package/scripts/pricing.mjs +255 -0
- 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/run/SKILL.md +26 -0
- 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.33",
|
|
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.33",
|
|
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,364 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.33 — 2026-08-17
|
|
4
|
+
|
|
5
|
+
### The board was hiding what its own journal already knew
|
|
6
|
+
|
|
7
|
+
Three directory slugs and one blended percentage. The journal has carried a
|
|
8
|
+
written title since it existed — "The kanban board: one screen that answers
|
|
9
|
+
what is going on" — and `crossBoard` summed every initiative's progress before
|
|
10
|
+
throwing the parts away, so an operator reading "47%" across three slugs could
|
|
11
|
+
not tell which was nearly done from which had not started.
|
|
12
|
+
|
|
13
|
+
Each initiative now has its own row: title, progress, and how many questions
|
|
14
|
+
it is waiting on. The payload reads no clock — it ships `last_ts` and the page
|
|
15
|
+
ages it — so `board.mjs --check` stays byte-exact.
|
|
16
|
+
|
|
17
|
+
**This replaced an archive feature, on measurement.** Across 63 distinct real
|
|
18
|
+
journals only 6 were finished-and-archivable while **43 were waiting on a
|
|
19
|
+
question nobody had answered**. The board was never cluttered with completed
|
|
20
|
+
work; it was full of ABANDONED work. Archiving would have touched under 10% of
|
|
21
|
+
initiatives, left the 64-initiative ceiling exactly where it is, and — since
|
|
22
|
+
archivable means 100% merged — pulled the headline percentage DOWN.
|
|
23
|
+
|
|
24
|
+
**Upgrading: one expected `--check` drift.** The payload gains a top-level
|
|
25
|
+
`initiatives` key, so a `board.json` committed by an earlier version no longer
|
|
26
|
+
matches what this one generates. Measured: `board.mjs --check` exits 1 once on
|
|
27
|
+
an upgraded install and 0 after a single regenerate —
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
node scripts/board.mjs --dir .tyran # then commit the three artefacts
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`doctor --state` is silent about it either way; the only surface is an
|
|
34
|
+
explicit `--check`, which matters if you run one in CI. The board `schema`
|
|
35
|
+
stays 1 because nothing about the existing keys changed, the same call made
|
|
36
|
+
when `errors_logged` was added.
|
|
37
|
+
|
|
38
|
+
### Two more things that had never worked and said nothing
|
|
39
|
+
|
|
40
|
+
- **`/run.json` never carried a reset time.** `pickWindow` tested
|
|
41
|
+
`typeof resets_at === 'string'` while every writer produces epoch SECONDS,
|
|
42
|
+
so it returned null for every real payload it was ever given: the run panel
|
|
43
|
+
could say a pause was in force but never when it would end. Live since the
|
|
44
|
+
feature shipped.
|
|
45
|
+
- **The closing checkpoint had no producer.** The projection has closed every
|
|
46
|
+
still-open spawn on `checkpoint phase=closed` since 0.1.31, and nothing ever
|
|
47
|
+
emitted one — 9 of 63 real journals had one. So an agent that finished weeks
|
|
48
|
+
ago still read as live work. The conductor is now told to write it, including
|
|
49
|
+
when an initiative ends because it was ABANDONED, and the test executes the
|
|
50
|
+
command rather than grepping for it.
|
|
51
|
+
|
|
52
|
+
`runState` also reports `limits_mode`: "the gate cannot see" and "the feature
|
|
53
|
+
was never switched on" are different facts with the same symptom.
|
|
54
|
+
|
|
55
|
+
### An ask offers its recommendation as one click
|
|
56
|
+
|
|
57
|
+
It was shown as text, and the only way to accept it was to retype it into the
|
|
58
|
+
box beneath it. For an operator who is not an engineer, that gap was most of
|
|
59
|
+
the difficulty of the page. The button fills the box rather than submitting,
|
|
60
|
+
so the wording stays editable and the answer stays deliberate.
|
|
61
|
+
|
|
62
|
+
### Findings are pointed at, not copied
|
|
63
|
+
|
|
64
|
+
Measured across 63 distinct journals: 3 carry any finding, 49 in total, and
|
|
65
|
+
none names a ticket — so they cannot enrich a card. Median claim is 429
|
|
66
|
+
characters and `STATE.md` already renders the full table. The initiative row
|
|
67
|
+
carries a count when it is non-zero and nothing else; a test forbids `claim`
|
|
68
|
+
or `proof` reaching the byte-compared payload.
|
|
69
|
+
|
|
70
|
+
## 0.1.32 — 2026-08-17
|
|
71
|
+
|
|
72
|
+
### Overnight mode could never fire, on any install
|
|
73
|
+
|
|
74
|
+
The pause depended on `.tyran/state/usage.json`; only the statusline writes
|
|
75
|
+
it; the statusline writes only when the platform payload carries
|
|
76
|
+
`rate_limits`; and that block is not always sent. Measured on an install
|
|
77
|
+
running `limits: mode: 'pause'` — **no sidecar had ever been written anywhere
|
|
78
|
+
on the machine**, so the configured pause had never once been able to fire.
|
|
79
|
+
The gate fails open, which is why nothing ever said so.
|
|
80
|
+
|
|
81
|
+
The gate now falls back to the platform's own cache in `~/.claude.json`, which
|
|
82
|
+
also removes the one onboarding step no script can perform: registering a
|
|
83
|
+
statusline means writing the operator's settings file, and the plugin is
|
|
84
|
+
refused there by design.
|
|
85
|
+
|
|
86
|
+
**A stale reading is acted on, deliberately.** That cache is refreshed on the
|
|
87
|
+
platform's schedule — measured 83 minutes old during continuous heavy use — so
|
|
88
|
+
under the gate's ten-minute freshness rule it would be discarded every time.
|
|
89
|
+
It is sound because usage inside a window only ever goes UP: a reading taken
|
|
90
|
+
inside the window that is still running is a LOWER BOUND on usage now. If it
|
|
91
|
+
already says 97%, the truth is at least that and pausing is correct; if it
|
|
92
|
+
says less, the gate may fail to pause, which is exactly today's behaviour and
|
|
93
|
+
the safe direction. A reading whose own `resets_at` has passed is discarded —
|
|
94
|
+
that check is what makes the rest safe. Pauses derived this way record
|
|
95
|
+
`lower_bound: true`, because "at least 97%" is a reason to stop and never a
|
|
96
|
+
reason to start.
|
|
97
|
+
|
|
98
|
+
Verified against live telemetry: at the shipped 97% nothing trips (the account
|
|
99
|
+
was at 32%/68%); at a 30% test threshold the weekly window trips with the
|
|
100
|
+
correct resume time.
|
|
101
|
+
|
|
102
|
+
`SIDECAR_RELPATH` had three spellings and `SIDECAR_FRESH_MS` two, across the
|
|
103
|
+
writer, the scheduler and the gate. Nothing fails while they agree, and when
|
|
104
|
+
they stop agreeing the symptom is a pause that silently never fires — the bug
|
|
105
|
+
above. They collapse into `scripts/usage-source.mjs`.
|
|
106
|
+
|
|
107
|
+
Only the two usage windows are read from that file. It also holds the account
|
|
108
|
+
uuid and the email address; a test asserts neither reaches the output.
|
|
109
|
+
|
|
110
|
+
### Three lifecycle leaks, each measured on real journals first
|
|
111
|
+
|
|
112
|
+
- **`lease-expired` was dead code that looked alive.** It read
|
|
113
|
+
`expires`/`expires_at`/`until`; across every journal on a real machine agents
|
|
114
|
+
wrote **`expiry` 33 times against `expires` 3**, so 33 of 36 recorded
|
|
115
|
+
expiries were invisible.
|
|
116
|
+
- **The schema flagged the field that would have made it work.** No expiry
|
|
117
|
+
spelling was in `DATA_KNOWN`, so recording one tripped `journal-key-unread`
|
|
118
|
+
— the ledger reporting an agent's own diligence back as an anomaly. Same for
|
|
119
|
+
the descriptions agents attach: `purpose` 28, `story` 21, `text` 21.
|
|
120
|
+
- **Worktrees accumulate and nothing had ever looked.** No removal path exists
|
|
121
|
+
in any skill, agent or script, and the journal has no event that can
|
|
122
|
+
represent one being destroyed. Measured: **26 worktrees in one repository,
|
|
123
|
+
33 GB under another's `.worktrees/`**. New `worktree-accumulating` warning
|
|
124
|
+
above a ceiling of 8 — a handful is the parallel model working as designed.
|
|
125
|
+
|
|
126
|
+
It **reports and does not remove**. Most of those worktrees hold work that
|
|
127
|
+
never CONCLUDED rather than work that finished, so removing the merged ones
|
|
128
|
+
would clear almost nothing while being able to delete something wanted.
|
|
129
|
+
|
|
130
|
+
### Spend answers "how much", with no configuration
|
|
131
|
+
|
|
132
|
+
The Spend tab could say how many tokens and never how much: `pricing:` was
|
|
133
|
+
hand-authored, the scanner never writes one, so absent was every install.
|
|
134
|
+
|
|
135
|
+
The published list prices now ship as `list-2026-08`. Cache rates are
|
|
136
|
+
published as fixed multiples of base input (1.25x, 2x, 0.1x), so only input
|
|
137
|
+
and output are written down and a test checks all fifteen rows against an
|
|
138
|
+
independently transcribed table. Overriding is per MODEL, not all-or-nothing.
|
|
139
|
+
|
|
140
|
+
This reverses an earlier rule — "Tyran does not know what anyone pays" — which
|
|
141
|
+
conflated two quantities. A subscriber's marginal cost is zero and unknowable;
|
|
142
|
+
what the tokens would list-price at on the API is published and fixed. The
|
|
143
|
+
reversal is conditional on the figure never claiming to be the other, so
|
|
144
|
+
`rate_card` still travels with every amount.
|
|
145
|
+
|
|
146
|
+
**Cache writes are billed at two rates and were counted as one.** A 1-hour
|
|
147
|
+
write costs 2x base input against a 5-minute write's 1.25x, and the transcripts
|
|
148
|
+
carry the split. Reading both the aggregate and the split would double-count,
|
|
149
|
+
so exactly one is read — verified across 1168 consecutive live records where
|
|
150
|
+
the two summed to the aggregate every time. Measured on 1.8 B real tokens: the
|
|
151
|
+
1-hour line is $175 against the 5-minute line's $70.
|
|
152
|
+
|
|
153
|
+
**A window you choose, because a plan is billed monthly.** `--window
|
|
154
|
+
30d|period|all`, and three buttons on the tab. `30d` is the default since it
|
|
155
|
+
needs nothing from the account; `period` runs from the subscription
|
|
156
|
+
anniversary and is offered only when that date is readable. The anniversary
|
|
157
|
+
arithmetic clamps short months — a subscription created on the 31st has no
|
|
158
|
+
31st in February, and naive maths yields a period that has not begun.
|
|
159
|
+
|
|
160
|
+
The plan price sits beside the API figure, and the multiple is shown only
|
|
161
|
+
under a month-shaped window: measured, an all-time total read as "6.9x what
|
|
162
|
+
you pay" where the honest monthly figure was about 11x.
|
|
163
|
+
|
|
164
|
+
**A per-day series**, which this page never had — every other view is a
|
|
165
|
+
snapshot, so nothing could answer "am I getting cheaper". It shows the full
|
|
166
|
+
history whatever window is selected, since a chart that shrank with the window
|
|
167
|
+
could not show you that last month was worse.
|
|
168
|
+
|
|
169
|
+
### The reviewer can fix what it finds
|
|
170
|
+
|
|
171
|
+
The property worth protecting was never "a reviewer cannot type" — it is that
|
|
172
|
+
nobody approves their own code, and those come apart. The reviewer holds
|
|
173
|
+
`Edit`, and the verdict is three-valued: a diff it touched can only come back
|
|
174
|
+
`REVISED`, which still owes a second read, and that read is cheap because the
|
|
175
|
+
fix is already written. No `Write` or `NotebookEdit`: authoring files is
|
|
176
|
+
designing, not reviewing.
|
|
177
|
+
|
|
178
|
+
An open operator ask now goes in the verdict LINE. Field-measured: a reviewer
|
|
179
|
+
raised a gate inside the body of an APPROVE, the conductor read the first
|
|
180
|
+
word, merged, and the question sat unanswered for thirty minutes.
|
|
181
|
+
|
|
182
|
+
**Subagents could not reach MCP at all.** `tools:` is an exhaustive allowlist,
|
|
183
|
+
so naming six built-ins silently stripped every `mcp__*` tool from the scout
|
|
184
|
+
and the reviewer — the scout's own description promises reconnaissance over
|
|
185
|
+
"its data", which was unreachable. Grants stay gated: write-guard's matcher
|
|
186
|
+
already carries `mcp__.*`.
|
|
187
|
+
|
|
188
|
+
### Two gate refusals that were wrong
|
|
189
|
+
|
|
190
|
+
- A backslash-escaped separator started a new segment, so `grep -nE 'A\|B' f`
|
|
191
|
+
split in two and an ordinary read was refused. `\<sep>` is never an operator
|
|
192
|
+
in any shell quoting context — verified against `/bin/sh` with a side-effect
|
|
193
|
+
oracle over 34 join constructions, zero divergences. The lexer stays
|
|
194
|
+
quote-BLIND on purpose: a naive quote tracker is broken by one apostrophe,
|
|
195
|
+
which swallows a `;` and makes a `git push` invisible to the deployment
|
|
196
|
+
check.
|
|
197
|
+
- `^id_[a-z0-9]+$` was really "any identifier starting with id_", and these
|
|
198
|
+
rules run over every literal WORD of a command — so `ID_ISSUED` and
|
|
199
|
+
`ID_TOKEN` were refused as ssh private keys. Now anchored on OpenSSH's own
|
|
200
|
+
key-type names, keeping hardware keys and per-host suffixes. Declared cost: a
|
|
201
|
+
key with an invented stem is no longer matched by name, though `.ssh/` still
|
|
202
|
+
catches it and so does gitleaks at push.
|
|
203
|
+
|
|
204
|
+
### Setup asks one question, in words a non-engineer can answer
|
|
205
|
+
|
|
206
|
+
Sales and marketing people run this now, and four entries shaped
|
|
207
|
+
`field: source` is where they stop. The scan carries a `plain` object: one
|
|
208
|
+
question, its evidence restated without jargon, at most two options, and a
|
|
209
|
+
list of what the repository already answered. P3 is not offered — a menu makes
|
|
210
|
+
every item look like a normal choice, and it stays something a person says in
|
|
211
|
+
their own words.
|
|
212
|
+
|
|
213
|
+
### Installation reaches the dashboard now
|
|
214
|
+
|
|
215
|
+
Install was four steps, a restart, and then a board nobody opened. Every one
|
|
216
|
+
of those is a place to stop, and the last one mattered most: `--serve` printed
|
|
217
|
+
a URL to a terminal and **nothing ever launched a browser**, so the screen
|
|
218
|
+
where Tyran becomes legible was the one thing installation never reached.
|
|
219
|
+
|
|
220
|
+
`install.sh` does everything a machine can:
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
curl -fsSL https://raw.githubusercontent.com/jjanczur/tyran/main/install.sh | sh
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Node version check first, because every hook shells out to `node` and an old
|
|
227
|
+
one does not fail at install time — it fails later as a gate that cannot run,
|
|
228
|
+
which is the hardest thing for a non-technical operator to read. Then the
|
|
229
|
+
plugin, then the pinned scanner, then the prompt to paste after the restart.
|
|
230
|
+
|
|
231
|
+
The restart is the one step that stays manual and it is not a shortcut not
|
|
232
|
+
taken: Claude Code loads plugins at startup and nothing inside a session can
|
|
233
|
+
make the app reload itself. So it is stated plainly and put last.
|
|
234
|
+
|
|
235
|
+
`board.mjs --serve --open` launches the browser, best-effort and never fatal —
|
|
236
|
+
a headless machine or an SSH session leaves the server running and the URL
|
|
237
|
+
printed, exactly where things were before. `--open` without `--serve` is a
|
|
238
|
+
usage error, like `--write`.
|
|
239
|
+
|
|
240
|
+
Setup gained two steps: install the scanner before anything needs it, and
|
|
241
|
+
**look for pre-existing secrets before the operator hits them**. A repository
|
|
242
|
+
whose history already holds a key is common, and the gate handles it badly by
|
|
243
|
+
surprise — nothing is scanned until someone edits that file, and then every
|
|
244
|
+
commit touching it is refused, permanently, for a reason years old. Setup now
|
|
245
|
+
says what is there and explains the choice, including the part that is easy to
|
|
246
|
+
leave out: a tracked baseline makes the tool quiet, it does not make the key
|
|
247
|
+
safe, and if the repo is public that key is already burned.
|
|
248
|
+
|
|
249
|
+
### The knowledge store was write-only, and nothing said so
|
|
250
|
+
|
|
251
|
+
Measured on a real install: `knowledge.mjs brief '**'` returned **1 of 31
|
|
252
|
+
entries**. The other thirty were dropped by the 4000-codepoint budget, and
|
|
253
|
+
104,178 codepoints of hard-won detail — migration-number races, TEST/PROD
|
|
254
|
+
schema drift, a deploy gate that silently blocks on the commit author — had
|
|
255
|
+
been accumulating for months and reaching nobody.
|
|
256
|
+
|
|
257
|
+
That is the opposite of the failure people expect from a growing store. It is
|
|
258
|
+
not expensive to read; it is **unread**, while growing without bound.
|
|
259
|
+
|
|
260
|
+
Every piece of the machinery was already correct and none of it added up. The
|
|
261
|
+
budget is deliberately the pressure that keeps entries scoped. Each brief
|
|
262
|
+
already names what it omitted. `doctor` already warned per oversized entry —
|
|
263
|
+
five times on that install. What nobody had was the total, and five local
|
|
264
|
+
tidy-up notes are not the same message as "your knowledge store is 97%
|
|
265
|
+
unread". Only the second one gets acted on.
|
|
266
|
+
|
|
267
|
+
`knowledge.mjs audit` reports it: how many entries could reach ONE brief, how
|
|
268
|
+
many could not, and — the diagnostic that matters most — which entries are so
|
|
269
|
+
wide they cannot appear **even alone**, where no budget any caller passes will
|
|
270
|
+
ever reach them. Eight of that install's thirty-one are in that state; the
|
|
271
|
+
widest is 10,210 codepoints, two and a half times the whole budget.
|
|
272
|
+
`doctor --state` carries the same number as `knowledge-store-unreachable`
|
|
273
|
+
(`info` — a store outgrows the budget in the ordinary course of being useful).
|
|
274
|
+
|
|
275
|
+
It measures and never edits. Which of two overlapping entries is the true one
|
|
276
|
+
is a judgement, and a script that guessed would delete exactly the detail the
|
|
277
|
+
store exists to hold — so consolidation is a retrospective step that writes a
|
|
278
|
+
**new** file for review and leaves the original untouched.
|
|
279
|
+
|
|
280
|
+
### The prerequisite that blocked day one
|
|
281
|
+
|
|
282
|
+
The secrets gate refuses every commit and push until `gitleaks` exists, and
|
|
283
|
+
it refuses rather than warning for a reason that has not changed. What had
|
|
284
|
+
been left with the operator is the *installing*: some people adopting Tyran
|
|
285
|
+
have no Homebrew, no admin rights, or are on Windows, and their realistic
|
|
286
|
+
answer to "install it and re-run" is not a safer repository — it is switching
|
|
287
|
+
the hook off. A gate nobody can satisfy protects nothing, which is the same
|
|
288
|
+
argument that made `.tyran/config.yaml` AUTO.
|
|
289
|
+
|
|
290
|
+
`scripts/ensure-gitleaks.mjs` fetches it: pinned version **and** pinned
|
|
291
|
+
SHA-256 per platform, taken from the release's own checksums, which is the
|
|
292
|
+
thing `ci.yml` has always done moved to where a user can reach it. A mismatch
|
|
293
|
+
deletes the download and installs nothing — this writes an executable that
|
|
294
|
+
something else later runs, and a scanner that has been replaced reports clean
|
|
295
|
+
on everything.
|
|
296
|
+
|
|
297
|
+
It installs to `~/.tyran/bin/`. The first version of this put it under
|
|
298
|
+
`<repo>/.tyran/bin/`, which is worse in a way worth recording: a path inside
|
|
299
|
+
the repository travels with a clone, so a planted binary reporting clean on
|
|
300
|
+
everything would arrive **with the checkout** — the attack the tracked-only
|
|
301
|
+
rule for `.gitleaksignore` already prevents, reopened through a file that is
|
|
302
|
+
not even in a diff. Under HOME the scanner is the operator's machine, exactly
|
|
303
|
+
like PATH, and one install serves every repository on it. PATH is still
|
|
304
|
+
consulted first: a gitleaks you installed yourself is never silently
|
|
305
|
+
displaced by whatever version this repo pins.
|
|
306
|
+
|
|
307
|
+
### Writing a prompt is now a top-tier job
|
|
308
|
+
|
|
309
|
+
`retro` was routed at `work` and reached `deep` only under `--profile full`,
|
|
310
|
+
so the agent that writes skills, agents and prompts — the text every later
|
|
311
|
+
session obeys — ran on the middle model, and `--profile eco` kept it there.
|
|
312
|
+
|
|
313
|
+
A new `authoring` role sits at `top` at every profile, with `top` and `max`
|
|
314
|
+
floors under it. Separated from `retro` rather than raising the whole of it,
|
|
315
|
+
because retro does two unlike things with one agent: folding a ledger, which
|
|
316
|
+
the middle model does fine, and authoring. The argument is `security-review`'s
|
|
317
|
+
in a stronger form — a bad security verdict costs one merge, while a bad
|
|
318
|
+
prompt misroutes every run that reads it for as long as it ships, and it is
|
|
319
|
+
the one output nothing downstream checks, because a skill that reads plausibly
|
|
320
|
+
passes review.
|
|
321
|
+
|
|
322
|
+
### A duplicate ledger id is refused
|
|
323
|
+
|
|
324
|
+
Measured in the field: two implementers running in parallel each worked out an
|
|
325
|
+
id for themselves, both were honoured, and the ledger kept two `F-7`s. History
|
|
326
|
+
is append-only, so "see F-7" stays ambiguous forever and nothing detects it
|
|
327
|
+
later.
|
|
328
|
+
|
|
329
|
+
`append` now refuses a caller-supplied `id` that is **already used for that
|
|
330
|
+
event type**. Deliberately not the broader fix of refusing every explicit id:
|
|
331
|
+
that removes a documented capability — an explicit id still wins, and a test
|
|
332
|
+
pins it — to prevent a failure that only occurs on collision. A fresh explicit
|
|
333
|
+
id still passes, `ticket.created` is unaffected because its ids come from the
|
|
334
|
+
plan, and the check runs under the write lock so two concurrent writers cannot
|
|
335
|
+
both pass it.
|
|
336
|
+
|
|
337
|
+
### Refusals you can paste
|
|
338
|
+
|
|
339
|
+
The multi-remote push refusal is correct — excluding commits present on ANY
|
|
340
|
+
remote let a key held on a private upstream reach a public origin unscanned —
|
|
341
|
+
but it was reported twice, from two installs, as a false positive, and both
|
|
342
|
+
reporters routed around it instead of satisfying it. The old text handed over
|
|
343
|
+
`git push <remote> <branch>`, a shape to translate rather than a line to run.
|
|
344
|
+
|
|
345
|
+
Everything needed to write the real command was already in hand, so it is
|
|
346
|
+
written: one runnable line per remote, with the branch filled in.
|
|
347
|
+
|
|
348
|
+
### Reviewers stop retyping evidence
|
|
349
|
+
|
|
350
|
+
`tyran:reviewer` has no MCP tools, so a database row or an API response
|
|
351
|
+
someone else fetched reaches it as text in a handoff — and text in a handoff
|
|
352
|
+
gets retyped. Measured on a production run: **1.6% of hand-copied values were
|
|
353
|
+
silently wrong**, which makes a reviewer that mistranscribes evidence worse
|
|
354
|
+
than no reviewer, because the verdict carries authority the numbers do not.
|
|
355
|
+
|
|
356
|
+
The roster is unchanged, because it cannot express the fix: `tools:` is a
|
|
357
|
+
static list shipped in the plugin and MCP tool names differ on every install.
|
|
358
|
+
The prompt closes it instead — require the raw bytes on disk and `Read` them,
|
|
359
|
+
rather than reasoning about a retyped copy. A value read from a file is
|
|
360
|
+
evidence; a value pasted into a sentence is a claim about evidence.
|
|
361
|
+
|
|
3
362
|
## 0.1.31 — 2026-08-17
|
|
4
363
|
|
|
5
364
|
Seven things the journal had recorded and nothing was reading. The theme is
|
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: 1535 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) },
|