@jjanczur/tyran 0.1.24 → 0.1.25

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.24",
14
+ "version": "0.1.25",
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.24",
3
+ "version": "0.1.25",
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,71 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.25 — 2026-08-15
4
+
5
+ ### The sandbox is now Tyran building Tyran
6
+
7
+ The published sample board was two invented initiatives about someone else's
8
+ payment system. It showed what the dashboard looked like and nothing about what
9
+ it is like to work this way, which is half of what a reader opens it for.
10
+
11
+ It now carries **three initiatives that actually built the board you are
12
+ looking at** — the lanes, overnight mode, and the Settings tab — written as
13
+ journals from the real work. Every finding on it is a finding that was made:
14
+ the artefact must never read a clock or `--check` can never pass twice; the
15
+ page must build DOM with `textContent` only, because journal values reach the
16
+ browser verbatim; the hook payload does not carry `rate_limits` and a plugin
17
+ cannot install a statusline. Every logged error is one that happened, including
18
+ the backtick in a comment that terminated the client's template literal.
19
+
20
+ All ten lanes are populated, five agents run at ages from two minutes to three
21
+ hours, two questions wait on the operator, and the banner's counts are read
22
+ from the payload rather than typed — it said "two invented initiatives" for a
23
+ release after a third was added.
24
+
25
+ ### Three findings while writing those journals, all in shipped code
26
+
27
+ - **Every reviewer on the published sandbox rendered as still running, for
28
+ ever.** A `review` closes its spawn by `data.by`; the sandbox journals said
29
+ `data.agent`, so no review ever closed anything and the headline agent count
30
+ was wrong on the one page whose job is to show what the product looks like.
31
+ - **The test that was supposed to catch that validated nothing.**
32
+ `validateJournal` takes a file PATH and the test handed it an array of
33
+ events, so it read an empty journal and returned `ok`. It has been passing
34
+ against journals carrying thirteen real errors.
35
+ - **An `error` event that named a ticket produced two rows on the board**, one
36
+ from `state.errors` and one from `unknownErrorTickets`. The ticket now
37
+ travels on the error itself, where a consumer that wants both can have both
38
+ without joining two lists by timestamp.
39
+
40
+ ### The board answers "is this supposed to be running?"
41
+
42
+ Three chips reading "6 HOURS since last signal — likely dead" covered four
43
+ unrelated situations and the board could tell them apart in none of them.
44
+
45
+ - **A STOP is on the board**, above everything else, carrying the first line of
46
+ `.tyran/STOP` as its reason. It is committed repo state, identical in every
47
+ clone, so it travels in the artefact — as `{stopped, reason}` and
48
+ deliberately not the path, which would make two clones disagree and fail
49
+ `--check`.
50
+ - **An error with no ticket is finally visible.** The fold has collected
51
+ `state.errors` since errors existed and the board carried neither it nor the
52
+ unknown-ticket list, so an agent logging a hard failure showed nothing at all
53
+ on the page that exists to say "not all is well". The key is
54
+ `errors_logged`, not `errors`: that name already means "this journal could
55
+ not be read", and one key with two meanings is the defect ADR-21 is named
56
+ after. Capped at 20 newest-first with the true count beside it, because this
57
+ artefact is committed.
58
+ - **Cards say how long they have stood still.** The board would tell you an
59
+ agent had been quiet for three hours and refuse to tell you a ticket had been
60
+ blocked for four days — the timestamp was in `board.json` all along. Only on
61
+ the lanes where standing still IS the defect: `backlog` and `ready` are
62
+ excluded, because an unstarted ticket is waiting its turn, and marking every
63
+ one of them stale makes the mark worthless where it means something.
64
+
65
+ All three use one staleness vocabulary, shared with the agent strip. Three
66
+ renderings of "how long ago" would let the same gap read as fine in one place
67
+ and alarming in another.
68
+
3
69
  ## 0.1.24 — 2026-08-15
4
70
 
