@jjanczur/tyran 0.1.24 → 0.1.26

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.26",
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.26",
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,183 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.26 — 2026-08-15
4
+
5
+ ### Answer a question from the board
6
+
7
+ The last context switch in the operator loop is gone. Every question in the
8
+ **Waiting on you** tab now carries a box: type an answer and press **Answer**,
9
+ or press **Take the default** on a question that records one. The three
10
+ `answer render / edit / apply` commands still work and stay printed on the tab —
11
+ the box is a convenience, and a board opened over `file://` or without
12
+ `--write` has to leave you somewhere to go.
13
+
14
+ The request carries exactly two things: **which** ask, and your words. The
15
+ question, the recorded default, the ticket and the gate id are all read back
16
+ out of the journal by the server — the same guarantee the answer sheet makes,
17
+ for the same reason. The append is `answerOne`, the function `answer apply`
18
+ already calls, unwrapped: both routes produce byte-identical events, the gate
19
+ is re-checked INSIDE the journal's write lock so a question closed in a
20
+ terminal thirty seconds ago cannot be closed twice, and the decision is written
21
+ before the gate.
22
+
23
+ Each card also says which kind of question it is, and that costs no new event
24
+ type: **decision · a default is recorded** means saying nothing has a safe
25
+ outcome; **blocking · no safe default** means it waits for you. It is the same
26
+ distinction that already makes the answer sheet sort no-default-first.
27
+
28
+ ### A tier that runs out of capacity falls to the next one down
29
+
30
+ Measured on a real run: the strongest tier hit its limit and the subagents
31
+ **failed** rather than finishing on the tier below, which had capacity the
32
+ whole time.
33
+
34
+ ```bash
35
+ node scripts/tiers.mjs --role acceptance --unavailable fable --field json
36
+ # tiers: FELL BACK top -> deep because the top model is unavailable.
37
+ ```
38
+
39
+ **Down the ladder, never up** — which is the answer to the question this was
40
+ blocked on. Climbing would spend more than the routing table promised,
41
+ silently, at exactly the moment nobody is watching. Three things the fall does
42
+ not do: it does not lower the **effort** (that judgement did not change because
43
+ a model ran out of capacity), it does not cross a **role floor** (a security
44
+ review on the cheapest model is not a security review), and it does not
45
+ **pretend** — the substitution is announced, and `fell_from` records it. When
46
+ every tier a role may use is unavailable, it exits 2 rather than returning the
47
+ bottom of the ladder: that is a pause, not a substitution, and overnight mode
48
+ is what knows how to wait.
49
+
50
+ ### Twelve confirmed findings from an adversarial review of 0.1.24 and 0.1.25
51
+
52
+ Five lenses attacked the shipped code and each finding was re-attacked
53
+ independently. Two were serious:
54
+
55
+ - **A config with no `limits:` block killed the whole Settings tab.** That
56
+ block is optional and every install set up before 0.1.24 has none, so
57
+ `resolvePath` returned null, `readAt` tried to iterate it, and the tab
58
+ rendered "the board server did not answer" while the server answered every
59
+ request. Every write on such a repo was an HTTP 500 in the terminal the docs
60
+ designate as the audit trail.
61
+ - **The page could reload under a half-typed value.** A `meta http-equiv=refresh`
62
+ is scheduled by the browser when it parses the tag, and REMOVING THE NODE
63
+ DOES NOT CANCEL IT — the code sincerely believed otherwise, in a comment. The
64
+ page now carries an inert marker only its own script reads, so the single
65
+ reload path is a timer it can actually stop.
66
+
67
+ And:
68
+
69
+ - **An unreadable journal wrote an absolute path** — a home directory and a
70
+ username — into `board.json`, which is committed and compared byte for byte,
71
+ so it also failed `--check` on every other machine. Now the error code and a
72
+ repo-relative path.
73
+ - **An initiative whose directory could not be read vanished** from the board
74
+ with nothing said; the totals just went down by one. `existsSync` cannot tell
75
+ "there is no journal here" from "I cannot tell whether there is one".
76
+ - **`--dir` pointed at the repo root silently succeeded**, creating a `state/`
77
+ directory in the wrong place and reporting that all was well about a repo
78
+ whose real journals sat one level down.
79
+ - **The settings write had no compare-and-swap.** Two boards on one directory,
80
+ or a board and a terminal, could discard each other's change with both
81
+ reporting success.
82
+ - Plus a wrong number in the CHANGELOG, an overclaim in `docs/configuration.md`
83
+ (`pricing:` and `main_writable_paths:` have no knob), a lane emptied by the
84
+ filter showing no placeholder, a stale "Four tabs" comment, one of ten lanes
85
+ unaccounted for in the stalled-card prose, and two unverifiable claims about
86
+ the sandbox.
87
+
88
+ ### yaml-lite: the writer and the reader disagreed about numbers
89
+
90
+ `formatScalar` required a digit before the decimal point and `parseScalar` did
91
+ not, so the **string** `.5` was written unquoted and read back as the **number**
92
+ 0.5. Both now use the reader's two patterns. This was found by `yaml-patch`'s
93
+ round-trip proof — the guard whose comment claimed no input was known to reach
94
+ it. That claim is now corrected rather than repeated.
95
+
96
+ A leading **BOM** is also handled: `trimStart` counts it as whitespace, so it
97
+ read as one column of indentation and the parser rejected the whole file with a
98
+ complaint about a line the operator could see nothing wrong with.
99
+
100
+ Three more in the patcher, each of which wrote or refused the wrong thing: a
101
+ key was located with `indexOf(':')` rather than the parser's own rule (so `a`
102
+ landed on the `a:b` line), a path ending in an integer dropped the list item's
103
+ dash, and replacing a list that is the FIRST key of a sequence item deleted the
104
+ item's sibling keys.
105
+
106
+ ### The backtick guard
107
+
108
+ The whole browser client is one template literal, so a backtick anywhere inside
109
+ it — including in a comment — ends the literal and the page stops loading. It
110
+ happened four times in one sitting. The parse test caught it every time and
111
+ could never say so: it reports whatever identifier followed the stray backtick.
112
+ A new guard reads the source as text, imports nothing, and names the line.
113
+
114
+ ## 0.1.25 — 2026-08-15
115
+
116
+ ### The sandbox is now Tyran building Tyran
117
+
118
+ The published sample board was two invented initiatives about someone else's
119
+ payment system. It showed what the dashboard looked like and nothing about what
120
+ it is like to work this way, which is half of what a reader opens it for.
121
+
122
+ It now carries **three initiatives that actually built the board you are
123
+ looking at** — the lanes, overnight mode, and the Settings tab — written as
124
+ journals from the real work. Every finding on it is a finding that was made:
125
+ the artefact must never read a clock or `--check` can never pass twice; the
126
+ page must build DOM with `textContent` only, because journal values reach the
127
+ browser verbatim; the hook payload does not carry `rate_limits` and a plugin
128
+ cannot install a statusline. Every logged error is one that happened, including
129
+ the backtick in a comment that terminated the client's template literal.
130
+
131
+ All ten lanes are populated, five agents run at ages from about twenty minutes
132
+ to three hours, two questions wait on the operator, and the banner's counts are read
133
+ from the payload rather than typed — it said "two invented initiatives" for a
134
+ release after a third was added.
135
+
136
+ ### Three findings while writing those journals, all in shipped code
137
+
138
+ - **Every reviewer on the published sandbox rendered as still running, for
139
+ ever.** A `review` closes its spawn by `data.by`; the sandbox journals said
140
+ `data.agent`, so no review ever closed anything and the headline agent count
141
+ was wrong on the one page whose job is to show what the product looks like.
142
+ - **The test that was supposed to catch that validated nothing.**
143
+ `validateJournal` takes a file PATH and the test handed it an array of
144
+ events, so it read an empty journal and returned `ok` — it was asserting
145
+ that nothing had no errors. The replacement journals tripped it thirteen
146
+ times on the first honest run.
147
+ - **An `error` event that named a ticket produced two rows on the board**, one
148
+ from `state.errors` and one from `unknownErrorTickets`. The ticket now
149
+ travels on the error itself, where a consumer that wants both can have both
150
+ without joining two lists by timestamp.
151
+
152
+ ### The board answers "is this supposed to be running?"
153
+
154
+ Three chips reading "6 HOURS since last signal — likely dead" covered four
155
+ unrelated situations and the board could tell them apart in none of them.
156
+
157
+ - **A STOP is on the board**, above everything else, carrying the first line of
158
+ `.tyran/STOP` as its reason. It is committed repo state, identical in every
159
+ clone, so it travels in the artefact — as `{stopped, reason}` and
160
+ deliberately not the path, which would make two clones disagree and fail
161
+ `--check`.
162
+ - **An error with no ticket is finally visible.** The fold has collected
163
+ `state.errors` since errors existed and the board carried neither it nor the
164
+ unknown-ticket list, so an agent logging a hard failure showed nothing at all
165
+ on the page that exists to say "not all is well". The key is
166
+ `errors_logged`, not `errors`: that name already means "this journal could
167
+ not be read", and one key with two meanings is the defect ADR-21 is named
168
+ after. Capped at 20 newest-first with the true count beside it, because this
169
+ artefact is committed.
170
+ - **Cards say how long they have stood still.** The board would tell you an
171
+ agent had been quiet for three hours and refuse to tell you a ticket had been
172
+ blocked for four days — the timestamp was in `board.json` all along. Only on
173
+ the lanes where standing still IS the defect: `backlog` and `ready` are
174
+ excluded, because an unstarted ticket is waiting its turn, and marking every
175
+ one of them stale makes the mark worthless where it means something.
176
+
177
+ All three use one staleness vocabulary, shared with the agent strip. Three
178
+ renderings of "how long ago" would let the same gap read as fine in one place
179
+ and alarming in another.
180
+
3
181
  ## 0.1.24 — 2026-08-15
