@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.
@@ -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.32",
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.32",
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: 1526 unit tests, run with `node --test "tests/**/*.test.mjs"`.
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
- export async function buildContext({ input, now = new Date(), env = process.env, health = hookHealth } = {}) {
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.32",
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": {