5
71
  ### Settings: the board can now change what Tyran does
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.24",
3
+ "version": "0.1.25",
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": {
@@ -140,6 +140,9 @@ h3{font-family:var(--font);color:var(--heading);font-size:.85rem;margin:1.1rem 0
140
140
  .card .id{font-family:var(--mono);color:var(--heading)}
141
141
  .card .init{font-family:var(--mono);color:var(--muted);font-size:.68rem}
142
142
  .card .note{color:var(--muted);font-size:.74rem;display:block}
143
+ .card .note.age-warm{color:var(--brass)}
144
+ .card .note.age-cold{color:var(--clay)}
145
+ .card .note.age-dead{color:var(--clay-bright);font-weight:600}
143
146
  .empty{color:var(--hairline);font-size:.78rem}
144
147
 
145
148
  /* ---- detail ---- */
@@ -368,6 +371,31 @@ if (data.schema !== 1) {
368
371
  return box;
369
372
  };
370
373
 
374
+ // One staleness vocabulary, used by the agent strip, the logged errors and
375
+ // the lane cards. Three renderings of "how long ago" would let the same
376
+ // gap read as fine in one place and alarming in another.
377
+ //
378
+ // This is the only clock on the page. The ARTEFACT never reads one — "as of"
379
+ // is the newest event timestamp, which is what keeps --check valid for the
380
+ // HTML — so every age here is computed in the reader's own browser.
381
+ var ageMsOf = function (ts) {
382
+ if (!ts) return null;
383
+ var t = Date.parse(ts);
384
+ return isNaN(t) ? null : Date.now() - t;
385
+ };
386
+ var ageClass = function (ms) {
387
+ if (ms === null) return 'age-cold';
388
+ return ms < 600000 ? 'age-fresh' : ms < 1800000 ? 'age-warm' : ms < 10800000 ? 'age-cold' : 'age-dead';
389
+ };
390
+ var ago = function (ts) {
391
+ var ms = ageMsOf(ts);
392
+ if (ms === null) return 'no time recorded';
393
+ if (ms < 60000) return 'just now';
394
+ if (ms < 3600000) return Math.round(ms / 60000) + ' min ago';
395
+ if (ms < 172800000) return Math.round(ms / 3600000) + ' h ago';
396
+ return Math.round(ms / 86400000) + ' d ago';
397
+ };
398
+
371
399
  var fmtTokens = function (n) {
372
400
  if (n >= 1e9) return (n / 1e9).toFixed(2) + ' B';
373
401
  if (n >= 1e6) return (n / 1e6).toFixed(1) + ' M';
@@ -395,15 +423,14 @@ if (data.schema !== 1) {
395
423
  // shown it — so the chip could say an agent went quiet without saying
396
424
  // what it went quiet in the middle of.
397
425
  if (a.next) chip.appendChild(el('div', 'note', 'next: ' + a.next));
398
- var ageMs = a.last_signal ? Date.now() - Date.parse(a.last_signal) : null;
399
- var cls = ageMs === null ? 'age-cold' : ageMs < 600000 ? 'age-fresh' : ageMs < 1800000 ? 'age-warm' : 'age-cold';
400
426
  // Four buckets, not three. The old top bucket was "30 minutes or six
401
427
  // hours", which are not the same event: one is a long test run, the
402
428
  // other is an agent that is not coming back.
429
+ var ageMs = ageMsOf(a.last_signal);
403
430
  var ageText = ageMs === null ? 'no signal recorded'
404
431
  : ageMs >= 10800000 ? Math.round(ageMs / 3600000) + ' HOURS since last signal — likely dead'
405
432
  : Math.round(ageMs / 60000) + ' min since last signal';
406
- chip.appendChild(el('div', ageMs !== null && ageMs >= 10800000 ? 'age-dead' : cls, ageText));
433
+ chip.appendChild(el('div', ageClass(ageMs), ageText));
407
434
  strip.appendChild(chip);
408
435
  });
409
436
  return strip;
@@ -411,6 +438,16 @@ if (data.schema !== 1) {
411
438
 
412
439
  // ---- overview ---------------------------------------------------------
413
440
  var ov = panels.overview;
441
+ // A STOP outranks everything, and it goes first. It is the one state in
442
+ // which a strip of silent agents is the system doing exactly as it was told,
443
+ // and without it that strip reads identically to a fleet that died.
444
+ if (data.stop && data.stop.stopped === true) {
445
+ var stopBox = el('div', 'paused');
446
+ stopBox.appendChild(el('b', null, 'STOPPED \\u2014 '));
447
+ stopBox.appendChild(el('span', null, 'an operator halted this repo: ' + (data.stop.reason || '(no reason given)')));
448
+ stopBox.appendChild(el('div', 'hint', 'Nothing new will be started until .tyran/STOP is deleted. Agents already running are not killed by it.'));
449
+ ov.appendChild(stopBox);
450
+ }
414
451
  (data.paused || []).forEach(function (p) {
415
452
  ov.appendChild(el('div', 'paused', 'PAUSED — ' + p.init + ': gate ' + p.kind + ' (' + p.result + ') since ' + p.since));
416
453
  });
@@ -481,6 +518,24 @@ if (data.schema !== 1) {
481
518
  });
482
519
  }
