@jjanczur/tyran 0.1.32 → 0.1.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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.33",
15
15
  "source": "./",
16
16
  "author": {
17
17
  "name": "Jacek Janczura",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tyran",
3
- "version": "0.1.32",
3
+ "version": "0.1.33",
4
4
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
5
5
  "author": {
6
6
  "name": "Jacek Janczura",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,72 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.33 — 2026-08-17
4
+
5
+ ### The board was hiding what its own journal already knew
6
+
7
+ Three directory slugs and one blended percentage. The journal has carried a
8
+ written title since it existed — "The kanban board: one screen that answers
9
+ what is going on" — and `crossBoard` summed every initiative's progress before
10
+ throwing the parts away, so an operator reading "47%" across three slugs could
11
+ not tell which was nearly done from which had not started.
12
+
13
+ Each initiative now has its own row: title, progress, and how many questions
14
+ it is waiting on. The payload reads no clock — it ships `last_ts` and the page
15
+ ages it — so `board.mjs --check` stays byte-exact.
16
+
17
+ **This replaced an archive feature, on measurement.** Across 63 distinct real
18
+ journals only 6 were finished-and-archivable while **43 were waiting on a
19
+ question nobody had answered**. The board was never cluttered with completed
20
+ work; it was full of ABANDONED work. Archiving would have touched under 10% of
21
+ initiatives, left the 64-initiative ceiling exactly where it is, and — since
22
+ archivable means 100% merged — pulled the headline percentage DOWN.
23
+
24
+ **Upgrading: one expected `--check` drift.** The payload gains a top-level
25
+ `initiatives` key, so a `board.json` committed by an earlier version no longer
26
+ matches what this one generates. Measured: `board.mjs --check` exits 1 once on
27
+ an upgraded install and 0 after a single regenerate —
28
+
29
+ ```bash
30
+ node scripts/board.mjs --dir .tyran # then commit the three artefacts
31
+ ```
32
+
33
+ `doctor --state` is silent about it either way; the only surface is an
34
+ explicit `--check`, which matters if you run one in CI. The board `schema`
35
+ stays 1 because nothing about the existing keys changed, the same call made
36
+ when `errors_logged` was added.
37
+
38
+ ### Two more things that had never worked and said nothing
39
+
40
+ - **`/run.json` never carried a reset time.** `pickWindow` tested
41
+ `typeof resets_at === 'string'` while every writer produces epoch SECONDS,
42
+ so it returned null for every real payload it was ever given: the run panel
43
+ could say a pause was in force but never when it would end. Live since the
44
+ feature shipped.
45
+ - **The closing checkpoint had no producer.** The projection has closed every
46
+ still-open spawn on `checkpoint phase=closed` since 0.1.31, and nothing ever
47
+ emitted one — 9 of 63 real journals had one. So an agent that finished weeks
48
+ ago still read as live work. The conductor is now told to write it, including
49
+ when an initiative ends because it was ABANDONED, and the test executes the
50
+ command rather than grepping for it.
51
+
52
+ `runState` also reports `limits_mode`: "the gate cannot see" and "the feature
53
+ was never switched on" are different facts with the same symptom.
54
+
55
+ ### An ask offers its recommendation as one click
56
+
57
+ It was shown as text, and the only way to accept it was to retype it into the
58
+ box beneath it. For an operator who is not an engineer, that gap was most of
59
+ the difficulty of the page. The button fills the box rather than submitting,
60
+ so the wording stays editable and the answer stays deliberate.
61
+
62
+ ### Findings are pointed at, not copied
63
+
64
+ Measured across 63 distinct journals: 3 carry any finding, 49 in total, and
65
+ none names a ticket — so they cannot enrich a card. Median claim is 429
66
+ characters and `STATE.md` already renders the full table. The initiative row
67
+ carries a count when it is non-zero and nothing else; a test forbids `claim`
68
+ or `proof` reaching the byte-compared payload.
69
+
3
70
  ## 0.1.32 — 2026-08-17
4
71
 
5
72
  ### 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: 1535 unit tests, run with `node --test "tests/**/*.test.mjs"`.
313
313
 
314
314
  ## Documentation
315
315
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.32",
3
+ "version": "0.1.33",
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": {
@@ -195,6 +195,20 @@ pre.how .c{color:var(--muted)}
195
195
  input against the 5-minute write's 1.25x. Without a distinct colour the
196
196
  most expensive caching decision on the page is invisible. */
197
197
  .comp .s-cache_write_1h{background:var(--ink)}
198
+ /* ---- initiatives ---- */
199
+ .inits{display:flex;flex-direction:column;gap:.3rem;margin:.5rem 0}
200
+ .initrow{display:grid;grid-template-columns:minmax(0,1.6fr) 5rem auto minmax(0,1fr);
201
+ gap:.6rem;align-items:center;padding:.35rem .5rem;border-radius:4px}
202
+ /* An initiative nobody can move without the operator is the one thing on this
203
+ section worth catching an eye. */
204
+ .initrow.waiting{background:color-mix(in srgb,var(--brass) 12%,transparent)}
205
+ .initrow .il{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
206
+ .initrow .islug{color:var(--muted);margin-left:.4rem;font-size:.85em}
207
+ .initrow .ib{height:6px;background:var(--line);border-radius:3px;overflow:hidden}
208
+ .initrow .ib i{display:block;height:100%;background:var(--sage)}
209
+ .initrow .iv,.initrow .iw{color:var(--muted);font-size:.9em;white-space:nowrap}
210
+ .initrow .iw.warn{color:var(--brass);font-weight:600}
211
+
198
212
  /* ---- the per-day series ---- */
199
213
  .days{display:flex;align-items:flex-end;gap:2px;height:74px;margin:.5rem 0 .3rem;
200
214
  overflow-x:auto;padding-bottom:2px}
@@ -572,6 +586,59 @@ if (data.schema !== 1) {
572
586
  ov.appendChild(first);
573
587
  }
574
588
 
589
+ // ---- initiatives, and the ones that have stopped moving ----------------
590
+ //
591
+ // MEASURED, and the reason this section exists rather than an archive: of 63
592
+ // real journals, 43 were waiting on a question nobody answered and only 6
593
+ // were finished-and-archivable. The board was not cluttered with completed
594
+ // work; it was full of ABANDONED work, and archiving the finished 6 would
595
+ // have removed the only initiatives at 100% and pulled the headline
596
+ // percentage down.
597
+ //
598
+ // "Waiting" is the initiative's own count of open operator questions. The
599
+ // idle time is computed HERE, from last_ts, because the payload is
600
+ // byte-compared and reads no clock — the same split the agent strip uses.
601
+ var inits = Array.isArray(data.initiatives) ? data.initiatives : [];
602
+ if (inits.length > 0) {
603
+ var stalled = inits.filter(function (i) { return i.waiting > 0; }).sort(function (a, b) {
604
+ return (ageMsOf(b.last_ts) || 0) - (ageMsOf(a.last_ts) || 0);
605
+ });
606
+ ov.appendChild(el('h2', null, 'Initiatives'));
607
+ if (stalled.length > 0) {
608
+ ov.appendChild(el('div', 'hint',
609
+ stalled.length + ' of ' + inits.length + ' are waiting on an answer from you. ' +
610
+ 'Longest-waiting first — an initiative with an open question does not move until it is answered.'));
611
+ }
612
+ var table = el('div', 'inits');
613
+ var ordered = stalled.concat(inits.filter(function (i) { return !(i.waiting > 0); }));
614
+ ordered.forEach(function (i) {
615
+ var row = el('div', i.waiting > 0 ? 'initrow waiting' : 'initrow');
616
+ // The TITLE, which the journal has carried all along while this page
617
+ // showed a directory slug.
618
+ var label = el('div', 'il');
619
+ label.appendChild(el('b', null, i.title || i.name));
620
+ if (i.title) label.appendChild(el('span', 'islug', i.name));
621
+ row.appendChild(label);
622
+ var bar = el('div', 'ib');
623
+ var fill = el('i');
624
+ fill.style.width = (typeof i.percent === 'number' ? i.percent : 0) + '%';
625
+ bar.appendChild(fill);
626
+ row.appendChild(bar);
627
+ var counts = i.merged + '/' + i.tickets + ' merged';
628
+ // Named only when there is something to name. A findings count of zero
629
+ // on every row is noise that teaches the eye to skip the column.
630
+ if (i.findings > 0) counts += ' \u00b7 ' + i.findings + ' finding' + (i.findings === 1 ? '' : 's');
631
+ row.appendChild(el('div', 'iv', counts));
632
+ var age = ageMsOf(i.last_ts);
633
+ row.appendChild(el('div', i.waiting > 0 ? 'iw warn' : 'iw',
634
+ i.waiting > 0
635
+ ? i.waiting + ' waiting on you \u00b7 quiet ' + ago(i.last_ts)
636
+ : (age === null ? '' : 'last moved ' + ago(i.last_ts))));
637
+ table.appendChild(row);
638
+ });
639
+ ov.appendChild(table);
640
+ }
641
+
575
642
  ov.appendChild(el('h2', null, 'Agents'));
576
643
  // Named, not implied by the order: the strip is sorted stalest-first by the
577
644
  // server, and a reader who does not know that reads the first chip as the
@@ -805,6 +872,21 @@ if (data.schema !== 1) {
805
872
  send.setAttribute('type', 'button');
806
873
  var useDefault = hasDefault ? el('button', 'sbtn', 'Take the default') : null;
807
874
  if (useDefault) useDefault.setAttribute('type', 'button');
875
+ // The recommendation was already shown, as TEXT, and the only way to
876
+ // accept it was to retype it into the box below it. For an operator who
877
+ // is not an engineer that gap is most of the difficulty of the whole
878
+ // page: the agent has said what it thinks should happen and the human is
879
+ // asked to transcribe it. This fills the box instead of submitting, so
880
+ // the wording stays editable and the answer is still deliberate.
881
+ var useRec = a.recommendation ? el('button', 'sbtn', 'Use the recommendation') : null;
882
+ if (useRec) {
883
+ useRec.setAttribute('type', 'button');
884
+ useRec.addEventListener('click', function () {
885
+ input.value = a.recommendation;
886
+ input.focus();
887
+ holdRefresh();
888
+ });
889
+ }
808
890
  var status = el('div', 'sstat');
809
891
 
810
892
  var submit = function (text) {
@@ -847,6 +929,7 @@ if (data.schema !== 1) {
847
929
 
848
930
  box.appendChild(input);
849
931
  acts.appendChild(send);
932
+ if (useRec) acts.appendChild(useRec);
850
933
  if (useDefault) acts.appendChild(useDefault);
851
934
  box.appendChild(acts);
852
935
  box.appendChild(status);
package/scripts/board.mjs CHANGED
@@ -234,6 +234,7 @@ export const MAX_LOGGED_ERRORS = 20;
234
234
 
235
235
  export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
236
236
  const asks = [];
237
+ const summaries = [];
237
238
  const agents = [];
238
239
  const paused = [];
239
240
  const logged = [];
@@ -246,6 +247,39 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
246
247
  for (const { name, state, board, files: docs } of initiatives) {
247
248
  merged += state.merged;
248
249
  tickets += state.ticketList.length;
250
+ // Per-initiative, because one blended percentage over every initiative is
251
+ // not a fact about any of them: an operator reading "50%" across four
252
+ // slugs cannot tell which is nearly done from which has not started.
253
+ //
254
+ // The TITLE is the point of the row. `init.created` has carried a written
255
+ // sentence all along — "Settings on the board: edit config and the
256
+ // autonomy policy from the page" — and the board showed the directory
257
+ // slug. `waiting` and `last_ts` are here rather than a computed idle time
258
+ // because this payload is byte-compared under `--check` and reads no
259
+ // clock; the page ages them, exactly as it already ages agents.
260
+ summaries.push({
261
+ name,
262
+ title: typeof state.created?.data?.title === 'string' ? state.created.data.title : null,
263
+ tickets: state.ticketList.length,
264
+ merged: state.merged,
265
+ percent: state.percent,
266
+ waiting: board.asks.length,
267
+ // A COUNT, and deliberately not the findings themselves. Measured across
268
+ // 63 distinct real journals: 3 carry any finding at all, 49 in total,
269
+ // and NOT ONE names a ticket — so they cannot enrich a card, which is
270
+ // where a richer board would have put them. Their median claim is 429
271
+ // characters, a paragraph rather than a label, and STATE.md already
272
+ // renders the full seven-column table.
273
+ //
274
+ // So this is a pointer, not a copy: the research exists and the reader
275
+ // is told where. Duplicating the prose here would be ADR-21's defect
276
+ // and would cost ~600 B per finding in a byte-compared payload.
277
+ // Guarded: `crossBoard` is exported and takes any folded state, and a
278
+ // caller assembling one by hand need not have every collection. A
279
+ // missing array must read as "none", never take the board down.
280
+ findings: (state.findings ?? []).length,
281
+ last_ts: state.lastTs,
282
+ });
249
283
  if (state.lastTs !== null && (asOf === null || state.lastTs > asOf)) asOf = state.lastTs;
250
284
  for (const a of board.asks) asks.push({ ...a, init: name });
251
285
  for (const a of board.agents) agents.push({ ...a, init: name });
@@ -329,6 +363,10 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
329
363
  stop: stop === null ? null : { stopped: stop.stopped, reason: stop.reason },
330
364
  paused,
331
365
  asks,
366
+ // Ordered by directory name, like everything else here, so two renders of
367
+ // one journal set are byte-identical. `totals.percent` blends these; the
368
+ // rows are what let a reader see WHICH initiative it blends.
369
+ initiatives: summaries,
332
370
  agents,
333
371
  files,
334
372
  lanes,
@@ -228,15 +228,37 @@ export function runState(repo, nowMs = Date.now()) {
228
228
  five_hour: pickWindow(sidecar.five_hour),
229
229
  seven_day: pickWindow(sidecar.seven_day),
230
230
  },
231
+ // Which mode the gate is IN, not only what it can see. Without this a page
232
+ // cannot tell "the gate cannot see" from "the feature was never switched
233
+ // on", and off is the default (templates/config.yaml) — so a telemetry
234
+ // warning built on the `usage` field alone would fire on every repository
235
+ // that has never enabled overnight mode.
236
+ limits_mode: readLimitsFile(repo)?.mode ?? 'off',
231
237
  };
232
238
  }
233
239
 
234
- /** Numbers and an ISO string only — never a free payload string from a hook. */
240
+ /**
241
+ * Numbers and an ISO string only — never a free payload string from a hook.
242
+ *
243
+ * `resets_at` arrives as epoch SECONDS: `statusline.mjs`'s `windowOf` keeps
244
+ * only `finiteNumber` values, and `usage-source.mjs` normalises the platform's
245
+ * ISO string to the same. This function tested `typeof === 'string'` and so
246
+ * returned null for every real payload it has ever been given — `/run.json`
247
+ * has never once carried a reset time, and the board's run panel could say a
248
+ * pause was in force but never when it would end.
249
+ *
250
+ * The string half of the guard was not wrong about the OUTPUT: this is the
251
+ * page's shape, and an ISO string is what a reader wants. It was wrong about
252
+ * the input. So convert, rather than widening the test and emitting seconds
253
+ * the page would have to know to multiply.
254
+ */
235
255
  function pickWindow(w) {
236
256
  if (w === null || typeof w !== 'object') return null;
257
+ const seconds = typeof w.resets_at === 'number' && Number.isFinite(w.resets_at) ? w.resets_at : null;
258
+ const iso = seconds === null ? null : new Date(seconds * 1000);
237
259
  return {
238
260
  used_percentage: typeof w.used_percentage === 'number' ? w.used_percentage : null,
239
- resets_at: typeof w.resets_at === 'string' ? w.resets_at : null,
261
+ resets_at: iso !== null && Number.isFinite(iso.getTime()) ? iso.toISOString() : null,
240
262
  };
241
263
  }
242
264
 
@@ -452,6 +452,32 @@ open one.
452
452
  a lease still held by an agent that has already reported. An orphaned lease
453
453
  blocks the next initiative from a resource nobody is using, and the person
454
454
  who hits it has no way to know it is stale.
455
+ - **Close the initiative when it is closed**, with the retrospective recorded
456
+ and the leases released:
457
+
458
+ ```bash
459
+ node "${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs" append <abs-journal> checkpoint <init> \
460
+ --actor conductor --data '{"phase":"closed","next_steps":[]}'
461
+ ```
462
+
463
+ `append ... checkpoint`, not a `checkpoint` subcommand — there is no such
464
+ subcommand, and the first draft of this line invented one. It would have
465
+ printed a usage block and closed nothing.
466
+
467
+ This is one line and it is load-bearing. The projection closes every still-
468
+ open spawn on a closing checkpoint, which is what stops an agent that
469
+ finished weeks ago from reading as live work, and it is the only signal any
470
+ reader has that an initiative is DONE rather than abandoned mid-flight.
471
+
472
+ Measured across 63 real journals: **9 ever received one**, while 43 sat
473
+ waiting on a question nobody answered. Nothing had ever told you to write
474
+ it — the fold that consumes it shipped, and the event that triggers it was
475
+ never emitted by anything, so the feature has been inert since it landed.
476
+
477
+ A closing checkpoint is not the same as "every ticket merged". Say it when
478
+ the work is over, including when it is over because it was abandoned — an
479
+ initiative someone walked away from is finished too, and saying so is what
480
+ keeps the board honest about which of them are still waiting on you.
455
481
  - **A usage-gate refusal is a wind-down order, not an obstacle.** Near the
456
482
  subscription window the gate refuses everything except checkpointing;
457
483
  its refusal text IS the checklist — follow it verbatim, in order, then