@jjanczur/tyran 0.1.32 → 0.1.34
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 +149 -0
- package/README.md +1 -1
- package/hooks/scripts/session-start.mjs +89 -3
- package/package.json +1 -1
- package/scripts/board-daemon.mjs +412 -0
- package/scripts/board-html.mjs +123 -0
- package/scripts/board.mjs +180 -13
- package/scripts/doctor.mjs +12 -1
- package/scripts/overnight.mjs +24 -2
- package/scripts/project.mjs +35 -1
- package/scripts/scan-repo.mjs +14 -0
- package/scripts/schema.mjs +51 -1
- package/skills/run/SKILL.md +26 -0
- package/skills/setup/SKILL.md +14 -3
- package/templates/config.yaml +18 -0
|
@@ -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.34",
|
|
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.34",
|
|
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,154 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.34 — 2026-08-17
|
|
4
|
+
|
|
5
|
+
### The dashboard starts itself
|
|
6
|
+
|
|
7
|
+
The board was reachable only by a human typing a command that never returns.
|
|
8
|
+
On every install where nobody typed it, each projection Tyran writes was
|
|
9
|
+
generated and read by no one.
|
|
10
|
+
|
|
11
|
+
`board.mjs --serve` blocks forever, which is right for an operator at a prompt
|
|
12
|
+
and fatal for everything else. Setup's "turn the dashboard on" step handed an
|
|
13
|
+
**agent** that command: measured, still listening three seconds after spawn
|
|
14
|
+
with nothing to return — so the tool call sat until the platform's timeout and
|
|
15
|
+
setup's remaining steps (validate, report, ask for the `.tyran/` commit)
|
|
16
|
+
silently never ran.
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
node scripts/board.mjs --dir .tyran --detach --write # returns; prints the URL
|
|
20
|
+
node scripts/board.mjs --dir .tyran --status # where is it?
|
|
21
|
+
node scripts/board.mjs --dir .tyran --stop
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`--detach` is the same server, waited on only until it answers. A new `board:`
|
|
25
|
+
block in `.tyran/config.yaml` defaults `autostart: true`, so every session
|
|
26
|
+
brings the board up if it is not already running and prints the URL in its
|
|
27
|
+
opening summary. `limits:` defaults off because off is *inert*; a board that
|
|
28
|
+
never starts is not.
|
|
29
|
+
|
|
30
|
+
**Liveness is an HTTP question, never a recorded pid.** `/health.json` names
|
|
31
|
+
the `.tyran` directory it serves, and a caller believes it only if that
|
|
32
|
+
directory is its own. Both halves are load-bearing: a pid written by one
|
|
33
|
+
process and read by another is dead before it is read and, once the OS
|
|
34
|
+
recycles the number, names a stranger — while probing only the *port* finds a
|
|
35
|
+
**different repository's** board (same program, same route) and concludes this
|
|
36
|
+
one is already up, so it never starts. Ports walk 4173–4182, so several repos
|
|
37
|
+
each get their own.
|
|
38
|
+
|
|
39
|
+
`TYRAN_NO_BOARD=1` turns it off machine-wide, for CI: an automated run clones a
|
|
40
|
+
repository whose committed config says `autostart: true`, has no browser and no
|
|
41
|
+
operator, and a detached server started by a build outlives the build.
|
|
42
|
+
|
|
43
|
+
### The commit, the reviewer and the model reach the card
|
|
44
|
+
|
|
45
|
+
Measured across **387 real journals and 1799 lane cards**: 1243 carried a merge
|
|
46
|
+
sha and 1074 a review verdict that no surface displayed.
|
|
47
|
+
|
|
48
|
+
Nothing looked broken because the **lane encoded them** — `done` means merged,
|
|
49
|
+
`changes-requested` means a non-approving review. The board was right, and
|
|
50
|
+
could not show its work. Selecting a card now shows the commit, the reviewer
|
|
51
|
+
and when, plus an **Execution** table: agent, model, start, verdict. That last
|
|
52
|
+
column is the half of "what did this cost me" the Spend tab cannot answer —
|
|
53
|
+
Spend gives dollars per ticket, this gives what was spawned to earn them.
|
|
54
|
+
|
|
55
|
+
The worst real `board.json` grows 57 KiB → 84 KiB. `BOARD.md` is byte-unchanged.
|
|
56
|
+
|
|
57
|
+
**Upgrading: one expected `--check` drift**, the same shape as 0.1.33's. Cards
|
|
58
|
+
gain `review`, `merge` and `execution`, so a `board.json` committed by an
|
|
59
|
+
earlier version no longer matches. Clear it with one regenerate:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
node scripts/board.mjs --dir .tyran # then commit the three artefacts
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`doctor --state` is silent about it; the only surface is an explicit `--check`.
|
|
66
|
+
|
|
67
|
+
### A feature deliberately not shipped, and the measurement that killed it
|
|
68
|
+
|
|
69
|
+
While specifying a `spawn-silent` doctor finding — an open agent that has
|
|
70
|
+
never said anything — the count came first. Across 388 real journals the
|
|
71
|
+
`progress` event appears **once**, against an instruction in
|
|
72
|
+
`agents/implementer.md` asking for four per story (roughly 6000 expected
|
|
73
|
+
against 1532 spawns).
|
|
74
|
+
|
|
75
|
+
So `spawn-silent` would fire on 100% of open spawns: the always-on warning
|
|
76
|
+
`SEVERITY_BY_CODE` already refuses by name. It is not shipped.
|
|
77
|
+
|
|
78
|
+
Agents are not ignoring the journal — 5302 gates and 4585 decisions — and not
|
|
79
|
+
ignoring that file: the `lease.acquired` instruction one bullet above produced
|
|
80
|
+
434 events. Four shipped features rest on the dead event and are inert on every
|
|
81
|
+
real install: `spawn-blocked`, the `blocked` lane, the agent chip's state, and
|
|
82
|
+
the signal half of "signal is not evidence". `NOTES-REQUESTS.md` §11 records
|
|
83
|
+
three options and the measurement that would decide between them.
|
|
84
|
+
|
|
85
|
+
## 0.1.33 — 2026-08-17
|
|
86
|
+
|
|
87
|
+
### The board was hiding what its own journal already knew
|
|
88
|
+
|
|
89
|
+
Three directory slugs and one blended percentage. The journal has carried a
|
|
90
|
+
written title since it existed — "The kanban board: one screen that answers
|
|
91
|
+
what is going on" — and `crossBoard` summed every initiative's progress before
|
|
92
|
+
throwing the parts away, so an operator reading "47%" across three slugs could
|
|
93
|
+
not tell which was nearly done from which had not started.
|
|
94
|
+
|
|
95
|
+
Each initiative now has its own row: title, progress, and how many questions
|
|
96
|
+
it is waiting on. The payload reads no clock — it ships `last_ts` and the page
|
|
97
|
+
ages it — so `board.mjs --check` stays byte-exact.
|
|
98
|
+
|
|
99
|
+
**This replaced an archive feature, on measurement.** Across 63 distinct real
|
|
100
|
+
journals only 6 were finished-and-archivable while **43 were waiting on a
|
|
101
|
+
question nobody had answered**. The board was never cluttered with completed
|
|
102
|
+
work; it was full of ABANDONED work. Archiving would have touched under 10% of
|
|
103
|
+
initiatives, left the 64-initiative ceiling exactly where it is, and — since
|
|
104
|
+
archivable means 100% merged — pulled the headline percentage DOWN.
|
|
105
|
+
|
|
106
|
+
**Upgrading: one expected `--check` drift.** The payload gains a top-level
|
|
107
|
+
`initiatives` key, so a `board.json` committed by an earlier version no longer
|
|
108
|
+
matches what this one generates. Measured: `board.mjs --check` exits 1 once on
|
|
109
|
+
an upgraded install and 0 after a single regenerate —
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
node scripts/board.mjs --dir .tyran # then commit the three artefacts
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
`doctor --state` is silent about it either way; the only surface is an
|
|
116
|
+
explicit `--check`, which matters if you run one in CI. The board `schema`
|
|
117
|
+
stays 1 because nothing about the existing keys changed, the same call made
|
|
118
|
+
when `errors_logged` was added.
|
|
119
|
+
|
|
120
|
+
### Two more things that had never worked and said nothing
|
|
121
|
+
|
|
122
|
+
- **`/run.json` never carried a reset time.** `pickWindow` tested
|
|
123
|
+
`typeof resets_at === 'string'` while every writer produces epoch SECONDS,
|
|
124
|
+
so it returned null for every real payload it was ever given: the run panel
|
|
125
|
+
could say a pause was in force but never when it would end. Live since the
|
|
126
|
+
feature shipped.
|
|
127
|
+
- **The closing checkpoint had no producer.** The projection has closed every
|
|
128
|
+
still-open spawn on `checkpoint phase=closed` since 0.1.31, and nothing ever
|
|
129
|
+
emitted one — 9 of 63 real journals had one. So an agent that finished weeks
|
|
130
|
+
ago still read as live work. The conductor is now told to write it, including
|
|
131
|
+
when an initiative ends because it was ABANDONED, and the test executes the
|
|
132
|
+
command rather than grepping for it.
|
|
133
|
+
|
|
134
|
+
`runState` also reports `limits_mode`: "the gate cannot see" and "the feature
|
|
135
|
+
was never switched on" are different facts with the same symptom.
|
|
136
|
+
|
|
137
|
+
### An ask offers its recommendation as one click
|
|
138
|
+
|
|
139
|
+
It was shown as text, and the only way to accept it was to retype it into the
|
|
140
|
+
box beneath it. For an operator who is not an engineer, that gap was most of
|
|
141
|
+
the difficulty of the page. The button fills the box rather than submitting,
|
|
142
|
+
so the wording stays editable and the answer stays deliberate.
|
|
143
|
+
|
|
144
|
+
### Findings are pointed at, not copied
|
|
145
|
+
|
|
146
|
+
Measured across 63 distinct journals: 3 carry any finding, 49 in total, and
|
|
147
|
+
none names a ticket — so they cannot enrich a card. Median claim is 429
|
|
148
|
+
characters and `STATE.md` already renders the full table. The initiative row
|
|
149
|
+
carries a count when it is non-zero and nothing else; a test forbids `claim`
|
|
150
|
+
or `proof` reaching the byte-compared payload.
|
|
151
|
+
|
|
3
152
|
## 0.1.32 — 2026-08-17
|
|
4
153
|
|
|
5
154
|
### Overnight mode could never fire, on any install
|
package/README.md
CHANGED
|
@@ -309,7 +309,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
|
|
|
309
309
|
fires and who invokes it, is in
|
|
310
310
|
[skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
|
|
311
311
|
themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
|
|
312
|
-
it:
|
|
312
|
+
it: 1569 unit tests, run with `node --test "tests/**/*.test.mjs"`.
|
|
313
313
|
|
|
314
314
|
## Documentation
|
|
315
315
|
|
|
@@ -26,6 +26,9 @@ import { checkHooks } from '../../scripts/hooks-check.mjs';
|
|
|
26
26
|
import { readJournal } from '../../scripts/journal.mjs';
|
|
27
27
|
import { SESSION_ID_RE } from '../../scripts/overnight.mjs';
|
|
28
28
|
import { fold, inlinePlain, progressLine } from '../../scripts/project.mjs';
|
|
29
|
+
import { findLiveServer, startDetachedNoWait, urlFor } from '../../scripts/board-daemon.mjs';
|
|
30
|
+
import { boardSettings } from '../../scripts/schema.mjs';
|
|
31
|
+
import { parse as parseYaml } from '../../scripts/yaml-lite.mjs';
|
|
29
32
|
import { field, main, runProbe } from './hook-io.mjs';
|
|
30
33
|
|
|
31
34
|
const HERE = dirname(fileURLToPath(import.meta.url));
|
|
@@ -169,14 +172,18 @@ function rows(list, render) {
|
|
|
169
172
|
* 120 characters under the platform's hard ceiling. Escaping first means the
|
|
170
173
|
* length fitBudget sees is the length that ships.
|
|
171
174
|
*/
|
|
172
|
-
export function renderContext({ repoRoot, initiatives, doctor, hardware, nowIso, pause = null }) {
|
|
173
|
-
if (initiatives.length === 0 && pause === null) return '';
|
|
175
|
+
export function renderContext({ repoRoot, initiatives, doctor, hardware, nowIso, pause = null, board = null }) {
|
|
176
|
+
if (initiatives.length === 0 && pause === null && board === null) return '';
|
|
174
177
|
const lines = [
|
|
175
178
|
'## Tyran state (injected by the session-start probe)',
|
|
176
179
|
'',
|
|
177
180
|
`Repo: ${inlinePlain(repoRoot)} · as of ${inlinePlain(nowIso)}`,
|
|
178
181
|
`Machine: ${inlinePlain(hardware)}`,
|
|
179
182
|
];
|
|
183
|
+
// In the HEADER for the same reason the pause notice is: `fitBudget` drops
|
|
184
|
+
// whole sections from the END, and the URL is the one line a reader wants
|
|
185
|
+
// from a repo with enough state to overflow the budget.
|
|
186
|
+
if (board !== null) lines.push(renderBoardLine(board));
|
|
180
187
|
// The pause notice lives in the HEADER, before any `### ` section, because
|
|
181
188
|
// fitBudget always keeps the preamble and drops sections from the end — a
|
|
182
189
|
// paused session must never lose the one line that says why it is paused.
|
|
@@ -401,6 +408,71 @@ export function recordConductor(stateDir, input, { now = new Date(), cwd = null
|
|
|
401
408
|
}
|
|
402
409
|
}
|
|
403
410
|
|
|
411
|
+
/**
|
|
412
|
+
* Start the dashboard, if it is not already up and the repo has not said no.
|
|
413
|
+
*
|
|
414
|
+
* This is the step that makes the board something an install HAS rather than
|
|
415
|
+
* something an operator remembers to run. Before it, the board was reached
|
|
416
|
+
* only by typing a command that holds a terminal, so on any install where
|
|
417
|
+
* nobody typed it every projection Tyran writes existed and nothing ever
|
|
418
|
+
* displayed them.
|
|
419
|
+
*
|
|
420
|
+
* Three properties, each of which the obvious implementation gets wrong:
|
|
421
|
+
*
|
|
422
|
+
* - it does NOT wait. `startDetachedNoWait` spawns and returns. This probe's
|
|
423
|
+
* whole budget is 4 s, already shared with doctor, and confirming a
|
|
424
|
+
* convenience would cost the user their session summary on a slow machine.
|
|
425
|
+
* The next session finds the server through `findLiveServer` and says so.
|
|
426
|
+
* - it asks whether one is running FIRST, over HTTP, scoped to this
|
|
427
|
+
* directory — so repeated sessions, `resume` and `compact` do not stack up
|
|
428
|
+
* servers, and another repo's board is never mistaken for this one's.
|
|
429
|
+
* - every failure is silent and returns a state, never an exception: a probe
|
|
430
|
+
* may not cost a session (ADR-22).
|
|
431
|
+
*
|
|
432
|
+
* Returns what to tell the reader, or null to say nothing at all.
|
|
433
|
+
*/
|
|
434
|
+
export async function ensureBoard(stateDir, { settings = null, find = findLiveServer, start = startDetachedNoWait, env = process.env } = {}) {
|
|
435
|
+
try {
|
|
436
|
+
// A machine-wide off switch, above the per-repo config. CI is the case
|
|
437
|
+
// that needs it: an automated run has no browser, no operator and no
|
|
438
|
+
// interest in a dashboard, but it does clone repositories whose committed
|
|
439
|
+
// config says `autostart: true` — and a detached server started by a
|
|
440
|
+
// build outlives the build. Also the honest way for this repository's own
|
|
441
|
+
// end-to-end tests to run the real hook without leaking a server per test.
|
|
442
|
+
if (env.TYRAN_NO_BOARD === '1') return null;
|
|
443
|
+
const board = settings ?? boardSettings(readConfigDoc(stateDir));
|
|
444
|
+
if (board.autostart === false) return null;
|
|
445
|
+
const live = await find(stateDir, board.port);
|
|
446
|
+
if (live !== null) return { running: true, port: live.port, url: urlFor(live.port) };
|
|
447
|
+
// The port it actually chose, not the one asked for: with several repos
|
|
448
|
+
// open at once the preferred one is routinely taken, and printing a URL
|
|
449
|
+
// that belongs to a different repository's board is worse than silence.
|
|
450
|
+
const chosen = await start(stateDir, { port: board.port, write: board.write });
|
|
451
|
+
return chosen === null ? null : { running: false, port: chosen, url: urlFor(chosen) };
|
|
452
|
+
} catch {
|
|
453
|
+
return null; // a dashboard that could not start is not worth a failed session
|
|
454
|
+
}
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
/** This repo's config, parsed, or null — every failure reads as "no config". */
|
|
458
|
+
function readConfigDoc(stateDir) {
|
|
459
|
+
try {
|
|
460
|
+
const path = join(stateDir, 'config.yaml');
|
|
461
|
+
if (!existsSync(path)) return null;
|
|
462
|
+
return parseYaml(readFileSync(path, 'utf8'));
|
|
463
|
+
} catch {
|
|
464
|
+
return null;
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
/** One line telling the operator where the board is. */
|
|
469
|
+
export function renderBoardLine(board) {
|
|
470
|
+
if (board === null) return '';
|
|
471
|
+
return board.running
|
|
472
|
+
? `Dashboard: ${inlinePlain(board.url)}`
|
|
473
|
+
: `Dashboard: starting at ${inlinePlain(board.url)} (give it a moment)`;
|
|
474
|
+
}
|
|
475
|
+
|
|
404
476
|
/** The pause marker, if one is active. Garbage reads as absent. */
|
|
405
477
|
export function readPauseMarker(stateDir) {
|
|
406
478
|
try {
|
|
@@ -413,7 +485,19 @@ export function readPauseMarker(stateDir) {
|
|
|
413
485
|
}
|
|
414
486
|
}
|
|
415
487
|
|
|
416
|
-
|
|
488
|
+
/**
|
|
489
|
+
* `ensure` is injectable and that is not a testing nicety — it is the seam
|
|
490
|
+
* that keeps a test suite from spawning servers.
|
|
491
|
+
*
|
|
492
|
+
* Every call of this function against a directory that has a `.tyran/` starts
|
|
493
|
+
* a detached board for it, and a test's temp directory is a NEW directory
|
|
494
|
+
* every time, so the idempotence that makes this safe in a real repo (one
|
|
495
|
+
* repo, one board) does not apply: each run leaves another live server behind
|
|
496
|
+
* it. Measured after adding autostart without this parameter — ten orphaned
|
|
497
|
+
* servers holding ports 4173-4182, the entire search span, which then made an
|
|
498
|
+
* unrelated test fail because no port was left to bind.
|
|
499
|
+
*/
|
|
500
|
+
export async function buildContext({ input, now = new Date(), env = process.env, health = hookHealth, ensure = ensureBoard } = {}) {
|
|
417
501
|
// Said even in a repository that has nothing to do with Tyran: the claim
|
|
418
502
|
// being corrected is about the PLUGIN the user installed, not about this
|
|
419
503
|
// project's state, and a user whose gates are dead needs to hear it in the
|
|
@@ -425,6 +509,7 @@ export async function buildContext({ input, now = new Date(), env = process.env,
|
|
|
425
509
|
if (!existsSync(stateDir)) return fitBudget(warning); // not a Tyran repo — but a dead gate still counts
|
|
426
510
|
recordConductor(stateDir, input, { now, cwd: repoRoot });
|
|
427
511
|
const nowIso = now.toISOString();
|
|
512
|
+
const board = await ensure(stateDir);
|
|
428
513
|
return fitBudget(
|
|
429
514
|
warning +
|
|
430
515
|
renderContext({
|
|
@@ -434,6 +519,7 @@ export async function buildContext({ input, now = new Date(), env = process.env,
|
|
|
434
519
|
hardware: hardwareLine(),
|
|
435
520
|
nowIso,
|
|
436
521
|
pause: readPauseMarker(stateDir),
|
|
522
|
+
board,
|
|
437
523
|
}),
|
|
438
524
|
);
|
|
439
525
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jjanczur/tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.34",
|
|
4
4
|
"description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|