483
520
 
521
+ // An agent that logged a hard error with no ticket to hang it on used to
522
+ // land in that initiative's STATE.md and nowhere else, so the page whose
523
+ // whole job is to say "not all is well" showed nothing at all.
524
+ var logged = data.errors_logged || [];
525
+ if (logged.length > 0) {
526
+ var total = data.errors_logged_total || logged.length;
527
+ ov.appendChild(el('h2', null, 'Errors logged (' + total + ')'));
528
+ ov.appendChild(el('div', 'hint', 'Agents recorded these as failures. Newest first. An error carrying no ticket belongs to the initiative rather than to any one card, which is why it appears here and in no lane.'));
529
+ logged.forEach(function (e) {
530
+ var text = (e.class || 'error') + (e.detail ? ': ' + e.detail : '')
531
+ + (e.ticket_unknown ? ' \u2014 it names ticket ' + e.ticket + ', which this journal has never declared' : '');
532
+ ov.appendChild(el('div', 'damaged', e.init + ' \\u00b7 ' + text + ' \\u00b7 ' + ago(e.ts)));
533
+ });
534
+ if (total > logged.length) {
535
+ ov.appendChild(el('div', 'hint', 'and ' + (total - logged.length) + ' older \\u2014 the journals have the rest.'));
536
+ }
537
+ }
538
+
484
539
  // The same argument one step down. An initiative whose journal is PARTLY
485
540
  // damaged folds to a board with nothing wrong on it — the lost half leaves
486
541
  // no trace — so it used to render as an initiative in perfect health.