4
182
 
5
183
  ### Settings: the board can now change what Tyran does
@@ -21,7 +199,7 @@ the difference the flag exists to make.
21
199
  comments were expendable because the screen could carry the explanations. That
22
200
  turned out not to be necessary: `scripts/yaml-patch.mjs` rewrites the line
23
201
  that owns a value rather than round-tripping the document through a
24
- serializer, so `templates/config.yaml` keeps all 60 of its comment lines — the
202
+ serializer, so `templates/config.yaml` keeps all 63 of its comment lines — the
25
203
  only place anyone is told that bare `off` is the YAML boolean false, which is
26
204
  also the value that would have silently changed meaning had this been done the
27
205
  obvious way.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.24",
3
+ "version": "0.1.26",
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": {
@@ -570,7 +570,19 @@ export function applySheet(tyranDir, sheetText, { dryRun = false } = {}) {
570
570
  /** One ask's two appends, or the reason nothing was written for it. A lock
571
571
  * this run could not take is reported like any other unwritten ask: the run
572
572
  * that holds it is writing the same sitting, and a thrown error here would
573
- * abandon the asks after this one without saying so. */
573
+ * abandon the asks after this one without saying so.
574
+ *
575
+ * Exported because the board answers questions too. A second implementation
576
+ * there would be a second place that decides what "answering" means — and the
577
+ * two properties that matter are both in here: the re-check of `askState`
578
+ * INSIDE the lock, so a question answered in a terminal thirty seconds ago is
579
+ * not answered twice, and decision-before-gate, so a crash between the two
580
+ * leaves a visible orphan decision rather than a closed question with no
581
+ * answer. */
582
+ export function answerOne(ask, verdict) {
583
+ return sittingOutcome(ask, verdict);
584
+ }
585
+
574
586
  function sittingOutcome(ask, verdict) {
575
587
  try {
576
588
  return withSittingLock(ask.journal, () => {
@@ -9,7 +9,7 @@ import { FORBIDDEN } from './invisible.mjs';
9
9
  * is blocked over file:// in Chromium, so meta-refresh is the one reliable
10
10
  * primitive; under `board.mjs --serve` the same refresh hits the server.
11
11
  *
12
- * ## Four tabs, because the page answers four questions
12
+ * ## Five tabs, because the page answers five questions
13
13
  *
14
14
  * Overview (what is the state), Board (where is every ticket), Waiting on you
15
15
  * (what is blocked on a decision, and how to answer it), Spend (what it
@@ -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 ---- */
@@ -154,6 +157,15 @@ h3{font-family:var(--font);color:var(--heading);font-size:.85rem;margin:1.1rem 0
154
157
  .ask .q{color:var(--brass-bright);font-size:1rem;font-weight:600}
155
158
  .ask .row{margin-top:.22rem;font-size:.86rem}
156
159
  .ask .label{color:var(--muted);text-transform:uppercase;font-size:.66rem;letter-spacing:.07em;margin-right:.4rem;font-family:var(--mono)}
160
+ .ask .kindtag{display:inline-block;font-family:var(--mono);font-size:.63rem;letter-spacing:.06em;text-transform:uppercase;border-radius:.25rem;padding:.1rem .4rem;margin-bottom:.35rem}
161
+ .ask .kindtag.blocking{background:var(--clay-low);color:var(--clay-bright);border:1px solid var(--clay-edge)}
162
+ .ask .kindtag.decision{background:var(--steel-low);color:var(--steel-bright);border:1px solid var(--steel-edge)}
163
+ .reply{margin-top:.6rem;border-top:1px solid var(--brass-edge);padding-top:.55rem}
164
+ .reply textarea{display:block;width:100%;font-family:var(--font);font-size:.86rem;background:var(--bg-raised);color:var(--text);border:1px solid var(--hairline);border-radius:.35rem;padding:.4rem .55rem;min-height:3.4rem;resize:vertical}
165
+ .reply textarea:focus-visible{outline:2px solid var(--steel);outline-offset:1px}
166
+ .reply textarea:disabled{opacity:.55;cursor:not-allowed}
167
+ .reply .acts{display:flex;flex-wrap:wrap;gap:.4rem;align-items:center;margin-top:.4rem}
168
+ .reply .hint{font-size:.75rem;color:var(--muted);margin-top:.3rem}
157
169
  pre.how{background:var(--bg-sunken);border:1px solid var(--hairline);border-radius:.45rem;padding:.7rem .85rem;font-family:var(--mono);font-size:.76rem;color:var(--text);overflow-x:auto;margin:.4rem 0 .7rem}
158
170
  pre.how .c{color:var(--muted)}
159
171
 
@@ -368,6 +380,31 @@ if (data.schema !== 1) {
368
380
  return box;
369
381
  };
370
382
 
383
+ // One staleness vocabulary, used by the agent strip, the logged errors and
384
+ // the lane cards. Three renderings of "how long ago" would let the same
385
+ // gap read as fine in one place and alarming in another.
386
+ //
387
+ // This is the only clock on the page. The ARTEFACT never reads one — "as of"
388
+ // is the newest event timestamp, which is what keeps --check valid for the
389
+ // HTML — so every age here is computed in the reader's own browser.
390
+ var ageMsOf = function (ts) {
391
+ if (!ts) return null;
392
+ var t = Date.parse(ts);
393
+ return isNaN(t) ? null : Date.now() - t;
394
+ };
395
+ var ageClass = function (ms) {
396
+ if (ms === null) return 'age-cold';
397
+ return ms < 600000 ? 'age-fresh' : ms < 1800000 ? 'age-warm' : ms < 10800000 ? 'age-cold' : 'age-dead';
398
+ };
399
+ var ago = function (ts) {
400
+ var ms = ageMsOf(ts);
401
+ if (ms === null) return 'no time recorded';
402
+ if (ms < 60000) return 'just now';
403
+ if (ms < 3600000) return Math.round(ms / 60000) + ' min ago';
404
+ if (ms < 172800000) return Math.round(ms / 3600000) + ' h ago';
405
+ return Math.round(ms / 86400000) + ' d ago';
406
+ };
407
+
371
408
  var fmtTokens = function (n) {
372
409
  if (n >= 1e9) return (n / 1e9).toFixed(2) + ' B';
373
410
  if (n >= 1e6) return (n / 1e6).toFixed(1) + ' M';
@@ -395,15 +432,14 @@ if (data.schema !== 1) {
395
432
  // shown it — so the chip could say an agent went quiet without saying
396
433
  // what it went quiet in the middle of.
397
434
  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
435
  // Four buckets, not three. The old top bucket was "30 minutes or six
401
436
  // hours", which are not the same event: one is a long test run, the
402
437
  // other is an agent that is not coming back.
438
+ var ageMs = ageMsOf(a.last_signal);
403
439
  var ageText = ageMs === null ? 'no signal recorded'
404
440
  : ageMs >= 10800000 ? Math.round(ageMs / 3600000) + ' HOURS since last signal — likely dead'
405
441
  : Math.round(ageMs / 60000) + ' min since last signal';
406
- chip.appendChild(el('div', ageMs !== null && ageMs >= 10800000 ? 'age-dead' : cls, ageText));
442
+ chip.appendChild(el('div', ageClass(ageMs), ageText));
407
443
  strip.appendChild(chip);
408
444
  });
409
445
  return strip;
@@ -411,6 +447,16 @@ if (data.schema !== 1) {
411
447
 
412
448
  // ---- overview ---------------------------------------------------------
413
449
  var ov = panels.overview;
450
+ // A STOP outranks everything, and it goes first. It is the one state in
451
+ // which a strip of silent agents is the system doing exactly as it was told,
452
+ // and without it that strip reads identically to a fleet that died.
453
+ if (data.stop && data.stop.stopped === true) {
454
+ var stopBox = el('div', 'paused');
455
+ stopBox.appendChild(el('b', null, 'STOPPED \\u2014 '));
456
+ stopBox.appendChild(el('span', null, 'an operator halted this repo: ' + (data.stop.reason || '(no reason given)')));
457
+ stopBox.appendChild(el('div', 'hint', 'Nothing new will be started until .tyran/STOP is deleted. Agents already running are not killed by it.'));
458
+ ov.appendChild(stopBox);
459
+ }
414
460
  (data.paused || []).forEach(function (p) {
415
461
  ov.appendChild(el('div', 'paused', 'PAUSED — ' + p.init + ': gate ' + p.kind + ' (' + p.result + ') since ' + p.since));
416
462
  });
@@ -481,6 +527,24 @@ if (data.schema !== 1) {
481
527
  });
482
528
  }
483
529
 
530
+ // An agent that logged a hard error with no ticket to hang it on used to
531
+ // land in that initiative's STATE.md and nowhere else, so the page whose
532
+ // whole job is to say "not all is well" showed nothing at all.
533
+ var logged = data.errors_logged || [];
534
+ if (logged.length > 0) {
535
+ var total = data.errors_logged_total || logged.length;
536
+ ov.appendChild(el('h2', null, 'Errors logged (' + total + ')'));
537
+ 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.'));
538
+ logged.forEach(function (e) {
539
+ var text = (e.class || 'error') + (e.detail ? ': ' + e.detail : '')
540
+ + (e.ticket_unknown ? ' \u2014 it names ticket ' + e.ticket + ', which this journal has never declared' : '');
541
+ ov.appendChild(el('div', 'damaged', e.init + ' \\u00b7 ' + text + ' \\u00b7 ' + ago(e.ts)));
542
+ });
543
+ if (total > logged.length) {
544
+ ov.appendChild(el('div', 'hint', 'and ' + (total - logged.length) + ' older \\u2014 the journals have the rest.'));
545
+ }
546
+ }
547
+
484
548
  // The same argument one step down. An initiative whose journal is PARTLY
485
549
  // damaged folds to a board with nothing wrong on it — the lost half leaves
486
550
  // no trace — so it used to render as an initiative in perfect health.
@@ -500,6 +564,13 @@ if (data.schema !== 1) {
500
564
  // ---- board ------------------------------------------------------------
501
565
  var bd = panels.board;
502
566
  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.'));
567
+ // Lanes where a ticket sitting still is worth saying out loud. The backlog
568
+ // and ready lanes are deliberately absent — an unstarted ticket is not
569
+ // stalling, it is waiting its turn, and marking every one of them stale
570
+ // would make the signal worthless on the lanes where it means something.
571
+ // Done, likewise: a merged ticket is supposed to stop moving.
572
+ var STALLABLE = ['blocked', 'changes-requested', 'in-review', 'waiting-operator', 'in-progress', 'paused-limit'];
573
+
503
574
  var detail = el('div');
504
575
  var selected = null;
505
576
  var lanesWrap = el('div', 'lanes');
@@ -525,6 +596,7 @@ if (data.schema !== 1) {
525
596
  // is already done — precisely when the running-agents list is empty.
526
597
  row('worked by', card.worked_by && card.worked_by.length ? card.worked_by.join(', ') : null);
527
598
  row('note', card.annotation);
599
+ row('last event', card.since ? ago(card.since) + ' (' + card.since + ')' : null);
528
600
  if (cost) {
529
601
  var hit = (cost.by_ticket || []).filter(function (r) { return r.ticket === card.id; })[0];
530
602
  if (hit) row('spend', fmtTokens(hit.tokens) + ' tokens · ' + fmtUsd(hit.usd));
@@ -574,8 +646,14 @@ if (data.schema !== 1) {
574
646
  var count = el('span', 'count', ' (' + cards.length + ')');
575
647
  h.appendChild(count);
576
648
  box.appendChild(h);
649
+ // Appended ALWAYS, hidden when it is not wanted. It used to be appended
650
+ // only for a lane that was empty at build time, so a lane emptied by the
651
+ // filter showed a heading, a count of "0 of 4", and then nothing — and the
652
+ // display toggle below was setting a style on a node that was not in the
653
+ // document.
577
654
  var emptyMark = el('div', 'empty', '—');
578
- if (cards.length === 0) box.appendChild(emptyMark);
655
+ box.appendChild(emptyMark);
656
+ emptyMark.style.display = cards.length === 0 ? '' : 'none';
579
657
  var buttons = [];
580
658
  cards.forEach(function (c) {
581
659
  var button = el('button', 'card');
@@ -589,6 +667,18 @@ if (data.schema !== 1) {
589
667
  if (moved[(c.init || '') + '/' + c.id]) button.appendChild(el('span', 'movedtag', 'moved'));
590
668
  if (c.agents && c.agents.length) button.appendChild(el('span', 'note', 'agents: ' + c.agents.join(', ')));
591
669
  if (c.annotation) button.appendChild(el('span', 'note', c.annotation));
670
+ // How long this card has stood still, on the lanes where standing still
671
+ // IS the defect. The board would tell you an agent had been quiet for
672
+ // three hours and refuse to tell you a ticket had been blocked for four
673
+ // days — the timestamp has been in board.json since the lanes existed
674
+ // and nothing ever rendered it.
675
+ //
676
+ // Worded as an observation, never a verdict: the board reports the last
677
+ // event on the ticket, and only a human knows whether that is a stall or
678
+ // a long test run.
679
+ if (STALLABLE.indexOf(lane) !== -1 && c.since) {
680
+ button.appendChild(el('span', 'note ' + ageClass(ageMsOf(c.since)), 'no event ' + ago(c.since).replace(/ ago$/, '')));
681
+ }
592
682
  button.addEventListener('click', function () { showDetail(c, lane, button); });
593
683
  box.appendChild(button);
594
684
  buttons.push(button);
@@ -627,8 +717,84 @@ if (data.schema !== 1) {
627
717
  'npx @jjanczur/tyran answer apply --dir .tyran # closes what you answered';
628
718
  qs.appendChild(how);
629
719
  if (asks.length === 0) qs.appendChild(el('div', 'empty', 'nothing — the agents have what they need'));
720
+
721
+ // Answering from the page. The three commands above still work and stay
722
+ // printed: this box is a convenience, not a replacement, and a board opened
723
+ // over file:// or without --write has to leave the operator somewhere to go.
724
+ //
725
+ // The request carries only WHICH ask and the operator's own words. The
726
+ // question, the recorded default, the ticket and the gate id are all read
727
+ // back out of the journal by the server — the same guarantee the answer
728
+ // sheet makes, for the same reason.
729
+ var replyBox = function (a, hasDefault) {
730
+ var box = el('div', 'reply');
731
+ var input = el('textarea');
732
+ input.placeholder = hasDefault
733
+ ? 'Your answer, in your own words \\u2014 or use the default button.'
734
+ : 'Your answer, in your own words. There is no recorded default for this one.';
735
+ var acts = el('div', 'acts');
736
+ var send = el('button', 'sbtn', 'Answer');
737
+ send.setAttribute('type', 'button');
738
+ var useDefault = hasDefault ? el('button', 'sbtn', 'Take the default') : null;
739
+ if (useDefault) useDefault.setAttribute('type', 'button');
740
+ var status = el('div', 'sstat');
741
+
742
+ var submit = function (text) {
743
+ [send, useDefault].forEach(function (b) { if (b) b.disabled = true; });
744
+ post('/answer', { init: a.init, kind: a.kind, answer: text }, status, function (ok) {
745
+ if (!ok) {
746
+ [send, useDefault].forEach(function (b) { if (b) b.disabled = false; });
747
+ return;
748
+ }
749
+ // The board re-rendered on the server before it replied, so the next
750
+ // load is already correct — and leaving an answered question on screen
751
+ // with a live box invites answering it twice.
752
+ input.disabled = true;
753
+ }, function (p) {
754
+ return (p.mode === 'default' ? 'answered with the recorded default' : 'answered')
755
+ + ': ' + p.recorded + ' \\u00b7 decision ' + p.decision + ' \\u2014 reload to refresh the board';
756
+ });
757
+ };
758
+ send.addEventListener('click', function () {
759
+ if (input.value.trim() === '') {
760
+ status.className = 'sstat bad';
761
+ status.textContent = hasDefault
762
+ ? 'type an answer, or press "Take the default"'
763
+ : 'type an answer \\u2014 this question has no default to fall back on';
764
+ return;
765
+ }
766
+ submit(input.value);
767
+ });
768
+ if (useDefault) useDefault.addEventListener('click', function () { submit(''); });
769
+
770
+ // Typing here must survive the 30-second reload, exactly like a settings
771
+ // field. Same mechanism, same reason.
772
+ //
773
+ // Wrapped, not passed: the hold-refresh helper is defined further down and
774
+ // is still undefined while these cards are built, and addEventListener with
775
+ // undefined is a silent no-op rather than an error — the listener would
776
+ // simply never exist and a half-typed answer would vanish on the next
777
+ // reload with nothing to show for it.
778
+ input.addEventListener('input', function () { holdRefresh(); });
779
+
780
+ box.appendChild(input);
781
+ acts.appendChild(send);
782
+ if (useDefault) acts.appendChild(useDefault);
783
+ box.appendChild(acts);
784
+ box.appendChild(status);
785
+ box.appendChild(el('div', 'hint', 'Answering writes a decision and closes the gate in ' + a.init + '\\u2019s journal. Needs the board started with --write.'));
786
+ return box;
787
+ };
630
788
  asks.forEach(function (a) {
631
789
  var card = el('div', 'ask');
790
+ // The one distinction that changes what an operator does about it, and it
791
+ // costs no new event type to say: an ask WITH a recorded default is a
792
+ // decision you may leave to the recommendation, and an ask without one is
793
+ // blocking, because there saying nothing has no safe outcome. That is
794
+ // already why the answer sheet sorts no-default first.
795
+ var hasDefault = a.default !== null && a.default !== undefined;
796
+ card.appendChild(el('span', 'kindtag ' + (hasDefault ? 'decision' : 'blocking'),
797
+ hasDefault ? 'decision \\u00b7 a default is recorded' : 'blocking \\u00b7 no safe default'));
632
798
  card.appendChild(el('div', 'q', a.question || '(no question recorded — gate ' + a.kind + ')'));
633
799
  [['answer with', a.kind], ['recommendation', a.recommendation], ['default', a.default],
634
800
  ['ticket', a.ticket], ['initiative', a.init], ['since', a.since]].forEach(function (pair) {
@@ -638,6 +804,7 @@ if (data.schema !== 1) {
638
804
  row.appendChild(el('span', null, pair[1]));
639
805
  card.appendChild(row);
640
806
  });
807
+ card.appendChild(replyBox(a, hasDefault));
641
808
  qs.appendChild(card);
642
809
  });
643
810
 
@@ -830,27 +997,35 @@ if (data.schema !== 1) {
830
997
  st.appendChild(stBody);
831
998
  stBody.appendChild(el('div', 'setnote', 'Settings are read from .tyran/config.yaml and .tyran/policies/autonomy.yaml, and they are served rather than embedded — open this board with "board.mjs --serve" to see them.'));
832
999
 
833
- // A meta refresh and a form are incompatible: half a typed model name would
834
- // vanish every thirty seconds. The tag stays in the HTML (a page whose JS
835
- // never runs still refreshes, and the docs sandbox strips the tag to stop
836
- // itself reloading), but at boot it is swapped for a timer that can be
837
- // paused — and the Settings tab pauses it. Present tag, same 30 seconds;
838
- // absent tag, no timer at all, which is what the sandbox wants.
839
- var refreshTag = document.querySelector('meta[http-equiv="refresh"]');
1000
+ // Auto-refresh, and the reason it is a timer rather than a meta tag.
1001
+ //
1002
+ // A real http-equiv refresh is scheduled by the browser when it PARSES the
1003
+ // tag, and removing the node afterwards does not cancel it — measured, in a
1004
+ // browser, after this page reloaded under a half-typed value that the code
1005
+ // sincerely believed it had protected. So the page carries an inert
1006
+ // tyran-refresh marker instead, and the only thing that reloads it is this
1007
+ // timer, which can be stopped while an operator is typing.
1008
+ //
1009
+ // Absent marker, no timer at all: that is what the docs sandbox wants, and
1010
+ // it gets it by stripping the marker rather than by special-casing anything.
1011
+ var refreshTag = document.querySelector('meta[name="tyran-refresh"]');
1012
+ var refreshSeconds = refreshTag === null ? 0 : Number(refreshTag.getAttribute('content'));
840
1013
  var refreshTimer = null;
841
1014
  var armRefresh = function () {
842
- if (refreshTag === null || refreshTimer !== null) return;
843
- refreshTimer = setTimeout(function () { location.reload(); }, 30000);
1015
+ if (!(refreshSeconds > 0) || refreshTimer !== null) return;
1016
+ refreshTimer = setTimeout(function () { location.reload(); }, refreshSeconds * 1000);
844
1017
  };
845
1018
  var holdRefresh = function () {
846
1019
  if (refreshTimer !== null) { clearTimeout(refreshTimer); refreshTimer = null; }
847
1020
  };
848
- if (refreshTag !== null && refreshTag.parentNode) {
849
- refreshTag.parentNode.removeChild(refreshTag);
850
- armRefresh();
851
- }
1021
+ armRefresh();
852
1022
 
853
- var post = function (route, body, status, onDone) {
1023
+ // The describe callback turns a successful payload into the sentence the
1024
+ // operator reads. Settings and answers succeed differently — one reports a
1025
+ // value that moved, the other what was recorded and under which decision id —
1026
+ // and a single hard-coded message rendered "undefined -> undefined" for the
1027
+ // route it was not written for.
1028
+ var post = function (route, body, status, onDone, describe) {
854
1029
  status.className = 'sstat';
855
1030
  status.textContent = 'saving\\u2026';
856
1031
  fetch(route, {
@@ -884,7 +1059,9 @@ if (data.schema !== 1) {
884
1059
  return;
885
1060
  }
886
1061
  status.className = 'sstat ok';
887
- status.textContent = show('saved \\u2014 ' + JSON.stringify(payload.before) + ' \\u2192 ' + JSON.stringify(payload.after));
1062
+ status.textContent = show(describe
1063
+ ? describe(payload)
1064
+ : 'saved \\u2014 ' + JSON.stringify(payload.before) + ' \\u2192 ' + JSON.stringify(payload.after));
888
1065
  if (onDone) onDone(true);
889
1066
  }).catch(function () {
890
1067
  status.className = 'sstat bad';
@@ -1112,7 +1289,7 @@ if (data.schema !== 1) {
1112
1289
  select('overview');
1113
1290
 
1114
1291
  var foot = el('footer');
1115
- foot.appendChild(el('div', null, 'GENERATED by tyran scripts/board.mjs — do not edit. Refreshes every 30 s; ages are computed in this browser.'));
1292
+ foot.appendChild(el('div', null, 'GENERATED by tyran scripts/board.mjs — do not edit. Reloads itself every 30 s unless you are editing; ages are computed in this browser.'));
1116
1293
  app.appendChild(foot);
1117
1294
  }
1118
1295
  `;
@@ -1162,7 +1339,15 @@ export function renderBoardHtml(payloadJsonText) {
1162
1339
  '<!-- GENERATED by tyran scripts/board.mjs - DO NOT EDIT. Source of truth: the journals under .tyran/state/ -->\n' +
1163
1340
  '<html lang="en"><head><meta charset="utf-8">\n' +
1164
1341
  '<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
1165
- '<meta http-equiv="refresh" content="30">\n' +
1342
+ // NOT `http-equiv="refresh"`. A real meta refresh is scheduled by the
1343
+ // browser the moment it parses the tag, and REMOVING THE NODE DOES NOT
1344
+ // CANCEL IT — measured, after this page reloaded under a half-typed model
1345
+ // name that the code sincerely believed it had protected. The tag is now
1346
+ // inert markup that only this page's own script reads, so the timer it
1347
+ // arms is one the page can actually stop while you are typing into it.
1348
+ // The page is built entirely by that script anyway, so nothing is lost:
1349
+ // a browser that cannot run it has no board to refresh.
1350
+ '<meta name="tyran-refresh" content="30">\n' +
1166
1351
  '<title>Tyran board</title>\n' +
1167
1352
  `<style>${CSS}</style>\n` +
1168
1353
  '</head><body><main id="app"></main>\n' +
package/scripts/board.mjs CHANGED
@@ -45,6 +45,8 @@ 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';
49
+ import { answerOne, answerProblem, classify, openAsks, partitionAsks, reRender } from './answer.mjs';
48
50
 
49
51
  export const BOARD_HTML_FILE = 'board.html';
50
52
 
@@ -65,8 +67,15 @@ export function readInitiativeBoards(tyranDir) {
65
67
  let names;
66
68
  try {
67
69
  names = readdirSync(stateDir).sort();
68
- } catch {
69
- return { initiatives: [], errors: [] };
70
+ } catch (err) {
71
+ // ENOENT is the legitimate fresh-repo case: setup has run, no initiative
72
+ // exists yet, and an empty board is the right answer. Anything else —
73
+ // EACCES, ENOTDIR, EIO — means we cannot TELL whether there is work here,
74
+ // and returning "no initiatives" for that is the board saying all is well
75
+ // about a directory it could not open. It is also what `--dir` pointed at
76
+ // the repo root instead of at `.tyran` looks like.
77
+ if (err?.code === 'ENOENT') return { initiatives: [], errors: [] };
78
+ return { initiatives: [], errors: [{ name: 'state', error: `${err?.code ?? 'unreadable'} reading ${join(basename(resolve(tyranDir)), 'state')}` }] };
70
79
  }
71
80
  const dirs = names.filter((name) => {
72
81
  try {
@@ -86,7 +95,17 @@ export function readInitiativeBoards(tyranDir) {
86
95
  const warned = [];
87
96
  for (const name of dirs) {
88
97
  const journal = join(stateDir, name, 'journal.jsonl');
89
- if (!existsSync(journal)) continue;
98
+ // "there is no journal here" and "I cannot tell whether there is a journal
99
+ // here" are different facts, and `existsSync` returns false for both. An
100
+ // initiative in an unreadable directory used to vanish from the board with
101
+ // nothing said — the totals simply went down by one.
102
+ try {
103
+ statSync(journal);
104
+ } catch (err) {
105
+ if (err?.code === 'ENOENT') continue;
106
+ errors.push({ name, error: `${err?.code ?? 'unreadable'} reading ${join('state', name, 'journal.jsonl')}` });
107
+ continue;
108
+ }
90
109
  try {
91
110
  const state = fold(readJournal(journal));
92
111
  // PARTIAL damage, which the guard below cannot see. That guard fires only
@@ -117,7 +136,17 @@ export function readInitiativeBoards(tyranDir) {
117
136
  // where an initiative's journal lives (ADR-21).
118
137
  initiatives.push({ name, journal, state, board: boardOf(state), files: initiativeFiles(tyranDir, name) });
119
138
  } catch (err) {
120
- errors.push({ name, error: String(err?.message ?? err) });
139
+ // The CODE and a repo-relative path, never the raw message. A Node fs
140
+ // error carries the absolute path, which means a home directory and a
141
+ // username — and this string is written into `board.json`, a committed
142
+ // artefact compared byte for byte, so it also made `--check` fail on any
143
+ // other machine.
144
+ errors.push({
145
+ name,
146
+ error: err?.code
147
+ ? `${err.code} reading ${join('state', name, 'journal.jsonl')}`
148
+ : String(err?.message ?? err),
149
+ });
121
150
  }
122
151
  }
123
152
  return { initiatives, errors, warned };
@@ -155,10 +184,20 @@ export function initiativeFiles(tyranDir, name) {
155
184
  }
156
185
 
157
186
  /** Pure merge of per-initiative boards into the one payload. */
158
- export function crossBoard({ initiatives, errors, warned = [] }) {
187
+ /**
188
+ * How many logged errors travel in the payload.
189
+ *
190
+ * `board.json` is committed and compared byte for byte, so an unbounded list
191
+ * would grow the artefact with every bad night. Newest first and a count for
192
+ * the rest: the board's job is to say something is wrong, not to be the log.
193
+ */
194
+ export const MAX_LOGGED_ERRORS = 20;
195
+
196
+ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
159
197
  const asks = [];
160
198
  const agents = [];
161
199
  const paused = [];
200
+ const logged = [];
162
201
  const files = {};
163
202
  const lanes = Object.fromEntries(LANES.map((lane) => [lane, []]));
164
203
  let merged = 0;
@@ -173,6 +212,22 @@ export function crossBoard({ initiatives, errors, warned = [] }) {
173
212
  for (const a of board.agents) agents.push({ ...a, init: name });
174
213
  if (board.paused !== null) paused.push({ ...board.paused, init: name });
175
214
  if (docs !== undefined && docs.length > 0) files[name] = docs;
215
+ // An `error` event with no ticket landed in STATE.md's Errors table and
216
+ // nowhere else: the fold collects it, and the board that exists to say
217
+ // "not all is well" carried neither `state.errors` nor the tickets an
218
+ // error named that the journal has never seen. A whole class of agent
219
+ // failure was invisible on the one screen meant to show it.
220
+ for (const e of state.errors) {
221
+ logged.push({
222
+ init: name,
223
+ class: e.class,
224
+ detail: e.detail,
225
+ ticket: e.ticket ?? null,
226
+ ticket_unknown: e.ticket_unknown === true,
227
+ ts: e.ts,
228
+ actor: e.actor,
229
+ });
230
+ }
176
231
  for (const lane of LANES) {
177
232
  for (const card of board.lanes.get(lane)) lanes[lane].push({ ...card, init: name });
178
233
  }
@@ -185,6 +240,9 @@ export function crossBoard({ initiatives, errors, warned = [] }) {
185
240
  // ISO string from the journal, so ascending string order IS ascending time;
186
241
  // an agent with no signal at all sorts to the front, where it belongs.
187
242
  agents.sort((a, b) => String(a.last_signal ?? '').localeCompare(String(b.last_signal ?? '')));
243
+ // Newest first: an error from four days ago is history, the one from ten
244
+ // minutes ago is the reason you opened this page.
245
+ logged.sort((a, b) => String(b.ts ?? '').localeCompare(String(a.ts ?? '')));
188
246
 
189
247
  return {
190
248
  schema: 1,
@@ -203,11 +261,26 @@ export function crossBoard({ initiatives, errors, warned = [] }) {
203
261
  blocked: lanes.blocked.length + lanes['changes-requested'].length
204
262
  + agents.filter((a) => a.state === 'blocked').length,
205
263
  },
264
+ // Committed repo state, so it belongs in the artefact rather than behind a
265
+ // route: `.tyran/STOP` is identical in every clone, and `--check` stays
266
+ // byte-exact. The machine-local half of "is this run supposed to be
267
+ // running" — the pause marker, the resume watcher — is served instead,
268
+ // for the same reason spend is.
269
+ // `{stopped, reason}` and NOT the path `checkStopAt` also returns: an
270
+ // absolute path in a committed, byte-compared artefact makes two clones of
271
+ // one journal disagree on a machine whose home directory is spelled
272
+ // differently. The same trap the initiative file list was caught in.
273
+ stop: stop === null ? null : { stopped: stop.stopped, reason: stop.reason },
206
274
  paused,
207
275
  asks,
208
276
  agents,
209
277
  files,
210
278
  lanes,
279
+ // The key is `errors_logged`, NOT `errors`: `errors` on this payload
280
+ // already means "this initiative's journal could not be read at all", and
281
+ // one key with two meanings is the defect ADR-21 is named after.
282
+ errors_logged: logged.slice(0, MAX_LOGGED_ERRORS),
283
+ errors_logged_total: logged.length,
211
284
  errors,
212
285
  warned,
213
286
  };
@@ -224,6 +297,11 @@ export function renderCrossMd(payload) {
224
297
  `**${t.agents} agent(s) running across ${t.initiatives} initiative(s) · ` +
225
298
  `${t.merged}/${t.tickets} tickets merged (${t.percent}%) · as of ${inline(payload.as_of)}**\n`,
226
299
  );
300
+ // First, and above the pause: a STOP outranks everything. It is the one
301
+ // state where a strip of silent agents is the system doing as it was told.
302
+ if (payload.stop?.stopped === true) {
303
+ parts.push(`\n**STOPPED** — an operator halted this repo: ${inline(payload.stop.reason)}\n`);
304
+ }
227
305
  for (const p of payload.paused) {
228
306
  parts.push(`\n**PAUSED** — ${inline(p.init)}: gate ${inline(p.kind)} (${inline(p.result)}) since ${inline(p.since)}\n`);
229
307
  }
@@ -233,6 +311,13 @@ export function renderCrossMd(payload) {
233
311
  for (const d of payload.warned ?? []) {
234
312
  for (const w of d.warnings) parts.push(`\n**WARNING** — ${inline(d.name)}: ${inline(w)}\n`);
235
313
  }
314
+ for (const e of payload.errors_logged ?? []) {
315
+ const what = `${inline(e.class ?? 'error')}${e.detail != null ? `: ${inline(e.detail)}` : ''}` +
316
+ (e.ticket_unknown ? ` — it names ticket ${inline(e.ticket)}, which this journal has never declared` : '');
317
+ parts.push(`\n**ERROR** — ${inline(e.init)}: ${what} (${inline(e.ts)})\n`);
318
+ }
319
+ const hidden = (payload.errors_logged_total ?? 0) - (payload.errors_logged ?? []).length;
320
+ if (hidden > 0) parts.push(`\n**ERROR** — and ${hidden} older error(s); read the journals for the rest\n`);
236
321
 
237
322
  parts.push('\n## Waiting on you\n\n');
238
323
  if (payload.asks.length === 0) parts.push('_none — the agents have what they need_\n');
@@ -281,7 +366,12 @@ export function renderCrossMd(payload) {
281
366
  }
282
367
 
283
368
  export function renderAll(tyranDir) {
284
- const payload = crossBoard(readInitiativeBoards(tyranDir));
369
+ const payload = crossBoard({
370
+ ...readInitiativeBoards(tyranDir),
371
+ // Named from the board's own directory rather than reconstructed from a
372
+ // repo root: `--dir` need not be spelled `.tyran`.
373
+ stop: checkStopAt(join(tyranDir, 'STOP')),
374
+ });
285
375
  const json = crossJson(payload);
286
376
  return {
287
377
  payload,
@@ -321,8 +411,13 @@ function readJsonBody(req) {
321
411
  req.on('data', (chunk) => {
322
412
  size += chunk.length;
323
413
  if (size > MAX_BODY_BYTES) {
324
- reject(new SettingsError('request body is too large'));
325
- req.destroy();
414
+ // Reject, but do NOT destroy the socket: the route's 400 is written on
415
+ // the next tick, and tearing the connection down first meant the
416
+ // client saw a network error instead of the sentence explaining what
417
+ // was wrong. Pausing stops us reading the rest without discarding the
418
+ // channel the answer goes out on.
419
+ req.pause();
420
+ reject(new SettingsError(`request body is larger than ${MAX_BODY_BYTES} bytes`));
326
421
  return;
327
422
  }
328
423
  chunks.push(chunk);
@@ -372,6 +467,47 @@ const sendJson = (res, status, body) => {
372
467
  res.end(JSON.stringify(body) + '\n');
373
468
  };
374
469
 
470
+ /**
471
+ * Answer one open question, from the page instead of from a terminal.
472
+ *
473
+ * The request supplies exactly two things: WHICH ask, and the operator's own
474
+ * words. Everything else — the question, the recorded default, the ticket, the
475
+ * gate id — is read back out of the journal, which is the same guarantee
476
+ * `answer apply` makes about its sheet: nothing you type can change what was
477
+ * asked. The append itself is `answerOne`, unchanged and unwrapped, so the
478
+ * lock, the re-check and the decision-before-gate ordering are the ones the
479
+ * CLI already uses.
480
+ */
481
+ function handleAnswer(dir, body) {
482
+ const kind = String(body.kind ?? '');
483
+ const init = String(body.init ?? '');
484
+ const text = typeof body.answer === 'string' ? body.answer : '';
485
+
486
+ const { asks } = openAsks(dir);
487
+ const { answerable } = partitionAsks(asks);
488
+ const ask = answerable.find((a) => a.kind === kind && a.init === init);
489
+ if (ask === undefined) {
490
+ throw new SettingsError(
491
+ `no open question "${kind}" in "${init}" — it may have been answered in a terminal since this page loaded. Reload.`,
492
+ );
493
+ }
494
+ const trimmed = text.trim();
495
+ const problem = answerProblem(trimmed);
496
+ if (problem !== null) throw new SettingsError(`that answer ${problem}`);
497
+
498
+ const verdict = classify(trimmed, ask);
499
+ if (verdict.mode === 'open') throw new SettingsError(verdict.why ?? 'nothing to record');
500
+ const outcome = answerOne(ask, verdict);
501
+ if (outcome.skipped !== undefined) throw new SettingsError(outcome.skipped);
502
+
503
+ // A board still showing an answered question is worse than one that never
504
+ // showed it. Re-render before replying, so the reload the page does next is
505
+ // already correct.
506
+ reRender(dir, new Map([[ask.init, ask.journal]]));
507
+ console.log(`board: answered ${ask.init}/${ask.kind} (${verdict.mode}) -> decision ${outcome.decision}`);
508
+ return { ok: true, kind: ask.kind, init: ask.init, mode: verdict.mode, decision: outcome.decision, recorded: verdict.text };
509
+ }
510
+
375
511
  /**
376
512
  * Apply one edit and write it, or change nothing and say why.
377
513
  *
@@ -388,6 +524,16 @@ function handleSettingsWrite(dir, route, body) {
388
524
  route === 'config'
389
525
  ? applySetting(dir, String(body.id ?? ''), body.value, confirm)
390
526
  : applyPolicyClass(dir, body.path === null || body.path === undefined ? null : String(body.path), String(body.class ?? ''), confirm);
527
+ // Compare-and-swap. `applySetting` reads the whole file and computes a whole
528
+ // replacement, so a second writer between the read and the write would have
529
+ // its change silently discarded — and both writers would report success.
530
+ // In-process that cannot interleave (this handler is one synchronous block),
531
+ // but two boards on one directory, or a board and a terminal, are ordinary.
532
+ if (readFileSync(applied.file, 'utf8') !== applied.before_text) {
533
+ throw new SettingsError(
534
+ `${applied.file} changed underneath this edit — something else wrote it while the page was open. Nothing was written; reload and try again.`,
535
+ );
536
+ }
391
537
  writeAtomic(applied.file, applied.text);
392
538
  // The operator's terminal is the audit trail. A change made from a web page
393
539
  // that left no trace anywhere a person looks is how a settings screen turns
@@ -440,6 +586,21 @@ function main() {
440
586
  console.error(`board: no such directory ${dir}`);
441
587
  process.exit(2);
442
588
  }
589
+ // `--dir` wants the `.tyran` directory, and pointing it at the repo root
590
+ // instead is the obvious typo. Since the renderer creates `state/` where it
591
+ // is told to, that typo used to succeed silently: a `state/` directory
592
+ // appearing in the project root, and an empty board reporting that all is
593
+ // well about a repo whose real journals sit one level down. Any ONE of these
594
+ // three is enough to recognise a Tyran directory, including a freshly set up
595
+ // one that has no initiative yet.
596
+ const looksLikeTyran = ['state', 'config.yaml', 'policies'].some((name) => existsSync(join(dir, name)));
597
+ if (!looksLikeTyran) {
598
+ console.error(
599
+ `board: ${dir} does not look like a .tyran directory — it has no state/, config.yaml or policies/. ` +
600
+ 'Point --dir at .tyran itself (run /tyran:setup first if this repo has not adopted Tyran).',
601
+ );
602
+ process.exit(2);
603
+ }
443
604
  const outDir = join(dir, 'state');
444
605
 
445
606
  if (flags.serve) {
@@ -476,8 +637,8 @@ function main() {
476
637
  sendJson(res, 200, { ...readSettings(dir), writable: flags.write });
477
638
  return;
478
639
  }
479
- if (req.url === '/settings/config' || req.url === '/settings/policy') {
480
- const route = req.url.slice('/settings/'.length);
640
+ if (req.url === '/settings/config' || req.url === '/settings/policy' || req.url === '/answer') {
641
+ const route = req.url === '/answer' ? 'answer' : req.url.slice('/settings/'.length);
481
642
  if (req.method !== 'POST') {
482
643
  sendJson(res, 405, { ok: false, error: 'this route takes POST' });
483
644
  return;
@@ -488,6 +649,10 @@ function main() {
488
649
  // that and editing the autonomy policy through it is the difference
489
650
  // this flag exists to make. The refusal names the flag, because a
490
651
  // 403 an operator cannot act on is just a bug report.
652
+ // One flag for every route that writes. Answering a question and
653
+ // editing the autonomy policy are different acts, but they are the
654
+ // same decision for the operator: whether this board may change the
655
+ // repository at all.
491
656
  if (!flags.write) {
492
657
  sendJson(res, 403, {
493
658
  ok: false,
@@ -500,7 +665,7 @@ function main() {
500
665
  return;
501
666
  }
502
667
  readJsonBody(req)
503
- .then((body) => sendJson(res, 200, handleSettingsWrite(dir, route, body)))
668
+ .then((body) => sendJson(res, 200, route === 'answer' ? handleAnswer(dir, body) : handleSettingsWrite(dir, route, body)))
504
669
  .catch((err) => {
505
670
  const known = err instanceof SettingsError;
506
671
  if (!known) console.error(`board: settings write failed: ${String(err?.message ?? err)}`);
@@ -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
@@ -290,7 +290,13 @@ export function allSettings() {
290
290
  function resolvePath(doc, path) {
291
291
  let node = doc;
292
292
  for (const segment of path) {
293
- if (node === null || typeof node !== 'object') return null;
293
+ // The REQUESTED path, never null. `limits:` is optional in a valid config
294
+ // — every install set up before it existed has none — and returning null
295
+ // here fed `readAt`'s `for (const segment of path)` an unusable value, so
296
+ // the whole Settings tab died with "path is not iterable" and every write
297
+ // became an HTTP 500. Handing the path back lets the absent-key branch do
298
+ // its job: `present: false`, and a control that says so.
299
+ if (node === null || typeof node !== 'object') return path;
294
300
  node = node[segment];
295
301
  }
296
302
  if (node !== null && typeof node === 'object' && !Array.isArray(node) && 'value' in node) {
@@ -473,7 +479,7 @@ export function applySetting(tyranDir, id, value, confirm = null) {
473
479
  if (errors.length > 0) {
474
480
  throw new SettingsError(`that change makes the config invalid, so nothing was written:\n ${errors.join('\n ')}`);
475
481
  }
476
- return { file, path, before, after: next, text };
482
+ return { file, path, before, after: next, text, before_text: loaded.text };
477
483
  }
478
484
 
479
485
  /**
@@ -538,5 +544,5 @@ export function applyPolicyClass(tyranDir, rulePath, klass, confirm = null) {
538
544
  if (errors.length > 0) {
539
545
  throw new SettingsError(`that change makes the policy invalid, so nothing was written:\n ${errors.join('\n ')}`);
540
546
  }
541
- return { file, path, before, after: klass, text };
547
+ return { file, path, before, after: klass, text, before_text: loaded.text };
542
548
  }
@@ -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()) {
package/scripts/tiers.mjs CHANGED
@@ -208,14 +208,72 @@ function clamp(value, min, max) {
208
208
  export function resolveModel(config, role, profile, risk = 'normal', override = {}) {
209
209
  const tier = resolveTier(role, profile, risk, override);
210
210
  const effort = resolveEffort(role, profile, risk, override);
211
- const alias = config?.tiers?.[tier];
212
- if (typeof alias !== 'string' || alias.length === 0) {
213
- throw new Error(`config has no model alias for tier "${tier}" — fix tiers in .tyran/config.yaml`);
214
- }
211
+ const aliasFor = (key) => {
212
+ const alias = config?.tiers?.[key];
213
+ if (typeof alias !== 'string' || alias.length === 0) {
214
+ throw new Error(`config has no model alias for tier "${key}" — fix tiers in .tyran/config.yaml`);
215
+ }
216
+ return alias;
217
+ };
215
218
  const floored =
216
219
  (ROLE_FLOOR[role] !== undefined && override.tier !== undefined && override.tier !== ROLE_FLOOR[role]) ||
217
220
  (ROLE_EFFORT_FLOOR[role] !== undefined && override.effort !== undefined && override.effort !== effort);
218
- return { tier, model: alias, effort, floored };
221
+
222
+ const unavailable = normalizeUnavailable(override.unavailable);
223
+ const resolved = { tier, model: aliasFor(tier), effort, floored, fell_from: null };
224
+ if (unavailable.length === 0 || !unavailable.includes(resolved.model)) return resolved;
225
+
226
+ const substitute = fallbackTier(config, role, tier, unavailable);
227
+ return {
228
+ tier: substitute,
229
+ model: aliasFor(substitute),
230
+ // Effort follows the ORIGINAL tier, not the substitute. The judgement
231
+ // "this task needs deep reasoning" did not change because a model ran out
232
+ // of capacity, and dropping both dials at once turns a substitution into a
233
+ // second, unasked-for downgrade.
234
+ effort,
235
+ floored,
236
+ fell_from: tier,
237
+ };
238
+ }
239
+
240
+ function normalizeUnavailable(value) {
241
+ if (value === undefined || value === null) return [];
242
+ const list = Array.isArray(value) ? value : [value];
243
+ return list.filter((v) => typeof v === 'string' && v.length > 0);
244
+ }
245
+
246
+ /**
247
+ * The next tier DOWN whose model is still available.
248
+ *
249
+ * Down, never up, and that is the answer to the question this feature was
250
+ * blocked on. A fallback that climbed would spend more than the routing table
251
+ * promised, silently, at the exact moment nobody is watching — and the whole
252
+ * point of the table is that what a run costs is legible before it runs. Down
253
+ * is also the direction the observed incident needed: the strongest tier hit
254
+ * its limit while the tier below it had capacity, and the work died rather
255
+ * than finishing on the model one step cheaper.
256
+ *
257
+ * The trade is stated rather than hidden: falling produces a WEAKER answer.
258
+ * That is why it stops at the role floor instead of walking to the bottom —
259
+ * a security review that ran on the cheapest model is not a security review,
260
+ * and the floors already say which roles those are.
261
+ */
262
+ export function fallbackTier(config, role, from, unavailable) {
263
+ const floorIndex = ROLE_FLOOR[role] === undefined ? 0 : TIER_ORDER.indexOf(ROLE_FLOOR[role]);
264
+ for (let i = TIER_ORDER.indexOf(from) - 1; i >= floorIndex; i -= 1) {
265
+ const alias = config?.tiers?.[TIER_ORDER[i]];
266
+ if (typeof alias === 'string' && alias.length > 0 && !unavailable.includes(alias)) return TIER_ORDER[i];
267
+ }
268
+ // Exhausting the ladder is NOT a substitution problem. Every model this role
269
+ // is allowed to use is unavailable, which means waiting, not routing — and
270
+ // the thing that already knows how to wait is overnight mode.
271
+ const reachable = TIER_ORDER.slice(floorIndex, TIER_ORDER.indexOf(from) + 1);
272
+ throw new Error(
273
+ `every tier "${escapeInvisible(role)}" may use is unavailable (${reachable.join(' -> ')}), so there is ` +
274
+ 'nothing to fall back to. This is a pause, not a substitution: see docs/overnight.md.' +
275
+ (ROLE_FLOOR[role] === undefined ? '' : ` The floor for this role is "${ROLE_FLOOR[role]}" and is not lowered by a fallback.`),
276
+ );
219
277
  }
220
278
 
221
279
  /** The whole routing map for one profile — what the conductor reads once. */
@@ -278,7 +336,9 @@ function main() {
278
336
  const risk = flag('risk', 'normal');
279
337
  const role = flag('role', null);
280
338
  const field = flag('field', 'model');
281
- const override = { tier: flag('tier', undefined), effort: flag('effort', undefined) };
339
+ // Repeatable: an overnight run can exhaust more than one tier.
340
+ const unavailable = args.reduce((acc, arg, i) => (arg === '--unavailable' && args[i + 1] ? [...acc, args[i + 1]] : acc), []);
341
+ const override = { tier: flag('tier', undefined), effort: flag('effort', undefined), unavailable };
282
342
 
283
343
  try {
284
344
  if (role === null) {
@@ -303,6 +363,14 @@ function main() {
303
363
  'change its model mid-flight — this is the tier your config says it should be running.',
304
364
  );
305
365
  }
366
+ // A substitution that said nothing would be the routing table quietly
367
+ // meaning something else than it says.
368
+ if (resolved.fell_from !== null) {
369
+ console.error(
370
+ `tiers: FELL BACK ${resolved.fell_from} -> ${resolved.tier} because the ${resolved.fell_from} model is ` +
371
+ 'unavailable. This is a WEAKER model than the routing table asked for; effort is unchanged.',
372
+ );
373
+ }
306
374
  console.error(`tiers: ${role} @ ${profile}/${risk} -> ${resolved.tier} · effort ${resolved.effort}`);
307
375
  if (field === 'json') console.log(JSON.stringify(resolved));
308
376
  else if (Object.hasOwn(resolved, field)) console.log(resolved[field]);
@@ -174,7 +174,11 @@ function stripComment(line, lineNo) {
174
174
 
175
175
  /** Parse a YAML-subset document into a plain JS object. */
176
176
  export function parse(text) {
177
- const rawLines = text.split('\n');
177
+ // A leading BOM is an encoding marker, not content. Left in place it becomes
178
+ // one column of "indentation" on line 1, and the parser rejected the whole
179
+ // file with "indentation must be a multiple of 2 spaces" — pointing at a
180
+ // line the operator can see nothing wrong with.
181
+ const rawLines = (text.charCodeAt(0) === 0xfeff ? text.slice(1) : text).split('\n');
178
182
  const lines = [];
179
183
  let sawDocStart = false;
180
184
  rawLines.forEach((raw, i) => {
@@ -272,7 +276,16 @@ export function parse(text) {
272
276
  return result;
273
277
  }
274
278
 
275
- function keyColonIndex(text) {
279
+ /**
280
+ * Where a mapping key ends, by this subset's own rule: the colon must be
281
+ * followed by whitespace or end-of-line.
282
+ *
283
+ * Exported for the same reason as `splitInlineComment` and `formatScalar` — an
284
+ * editor that locates a key must locate it by the rule the PARSER uses. A bare
285
+ * `indexOf(':')` finds the colon inside `a:b: 1` and lands the edit on a
286
+ * different key's line, which is a wrong write, not a failed one.
287
+ */
288
+ export function keyColonIndex(text) {
276
289
  let inSingle = false;
277
290
  let inDouble = false;
278
291
  for (let i = 0; i < text.length; i++) {
@@ -286,7 +299,8 @@ function keyColonIndex(text) {
286
299
  return -1;
287
300
  }
288
301
 
289
- function unquoteKey(raw, lineNo) {
302
+ /** A key as the parser reads it, quotes and all. Exported alongside `keyColonIndex`. */
303
+ export function unquoteKey(raw, lineNo) {
290
304
  const key = raw.trim();
291
305
  if (key === '') throw new YamlLiteError('empty key', lineNo);
292
306
  if ((key[0] === '"' && key.at(-1) === '"' && key.length > 1) ||
@@ -422,6 +436,12 @@ export function formatScalar(value) {
422
436
  Object.hasOwn(BOOL, s.toLowerCase()) ||
423
437
  s === 'null' ||
424
438
  s === '~' ||
425
- /^-?\d+(\.\d+)?$/.test(s);
439
+ // The READER's two number tests, not an approximation of them. They
440
+ // disagreed on a leading-dot decimal: `parseScalar` reads `.5` as the
441
+ // number 0.5, while this rule required a digit before the dot and so
442
+ // wrote the STRING ".5" unquoted — a value that came back as a different
443
+ // type. Found by yaml-patch's round-trip proof, which is what it is for.
444
+ /^-?\d+$/.test(s) ||
445
+ /^-?\d*\.\d+$/.test(s);
426
446
  return needsQuotes ? `'${s.replace(/'/g, "''")}'` : s;
427
447
  }
@@ -37,7 +37,7 @@
37
37
  * refused instead, with the line number, because the alternative is the
38
38
  * silent loss this whole module exists to prevent.
39
39
  */
40
- import { YamlLiteError, formatScalar, parse, splitInlineComment } from './yaml-lite.mjs';
40
+ import { YamlLiteError, formatScalar, keyColonIndex, parse, splitInlineComment, unquoteKey } from './yaml-lite.mjs';
41
41
 
42
42
  export class YamlPatchError extends Error {}
43
43
 
@@ -181,9 +181,18 @@ function locate(lines, path) {
181
181
  for (let i = from; i < to; i += 1) {
182
182
  const line = asKeyLine(lines[i], dashIndent, indent);
183
183
  if (line.blank || line.indent !== indent) continue;
184
- const colon = line.trimmed.indexOf(':');
184
+ // The PARSER's key rule, not a bare indexOf: a colon inside a key name
185
+ // (`a:b: 1`) otherwise ends the key early, and the edit lands on a
186
+ // different key's line — a wrong write rather than a failed one.
187
+ const colon = keyColonIndex(line.trimmed);
185
188
  if (colon === -1) continue;
186
- if (line.trimmed.slice(0, colon).trim().replace(/^['"]|['"]$/g, '') !== segment) continue;
189
+ let key;
190
+ try {
191
+ key = unquoteKey(line.trimmed.slice(0, colon), line.i + 1);
192
+ } catch {
193
+ continue;
194
+ }
195
+ if (key !== segment) continue;
187
196
  hit = i;
188
197
  view = line;
189
198
  break;
@@ -205,11 +214,15 @@ function locate(lines, path) {
205
214
  /**
206
215
  * Deep structural equality over the plain data yaml-lite produces.
207
216
  *
208
- * Exported so the proof at the end of `patch()` can be tested directly. It is
209
- * defence in depth with no input known to reach it — every wrong case found so
210
- * far is refused earlier, by the locator, by the comment guard, or by
211
- * `formatScalar` — so a test that goes through `patch()` cannot make it fire,
212
- * and this is the mutable logic the guarantee actually rests on.
217
+ * Exported so the proof at the end of `patch()` can be tested directly, and
218
+ * because it is the mutable logic the guarantee rests on.
219
+ *
220
+ * It is NOT unreachable, and an earlier version of this comment said it was.
221
+ * A review found the case: `formatScalar` used a stricter number pattern than
222
+ * `parseScalar`, so the string ".5" was written unquoted and read back as the
223
+ * number 0.5 — a changed type, caught here and nowhere else. That specific
224
+ * disagreement is fixed in yaml-lite, which is the right place for it; this
225
+ * check is what noticed.
213
226
  */
214
227
  export function sameValue(a, b) {
215
228
  if (a === b) return true;
@@ -242,9 +255,16 @@ function writeAt(doc, path, value) {
242
255
  /** Rewrite the value on a `key: value` line, keeping indent, comment and ending. */
243
256
  function scalarLine(line, target, value) {
244
257
  const body = target.dash ? line.trimmed.slice(2).trim() : line.trimmed;
245
- const colon = body.indexOf(':');
246
- const head = `${' '.repeat(line.indent)}${target.dash ? '- ' : ''}${body.slice(0, colon + 1)}`;
258
+ const colon = keyColonIndex(body);
247
259
  const tail = line.comment === '' ? '' : ` ${line.comment}`;
260
+ // A plain sequence item (`- npm test`) is a value with no key at all, which
261
+ // an address ending in an integer reaches. Treating it like a mapping line
262
+ // dropped the dash and shifted the indent by one, and the round-trip proof
263
+ // then blamed a NEIGHBOURING line for the indentation it had broken.
264
+ if (colon === -1) {
265
+ return `${' '.repeat(line.indent)}- ${formatScalar(value)}${tail}${line.eol}`;
266
+ }
267
+ const head = `${' '.repeat(line.indent)}${target.dash ? '- ' : ''}${body.slice(0, colon + 1)}`;
248
268
  return `${head} ${formatScalar(value)}${tail}${line.eol}`;
249
269
  }
250
270
 
@@ -256,6 +276,14 @@ function scalarLine(line, target, value) {
256
276
  * parse back to exactly the document intended.
257
277
  */
258
278
  export function patch(text, path, value) {
279
+ // A BOM is an encoding marker, not content — and `trimStart` counts it as
280
+ // whitespace, so it read as one column of indentation and the rebuilt line
281
+ // replaced it with a SPACE, producing an odd indent the parser then refused.
282
+ // Split it off here and put it back on the result, so the file keeps the
283
+ // marker it came with and nothing downstream has to know about it.
284
+ const bom = text.charCodeAt(0) === 0xfeff ? text.slice(0, 1) : '';
285
+ if (bom !== '') return bom + patch(text.slice(1), path, value);
286
+
259
287
  let before;
260
288
  try {
261
289
  before = parse(text);
@@ -300,12 +328,17 @@ function edit(text, path, value, before) {
300
328
  const body = target.dash ? line.trimmed.slice(2).trim() : line.trimmed;
301
329
  const colon = body.indexOf(':');
302
330
  const inlineValue = body.slice(colon + 1).trim();
303
- const end = inlineValue === '' ? blockEnd(lines, target.line + 1, line.indent) : target.line + 1;
331
+ // The block boundary is the KEY's indent, not the line's. On the first key
332
+ // of a sequence item (`- tags:`) the line is indented at the DASH, so
333
+ // using it ran the block to the end of the whole item and the splice took
334
+ // the item's sibling keys out with the list.
335
+ const ownIndent = target.dash ? target.keyIndent : line.indent;
336
+ const end = inlineValue === '' ? blockEnd(lines, target.line + 1, ownIndent) : target.line + 1;
304
337
  // The items' indent is the one they already have; a list with none yet
305
338
  // (`shared_zones: []`) takes the step the rest of the document uses.
306
- const discovered = childIndentOf(lines, target.line + 1, end, line.indent);
339
+ const discovered = childIndentOf(lines, target.line + 1, end, ownIndent);
307
340
  const childIndent = discovered === -1
308
- ? line.indent + documentStep(lines, first === undefined ? 0 : first.indent)
341
+ ? ownIndent + documentStep(lines, first === undefined ? 0 : first.indent)
309
342
  : discovered;
310
343
  // Rewriting the block rewrites its lines, so a comment living among the
311
344
  // items would disappear. Refusing keeps the promise this module is for.