@jjanczur/tyran 0.1.31 → 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.
@@ -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.31",
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.31",
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,297 @@
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
+
3
295
  ## 0.1.31 — 2026-08-17
4
296
 
5
297
  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. Money
127
- appears only under a rate card you write: Tyran does not know what you pay.
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
- Inside Claude Code:
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: 1451 unit tests, run with `node --test "tests/**/*.test.mjs"`.
312
+ it: 1526 unit tests, run with `node --test "tests/**/*.test.mjs"`.
301
313
 
302
314
  ## Documentation
303
315
 
@@ -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 a binary APPROVE or CHANGES-REQUESTED with numbered, executable counterexamples. Never reviews its own code.
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 have no editing tools on purpose: a reviewer who can fix what they found
13
- ends up approving their own patch. This removes the easy path, not every path
14
- — `Bash` can still write — so treat it as a boundary you keep, not a wall
15
- that keeps you.
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 binary.** APPROVE, with minor notes routed to `NOTES.md`;
51
- or CHANGES-REQUESTED with a numbered list — what, where, why. No
52
- generalities.
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
- { id: 'ssh-private-key', on: 'basename', match: (b) => /^id_[a-z0-9]+$/i.test(b) },
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) },