@@ -500,6 +555,13 @@ if (data.schema !== 1) {
500
555
  // ---- board ------------------------------------------------------------
501
556
  var bd = panels.board;
502
557
  bd.appendChild(el('div', 'hint', 'Every lane is derived from the journal — moving a ticket means appending an event, never editing this page. Select a card to see what the board knows about it.'));
558
+ // Lanes where a ticket sitting still is worth saying out loud. The backlog
559
+ // and ready lanes are deliberately absent — an unstarted ticket is not
560
+ // stalling, it is waiting its turn, and marking every one of them stale
561
+ // would make the signal worthless on the lanes where it means something.
562
+ // Done, likewise: a merged ticket is supposed to stop moving.
563
+ var STALLABLE = ['blocked', 'changes-requested', 'in-review', 'waiting-operator', 'in-progress', 'paused-limit'];
564
+
503
565
  var detail = el('div');
504
566
  var selected = null;
505
567
  var lanesWrap = el('div', 'lanes');
@@ -525,6 +587,7 @@ if (data.schema !== 1) {
525
587
  // is already done — precisely when the running-agents list is empty.
526
588
  row('worked by', card.worked_by && card.worked_by.length ? card.worked_by.join(', ') : null);
527
589
  row('note', card.annotation);
590
+ row('last event', card.since ? ago(card.since) + ' (' + card.since + ')' : null);
528
591
  if (cost) {
529
592
  var hit = (cost.by_ticket || []).filter(function (r) { return r.ticket === card.id; })[0];
530
593
  if (hit) row('spend', fmtTokens(hit.tokens) + ' tokens · ' + fmtUsd(hit.usd));
@@ -589,6 +652,18 @@ if (data.schema !== 1) {
589
652
  if (moved[(c.init || '') + '/' + c.id]) button.appendChild(el('span', 'movedtag', 'moved'));
590
653
  if (c.agents && c.agents.length) button.appendChild(el('span', 'note', 'agents: ' + c.agents.join(', ')));
591
654
  if (c.annotation) button.appendChild(el('span', 'note', c.annotation));
655
+ // How long this card has stood still, on the lanes where standing still
656
+ // IS the defect. The board would tell you an agent had been quiet for
657
+ // three hours and refuse to tell you a ticket had been blocked for four
658
+ // days — the timestamp has been in board.json since the lanes existed
659
+ // and nothing ever rendered it.
660
+ //
661
+ // Worded as an observation, never a verdict: the board reports the last
662
+ // event on the ticket, and only a human knows whether that is a stall or
663
+ // a long test run.
664
+ if (STALLABLE.indexOf(lane) !== -1 && c.since) {
665
+ button.appendChild(el('span', 'note ' + ageClass(ageMsOf(c.since)), 'no event ' + ago(c.since).replace(/ ago$/, '')));
666
+ }
592
667
  button.addEventListener('click', function () { showDetail(c, lane, button); });
593
668
  box.appendChild(button);
594
669
  buttons.push(button);
package/scripts/board.mjs CHANGED
@@ -45,6 +45,7 @@ import { jsonEscapeInvisible } from './invisible.mjs';
45
45
  import { renderBoardError, renderBoardHtml } from './board-html.mjs';
46
46
  import { COST_SCHEMA, costJson, costReport } from './cost.mjs';
47
47
  import { SettingsError, applyPolicyClass, applySetting, readSettings } from './settings.mjs';
48
+ import { checkStopAt } from './stop-check.mjs';
48
49
 
49
50
  export const BOARD_HTML_FILE = 'board.html';
50
51
 
@@ -155,10 +156,20 @@ export function initiativeFiles(tyranDir, name) {
155
156
  }
156
157
 
157
158
  /** Pure merge of per-initiative boards into the one payload. */
158
- export function crossBoard({ initiatives, errors, warned = [] }) {
159
+ /**
160
+ * How many logged errors travel in the payload.
161
+ *
162
+ * `board.json` is committed and compared byte for byte, so an unbounded list
163
+ * would grow the artefact with every bad night. Newest first and a count for
164
+ * the rest: the board's job is to say something is wrong, not to be the log.
165
+ */
166
+ export const MAX_LOGGED_ERRORS = 20;
167
+
168
+ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
159
169
  const asks = [];
160
170
  const agents = [];
161
171
  const paused = [];
172
+ const logged = [];
162
173
  const files = {};
163
174
  const lanes = Object.fromEntries(LANES.map((lane) => [lane, []]));
164
175
  let merged = 0;
@@ -173,6 +184,22 @@ export function crossBoard({ initiatives, errors, warned = [] }) {
173
184
  for (const a of board.agents) agents.push({ ...a, init: name });
174
185
  if (board.paused !== null) paused.push({ ...board.paused, init: name });
175
186
  if (docs !== undefined && docs.length > 0) files[name] = docs;
187
+ // An `error` event with no ticket landed in STATE.md's Errors table and
188
+ // nowhere else: the fold collects it, and the board that exists to say
189
+ // "not all is well" carried neither `state.errors` nor the tickets an
190
+ // error named that the journal has never seen. A whole class of agent
191
+ // failure was invisible on the one screen meant to show it.
192
+ for (const e of state.errors) {
193
+ logged.push({
194
+ init: name,
195
+ class: e.class,
196
+ detail: e.detail,
197
+ ticket: e.ticket ?? null,
198
+ ticket_unknown: e.ticket_unknown === true,
199
+ ts: e.ts,
200
+ actor: e.actor,
201
+ });
202
+ }
176
203
  for (const lane of LANES) {
177
204
  for (const card of board.lanes.get(lane)) lanes[lane].push({ ...card, init: name });
178
205
  }
@@ -185,6 +212,9 @@ export function crossBoard({ initiatives, errors, warned = [] }) {
185
212
  // ISO string from the journal, so ascending string order IS ascending time;
186
213
  // an agent with no signal at all sorts to the front, where it belongs.
187
214
  agents.sort((a, b) => String(a.last_signal ?? '').localeCompare(String(b.last_signal ?? '')));
215
+ // Newest first: an error from four days ago is history, the one from ten
216
+ // minutes ago is the reason you opened this page.
217
+ logged.sort((a, b) => String(b.ts ?? '').localeCompare(String(a.ts ?? '')));
188
218
 
189
219
  return {
190
220
  schema: 1,
@@ -203,11 +233,26 @@ export function crossBoard({ initiatives, errors, warned = [] }) {
203
233
  blocked: lanes.blocked.length + lanes['changes-requested'].length
204
234
  + agents.filter((a) => a.state === 'blocked').length,
205
235
  },
236
+ // Committed repo state, so it belongs in the artefact rather than behind a
237
+ // route: `.tyran/STOP` is identical in every clone, and `--check` stays
238
+ // byte-exact. The machine-local half of "is this run supposed to be
239
+ // running" — the pause marker, the resume watcher — is served instead,
240
+ // for the same reason spend is.
241
+ // `{stopped, reason}` and NOT the path `checkStopAt` also returns: an
242
+ // absolute path in a committed, byte-compared artefact makes two clones of
243
+ // one journal disagree on a machine whose home directory is spelled
244
+ // differently. The same trap the initiative file list was caught in.
245
+ stop: stop === null ? null : { stopped: stop.stopped, reason: stop.reason },
206
246
  paused,
207
247
  asks,
208
248
  agents,
209
249
  files,
210
250
  lanes,
251
+ // The key is `errors_logged`, NOT `errors`: `errors` on this payload
252
+ // already means "this initiative's journal could not be read at all", and
253
+ // one key with two meanings is the defect ADR-21 is named after.
254
+ errors_logged: logged.slice(0, MAX_LOGGED_ERRORS),
255
+ errors_logged_total: logged.length,
211
256
  errors,
212
257
  warned,
213
258
  };
@@ -224,6 +269,11 @@ export function renderCrossMd(payload) {
224
269
  `**${t.agents} agent(s) running across ${t.initiatives} initiative(s) · ` +
225
270
  `${t.merged}/${t.tickets} tickets merged (${t.percent}%) · as of ${inline(payload.as_of)}**\n`,
226
271
  );
272
+ // First, and above the pause: a STOP outranks everything. It is the one
273
+ // state where a strip of silent agents is the system doing as it was told.
274
+ if (payload.stop?.stopped === true) {
275
+ parts.push(`\n**STOPPED** — an operator halted this repo: ${inline(payload.stop.reason)}\n`);
276
+ }
227
277
  for (const p of payload.paused) {
228
278
  parts.push(`\n**PAUSED** — ${inline(p.init)}: gate ${inline(p.kind)} (${inline(p.result)}) since ${inline(p.since)}\n`);
229
279
  }
@@ -233,6 +283,13 @@ export function renderCrossMd(payload) {
233
283
  for (const d of payload.warned ?? []) {
234
284
  for (const w of d.warnings) parts.push(`\n**WARNING** — ${inline(d.name)}: ${inline(w)}\n`);
235
285
  }
286
+ for (const e of payload.errors_logged ?? []) {
287
+ const what = `${inline(e.class ?? 'error')}${e.detail != null ? `: ${inline(e.detail)}` : ''}` +
288
+ (e.ticket_unknown ? ` — it names ticket ${inline(e.ticket)}, which this journal has never declared` : '');
289
+ parts.push(`\n**ERROR** — ${inline(e.init)}: ${what} (${inline(e.ts)})\n`);
290
+ }
291
+ const hidden = (payload.errors_logged_total ?? 0) - (payload.errors_logged ?? []).length;
292
+ if (hidden > 0) parts.push(`\n**ERROR** — and ${hidden} older error(s); read the journals for the rest\n`);
236
293
 
237
294
  parts.push('\n## Waiting on you\n\n');
238
295
  if (payload.asks.length === 0) parts.push('_none — the agents have what they need_\n');
@@ -281,7 +338,12 @@ export function renderCrossMd(payload) {
281
338
  }
282
339
 
283
340
  export function renderAll(tyranDir) {
284
- const payload = crossBoard(readInitiativeBoards(tyranDir));
341
+ const payload = crossBoard({
342
+ ...readInitiativeBoards(tyranDir),
343
+ // Named from the board's own directory rather than reconstructed from a
344
+ // repo root: `--dir` need not be spelled `.tyran`.
345
+ stop: checkStopAt(join(tyranDir, 'STOP')),
346
+ });
285
347
  const json = crossJson(payload);
286
348
  return {
287
349
  payload,
@@ -554,7 +554,20 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
554
554
  state.retro.push({ kind: data.kind ?? null, target: data.target ?? null, confidence: data.confidence ?? null, ts });
555
555
  break;
556
556
  case 'error': {
557
- state.errors.push({ class: data.class ?? null, detail: data.detail ?? null, ts, actor });
557
+ // The ticket travels ON the error, not only in the separate
558
+ // unknown-ticket list. A consumer that wanted both — the board does —
559
+ // otherwise had to join the two by timestamp, and emitted one event as
560
+ // two rows when it could not.
561
+ const errTicket = data.ticket != null ? String(data.ticket) : null;
562
+ const errKnown = errTicket !== null && state.tickets.has(errTicket);
563
+ state.errors.push({
564
+ class: data.class ?? null,
565
+ detail: data.detail ?? null,
566
+ ts,
567
+ actor,
568
+ ticket: errTicket,
569
+ ticket_unknown: errTicket !== null && !errKnown,
570
+ });
558
571
  // `data.ticket` is optional metadata on an error, so a typo here is a
559
572
  // typo nothing rejected at append. Binding it to a ticket the journal
560
573
  // has never seen would MINT that ticket, and a minted ticket is one
@@ -42,7 +42,18 @@ const REASON_BYTES = 2000;
42
42
  * be asked. A brake that releases itself when it is damaged is not a brake.
43
43
  */
44
44
  export function checkStop(repoDir) {
45
- const path = join(repoDir, STOP_PATH);
45
+ return checkStopAt(join(repoDir, STOP_PATH));
46
+ }
47
+
48
+ /**
49
+ * The same answer, for a caller that already knows where the file is.
50
+ *
51
+ * The board is given a `--dir` that need not be spelled `.tyran`, so it cannot
52
+ * reconstruct the path by joining a repo root to a constant. A second
53
+ * existsSync-and-read there would be a second spelling of the fail-CLOSED rule
54
+ * below, which is exactly the rule that must not have two spellings.
55
+ */
56
+ export function checkStopAt(path) {
46
57
  if (!existsSync(path)) return { stopped: false, reason: null, path };
47
58
  try {
48
59
  if (statSync(path).isDirectory()) {