@jjanczur/tyran 0.1.25 → 0.1.27

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.25",
14
+ "version": "0.1.27",
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.25",
3
+ "version": "0.1.27",
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,210 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.27 — 2026-08-15
4
+
5
+ The last four items of the munder-difflin plan, and the half of the model
6
+ fallback that was still missing. `NOTES-REQUESTS.md` §7 is now closed.
7
+
8
+ ### The board says whether the run is supposed to be running
9
+
10
+ Three agent chips reading "6 HOURS since last signal — likely dead" covered
11
+ four unrelated situations, and 0.1.25 could only tell you about one of them:
12
+ an operator `STOP`. That one is committed repo state and travels in the
13
+ artefact. The rest is machine-local and gitignored — the pause marker, the
14
+ resume watcher's pid, the usage sidecar — so `--serve` answers it at
15
+ **`/run.json`**, on exactly the argument spend already makes.
16
+
17
+ The page turns it into one banner above the tiles when any of three things is
18
+ true: a usage-limit pause is live, a pause was due to resume and has not, or
19
+ the resume watcher is not running. A damaged or missing file reads as absent —
20
+ this answers a question *about* the run and must never be the reason nobody can
21
+ see the board.
22
+
23
+ ### The queue knows what each question is holding up
24
+
25
+ Nine open questions sorted by age alone put the one gating six tickets wherever
26
+ it happened to fall. `deps` is resolved FORWARD everywhere else — a ticket is
27
+ `ready` when its dependencies are merged — and the reverse direction was never
28
+ computed at all.
29
+
30
+ Each ask now carries `blocks: {count, ids}`, walked transitively and skipping
31
+ merged tickets. The board sorts by it and **so does the answer sheet**, because
32
+ those are two renderings of one queue. Two deliberate limits:
33
+ no-recorded-default still sorts first (the only questions where saying nothing
34
+ has no safe outcome), and an initiative that declares no dependencies reports
35
+ `null` rather than `0` on every ask — an absence rendered as a measurement is
36
+ worse than saying nothing.
37
+
38
+ ### Signal is not evidence
39
+
40
+ The agent strip aged on `progress`, which an agent emits at will. An agent
41
+ looping without achieving anything therefore had the freshest chip on the
42
+ board — and, because the strip is stalest-first, sorted to the bottom.
43
+
44
+ Agents now carry both times: **`last_signal`** is what it said,
45
+ **`last_evidence`** is what it showed (a `report` with its `evidence[]`, a
46
+ `finding` with its proof, a `review` verdict). The strip sorts on evidence, and
47
+ an agent that has shown nothing ages from its **spawn** rather than from the
48
+ last thing it said — otherwise the chatty agent still outranks one that
49
+ produced something twenty minutes ago, which is the exact inversion this split
50
+ exists to correct.
51
+
52
+ No doctor finding for it, deliberately. The threshold separating "quiet because
53
+ the work is hard" from "quiet because nothing is happening" is not one this
54
+ project can pick for every repo, and a warning that fires on healthy agents is
55
+ one people learn to scroll past.
56
+
57
+ ### A ticket that failed twice is re-tried a tier higher
58
+
59
+ The escalation rule lived in the conductor's memory, which iron rule 7 already
60
+ names the least reliable store in the system: after a compaction, the ticket is
61
+ re-spawned at the tier that failed both times.
62
+
63
+ ```bash
64
+ node scripts/tiers.mjs --role implementer \
65
+ --journal .tyran/state/<init>/journal.jsonl --ticket T-3 --field json
66
+ # tiers: ESCALATED work -> deep after 2 failed attempt(s) on T-3 (ceiling deep).
67
+ ```
68
+
69
+ Capped twice over — two steps, and a ceiling of `deep`. A ticket that has
70
+ failed five times does not need the most expensive model in the table; it needs
71
+ a human, and the `changes-requested` lane already shows that. The same read
72
+ picks up any model an `error` event recorded as `model-unavailable` and feeds
73
+ it to the fallback, so **the exclusion is durable in the ledger** rather than
74
+ in a session that will be compacted. Escalation happens first and the fallback
75
+ second: a re-try asks for a stronger model, then discovers whether it is
76
+ available.
77
+
78
+ The weakness, stated rather than left to be found: "did this attempt fail" is
79
+ `APPROVING_RE`, written for lane assignment — "approved with nits" escalates
80
+ nothing and "looks fine" escalates. And a journal that cannot be read routes as
81
+ a first attempt, loudly, because routing must never depend on a readable
82
+ journal.
83
+
84
+ **Detection is still not automatic.** The limit surfaces inside a subagent's
85
+ API call where no hook can see it, so something still has to notice and write
86
+ the `error` event down. That seam is recorded in `NOTES-REQUESTS.md` rather
87
+ than papered over.
88
+
89
+ ### Left alone on purpose
90
+
91
+ `budget:` in the config schema is dead weight — validated, read by nothing —
92
+ and it stays. Removing a key from the `known` list makes every config that
93
+ carries it invalid, and an invalid config makes the policy gate refuse every
94
+ write in that repo. The cost lands on whoever set the key; the benefit is a
95
+ shorter array.
96
+
97
+ ## 0.1.26 — 2026-08-15
98
+
99
+ ### Answer a question from the board
100
+
101
+ The last context switch in the operator loop is gone. Every question in the
102
+ **Waiting on you** tab now carries a box: type an answer and press **Answer**,
103
+ or press **Take the default** on a question that records one. The three
104
+ `answer render / edit / apply` commands still work and stay printed on the tab —
105
+ the box is a convenience, and a board opened over `file://` or without
106
+ `--write` has to leave you somewhere to go.
107
+
108
+ The request carries exactly two things: **which** ask, and your words. The
109
+ question, the recorded default, the ticket and the gate id are all read back
110
+ out of the journal by the server — the same guarantee the answer sheet makes,
111
+ for the same reason. The append is `answerOne`, the function `answer apply`
112
+ already calls, unwrapped: both routes produce byte-identical events, the gate
113
+ is re-checked INSIDE the journal's write lock so a question closed in a
114
+ terminal thirty seconds ago cannot be closed twice, and the decision is written
115
+ before the gate.
116
+
117
+ Each card also says which kind of question it is, and that costs no new event
118
+ type: **decision · a default is recorded** means saying nothing has a safe
119
+ outcome; **blocking · no safe default** means it waits for you. It is the same
120
+ distinction that already makes the answer sheet sort no-default-first.
121
+
122
+ ### A tier that runs out of capacity falls to the next one down
123
+
124
+ Measured on a real run: the strongest tier hit its limit and the subagents
125
+ **failed** rather than finishing on the tier below, which had capacity the
126
+ whole time.
127
+
128
+ ```bash
129
+ node scripts/tiers.mjs --role acceptance --unavailable fable --field json
130
+ # tiers: FELL BACK top -> deep because the top model is unavailable.
131
+ ```
132
+
133
+ **Down the ladder, never up** — which is the answer to the question this was
134
+ blocked on. Climbing would spend more than the routing table promised,
135
+ silently, at exactly the moment nobody is watching. Three things the fall does
136
+ not do: it does not lower the **effort** (that judgement did not change because
137
+ a model ran out of capacity), it does not cross a **role floor** (a security
138
+ review on the cheapest model is not a security review), and it does not
139
+ **pretend** — the substitution is announced, and `fell_from` records it. When
140
+ every tier a role may use is unavailable, it exits 2 rather than returning the
141
+ bottom of the ladder: that is a pause, not a substitution, and overnight mode
142
+ is what knows how to wait.
143
+
144
+ ### Twelve confirmed findings from an adversarial review of 0.1.24 and 0.1.25
145
+
146
+ Five lenses attacked the shipped code and each finding was re-attacked
147
+ independently. Two were serious:
148
+
149
+ - **A config with no `limits:` block killed the whole Settings tab.** That
150
+ block is optional and every install set up before 0.1.24 has none, so
151
+ `resolvePath` returned null, `readAt` tried to iterate it, and the tab
152
+ rendered "the board server did not answer" while the server answered every
153
+ request. Every write on such a repo was an HTTP 500 in the terminal the docs
154
+ designate as the audit trail.
155
+ - **The page could reload under a half-typed value.** A `meta http-equiv=refresh`
156
+ is scheduled by the browser when it parses the tag, and REMOVING THE NODE
157
+ DOES NOT CANCEL IT — the code sincerely believed otherwise, in a comment. The
158
+ page now carries an inert marker only its own script reads, so the single
159
+ reload path is a timer it can actually stop.
160
+
161
+ And:
162
+
163
+ - **An unreadable journal wrote an absolute path** — a home directory and a
164
+ username — into `board.json`, which is committed and compared byte for byte,
165
+ so it also failed `--check` on every other machine. Now the error code and a
166
+ repo-relative path.
167
+ - **An initiative whose directory could not be read vanished** from the board
168
+ with nothing said; the totals just went down by one. `existsSync` cannot tell
169
+ "there is no journal here" from "I cannot tell whether there is one".
170
+ - **`--dir` pointed at the repo root silently succeeded**, creating a `state/`
171
+ directory in the wrong place and reporting that all was well about a repo
172
+ whose real journals sat one level down.
173
+ - **The settings write had no compare-and-swap.** Two boards on one directory,
174
+ or a board and a terminal, could discard each other's change with both
175
+ reporting success.
176
+ - Plus a wrong number in the CHANGELOG, an overclaim in `docs/configuration.md`
177
+ (`pricing:` and `main_writable_paths:` have no knob), a lane emptied by the
178
+ filter showing no placeholder, a stale "Four tabs" comment, one of ten lanes
179
+ unaccounted for in the stalled-card prose, and two unverifiable claims about
180
+ the sandbox.
181
+
182
+ ### yaml-lite: the writer and the reader disagreed about numbers
183
+
184
+ `formatScalar` required a digit before the decimal point and `parseScalar` did
185
+ not, so the **string** `.5` was written unquoted and read back as the **number**
186
+ 0.5. Both now use the reader's two patterns. This was found by `yaml-patch`'s
187
+ round-trip proof — the guard whose comment claimed no input was known to reach
188
+ it. That claim is now corrected rather than repeated.
189
+
190
+ A leading **BOM** is also handled: `trimStart` counts it as whitespace, so it
191
+ read as one column of indentation and the parser rejected the whole file with a
192
+ complaint about a line the operator could see nothing wrong with.
193
+
194
+ Three more in the patcher, each of which wrote or refused the wrong thing: a
195
+ key was located with `indexOf(':')` rather than the parser's own rule (so `a`
196
+ landed on the `a:b` line), a path ending in an integer dropped the list item's
197
+ dash, and replacing a list that is the FIRST key of a sequence item deleted the
198
+ item's sibling keys.
199
+
200
+ ### The backtick guard
201
+
202
+ The whole browser client is one template literal, so a backtick anywhere inside
203
+ it — including in a comment — ends the literal and the page stops loading. It
204
+ happened four times in one sitting. The parse test caught it every time and
205
+ could never say so: it reports whatever identifier followed the stray backtick.
206
+ A new guard reads the source as text, imports nothing, and names the line.
207
+
3
208
  ## 0.1.25 — 2026-08-15
4
209
 
5
210
  ### The sandbox is now Tyran building Tyran
@@ -17,8 +222,8 @@ browser verbatim; the hook payload does not carry `rate_limits` and a plugin
17
222
  cannot install a statusline. Every logged error is one that happened, including
18
223
  the backtick in a comment that terminated the client's template literal.
19
224
 
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
225
+ All ten lanes are populated, five agents run at ages from about twenty minutes
226
+ to three hours, two questions wait on the operator, and the banner's counts are read
22
227
  from the payload rather than typed — it said "two invented initiatives" for a
23
228
  release after a third was added.
24
229
 
@@ -30,8 +235,9 @@ release after a third was added.
30
235
  was wrong on the one page whose job is to show what the product looks like.
31
236
  - **The test that was supposed to catch that validated nothing.**
32
237
  `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.
238
+ events, so it read an empty journal and returned `ok` — it was asserting
239
+ that nothing had no errors. The replacement journals tripped it thirteen
240
+ times on the first honest run.
35
241
  - **An `error` event that named a ticket produced two rows on the board**, one
36
242
  from `state.errors` and one from `unknownErrorTickets`. The ticket now
37
243
  travels on the error itself, where a consumer that wants both can have both
@@ -87,7 +293,7 @@ the difference the flag exists to make.
87
293
  comments were expendable because the screen could carry the explanations. That
88
294
  turned out not to be necessary: `scripts/yaml-patch.mjs` rewrites the line
89
295
  that owns a value rather than round-tripping the document through a
90
- serializer, so `templates/config.yaml` keeps all 60 of its comment lines — the
296
+ serializer, so `templates/config.yaml` keeps all 63 of its comment lines — the
91
297
  only place anyone is told that bare `off` is the YAML boolean false, which is
92
298
  also the value that would have silently changed meaning had this been done the
93
299
  obvious way.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.25",
3
+ "version": "0.1.27",
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": {
@@ -146,8 +146,16 @@ export function openAsks(tyranDir) {
146
146
  */
147
147
  export function sortAsks(asks) {
148
148
  return [...asks].sort(
149
+ // No-default FIRST, and that stays primary: those are the only questions
150
+ // where saying nothing has no safe outcome, which is a stronger claim on
151
+ // the operator than any amount of downstream work.
149
152
  (a, b) =>
150
153
  Number(a.default != null) - Number(b.default != null) ||
154
+ // Then blast radius. Nine questions sorted by age alone put the one
155
+ // gating six tickets wherever it happened to fall; `blocks` is null on a
156
+ // journal that declares no dependencies, and null sorts as zero so those
157
+ // queues keep their old order exactly.
158
+ (b.blocks?.count ?? 0) - (a.blocks?.count ?? 0) ||
151
159
  String(a.since ?? '').localeCompare(String(b.since ?? '')) ||
152
160
  naturalCompare(a.init, b.init) ||
153
161
  naturalCompare(a.kind, b.kind),
@@ -570,7 +578,19 @@ export function applySheet(tyranDir, sheetText, { dryRun = false } = {}) {
570
578
  /** One ask's two appends, or the reason nothing was written for it. A lock
571
579
  * this run could not take is reported like any other unwritten ask: the run
572
580
  * that holds it is writing the same sitting, and a thrown error here would
573
- * abandon the asks after this one without saying so. */
581
+ * abandon the asks after this one without saying so.
582
+ *
583
+ * Exported because the board answers questions too. A second implementation
584
+ * there would be a second place that decides what "answering" means — and the
585
+ * two properties that matter are both in here: the re-check of `askState`
586
+ * INSIDE the lock, so a question answered in a terminal thirty seconds ago is
587
+ * not answered twice, and decision-before-gate, so a crash between the two
588
+ * leaves a visible orphan decision rather than a closed question with no
589
+ * answer. */
590
+ export function answerOne(ask, verdict) {
591
+ return sittingOutcome(ask, verdict);
592
+ }
593
+
574
594
  function sittingOutcome(ask, verdict) {
575
595
  try {
576
596
  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
@@ -157,6 +157,15 @@ h3{font-family:var(--font);color:var(--heading);font-size:.85rem;margin:1.1rem 0
157
157
  .ask .q{color:var(--brass-bright);font-size:1rem;font-weight:600}
158
158
  .ask .row{margin-top:.22rem;font-size:.86rem}
159
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}
160
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}
161
170
  pre.how .c{color:var(--muted)}
162
171
 
@@ -431,6 +440,15 @@ if (data.schema !== 1) {
431
440
  : ageMs >= 10800000 ? Math.round(ageMs / 3600000) + ' HOURS since last signal — likely dead'
432
441
  : Math.round(ageMs / 60000) + ' min since last signal';
433
442
  chip.appendChild(el('div', ageClass(ageMs), ageText));
443
+ // Signal is what the agent SAID; evidence is what it SHOWED. An agent
444
+ // emitting progress every few minutes while achieving nothing is the
445
+ // healthiest-looking chip on the board, and the strip is sorted by the
446
+ // first of those two, so it also sorts to the bottom.
447
+ var evMs = ageMsOf(a.last_evidence);
448
+ chip.appendChild(el('div', evMs === null ? 'age-cold' : ageClass(evMs),
449
+ evMs === null
450
+ ? 'nothing shown yet'
451
+ : (a.evidence_kind || 'evidence') + ' ' + ago(a.last_evidence)));
434
452
  strip.appendChild(chip);
435
453
  });
436
454
  return strip;
@@ -637,8 +655,14 @@ if (data.schema !== 1) {
637
655
  var count = el('span', 'count', ' (' + cards.length + ')');
638
656
  h.appendChild(count);
639
657
  box.appendChild(h);
658
+ // Appended ALWAYS, hidden when it is not wanted. It used to be appended
659
+ // only for a lane that was empty at build time, so a lane emptied by the
660
+ // filter showed a heading, a count of "0 of 4", and then nothing — and the
661
+ // display toggle below was setting a style on a node that was not in the
662
+ // document.
640
663
  var emptyMark = el('div', 'empty', '—');
641
- if (cards.length === 0) box.appendChild(emptyMark);
664
+ box.appendChild(emptyMark);
665
+ emptyMark.style.display = cards.length === 0 ? '' : 'none';
642
666
  var buttons = [];
643
667
  cards.forEach(function (c) {
644
668
  var button = el('button', 'card');
@@ -702,10 +726,87 @@ if (data.schema !== 1) {
702
726
  'npx @jjanczur/tyran answer apply --dir .tyran # closes what you answered';
703
727
  qs.appendChild(how);
704
728
  if (asks.length === 0) qs.appendChild(el('div', 'empty', 'nothing — the agents have what they need'));
729
+
730
+ // Answering from the page. The three commands above still work and stay
731
+ // printed: this box is a convenience, not a replacement, and a board opened
732
+ // over file:// or without --write has to leave the operator somewhere to go.
733
+ //
734
+ // The request carries only WHICH ask and the operator's own words. The
735
+ // question, the recorded default, the ticket and the gate id are all read
736
+ // back out of the journal by the server — the same guarantee the answer
737
+ // sheet makes, for the same reason.
738
+ var replyBox = function (a, hasDefault) {
739
+ var box = el('div', 'reply');
740
+ var input = el('textarea');
741
+ input.placeholder = hasDefault
742
+ ? 'Your answer, in your own words \\u2014 or use the default button.'
743
+ : 'Your answer, in your own words. There is no recorded default for this one.';
744
+ var acts = el('div', 'acts');
745
+ var send = el('button', 'sbtn', 'Answer');
746
+ send.setAttribute('type', 'button');
747
+ var useDefault = hasDefault ? el('button', 'sbtn', 'Take the default') : null;
748
+ if (useDefault) useDefault.setAttribute('type', 'button');
749
+ var status = el('div', 'sstat');
750
+
751
+ var submit = function (text) {
752
+ [send, useDefault].forEach(function (b) { if (b) b.disabled = true; });
753
+ post('/answer', { init: a.init, kind: a.kind, answer: text }, status, function (ok) {
754
+ if (!ok) {
755
+ [send, useDefault].forEach(function (b) { if (b) b.disabled = false; });
756
+ return;
757
+ }
758
+ // The board re-rendered on the server before it replied, so the next
759
+ // load is already correct — and leaving an answered question on screen
760
+ // with a live box invites answering it twice.
761
+ input.disabled = true;
762
+ }, function (p) {
763
+ return (p.mode === 'default' ? 'answered with the recorded default' : 'answered')
764
+ + ': ' + p.recorded + ' \\u00b7 decision ' + p.decision + ' \\u2014 reload to refresh the board';
765
+ });
766
+ };
767
+ send.addEventListener('click', function () {
768
+ if (input.value.trim() === '') {
769
+ status.className = 'sstat bad';
770
+ status.textContent = hasDefault
771
+ ? 'type an answer, or press "Take the default"'
772
+ : 'type an answer \\u2014 this question has no default to fall back on';
773
+ return;
774
+ }
775
+ submit(input.value);
776
+ });
777
+ if (useDefault) useDefault.addEventListener('click', function () { submit(''); });
778
+
779
+ // Typing here must survive the 30-second reload, exactly like a settings
780
+ // field. Same mechanism, same reason.
781
+ //
782
+ // Wrapped, not passed: the hold-refresh helper is defined further down and
783
+ // is still undefined while these cards are built, and addEventListener with
784
+ // undefined is a silent no-op rather than an error — the listener would
785
+ // simply never exist and a half-typed answer would vanish on the next
786
+ // reload with nothing to show for it.
787
+ input.addEventListener('input', function () { holdRefresh(); });
788
+
789
+ box.appendChild(input);
790
+ acts.appendChild(send);
791
+ if (useDefault) acts.appendChild(useDefault);
792
+ box.appendChild(acts);
793
+ box.appendChild(status);
794
+ box.appendChild(el('div', 'hint', 'Answering writes a decision and closes the gate in ' + a.init + '\\u2019s journal. Needs the board started with --write.'));
795
+ return box;
796
+ };
705
797
  asks.forEach(function (a) {
706
798
  var card = el('div', 'ask');
799
+ // The one distinction that changes what an operator does about it, and it
800
+ // costs no new event type to say: an ask WITH a recorded default is a
801
+ // decision you may leave to the recommendation, and an ask without one is
802
+ // blocking, because there saying nothing has no safe outcome. That is
803
+ // already why the answer sheet sorts no-default first.
804
+ var hasDefault = a.default !== null && a.default !== undefined;
805
+ card.appendChild(el('span', 'kindtag ' + (hasDefault ? 'decision' : 'blocking'),
806
+ hasDefault ? 'decision \\u00b7 a default is recorded' : 'blocking \\u00b7 no safe default'));
707
807
  card.appendChild(el('div', 'q', a.question || '(no question recorded — gate ' + a.kind + ')'));
708
808
  [['answer with', a.kind], ['recommendation', a.recommendation], ['default', a.default],
809
+ ['blocks', a.blocks && a.blocks.count > 0 ? a.blocks.count + ' ticket(s): ' + a.blocks.ids.join(', ') : null],
709
810
  ['ticket', a.ticket], ['initiative', a.init], ['since', a.since]].forEach(function (pair) {
710
811
  if (pair[1] === null || pair[1] === undefined) return;
711
812
  var row = el('div', 'row');
@@ -713,6 +814,7 @@ if (data.schema !== 1) {
713
814
  row.appendChild(el('span', null, pair[1]));
714
815
  card.appendChild(row);
715
816
  });
817
+ card.appendChild(replyBox(a, hasDefault));
716
818
  qs.appendChild(card);
717
819
  });
718
820
 
@@ -905,27 +1007,35 @@ if (data.schema !== 1) {
905
1007
  st.appendChild(stBody);
906
1008
  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.'));
907
1009
 
908
- // A meta refresh and a form are incompatible: half a typed model name would
909
- // vanish every thirty seconds. The tag stays in the HTML (a page whose JS
910
- // never runs still refreshes, and the docs sandbox strips the tag to stop
911
- // itself reloading), but at boot it is swapped for a timer that can be
912
- // paused — and the Settings tab pauses it. Present tag, same 30 seconds;
913
- // absent tag, no timer at all, which is what the sandbox wants.
914
- var refreshTag = document.querySelector('meta[http-equiv="refresh"]');
1010
+ // Auto-refresh, and the reason it is a timer rather than a meta tag.
1011
+ //
1012
+ // A real http-equiv refresh is scheduled by the browser when it PARSES the
1013
+ // tag, and removing the node afterwards does not cancel it — measured, in a
1014
+ // browser, after this page reloaded under a half-typed value that the code
1015
+ // sincerely believed it had protected. So the page carries an inert
1016
+ // tyran-refresh marker instead, and the only thing that reloads it is this
1017
+ // timer, which can be stopped while an operator is typing.
1018
+ //
1019
+ // Absent marker, no timer at all: that is what the docs sandbox wants, and
1020
+ // it gets it by stripping the marker rather than by special-casing anything.
1021
+ var refreshTag = document.querySelector('meta[name="tyran-refresh"]');
1022
+ var refreshSeconds = refreshTag === null ? 0 : Number(refreshTag.getAttribute('content'));
915
1023
  var refreshTimer = null;
916
1024
  var armRefresh = function () {
917
- if (refreshTag === null || refreshTimer !== null) return;
918
- refreshTimer = setTimeout(function () { location.reload(); }, 30000);
1025
+ if (!(refreshSeconds > 0) || refreshTimer !== null) return;
1026
+ refreshTimer = setTimeout(function () { location.reload(); }, refreshSeconds * 1000);
919
1027
  };
920
1028
  var holdRefresh = function () {
921
1029
  if (refreshTimer !== null) { clearTimeout(refreshTimer); refreshTimer = null; }
922
1030
  };
923
- if (refreshTag !== null && refreshTag.parentNode) {
924
- refreshTag.parentNode.removeChild(refreshTag);
925
- armRefresh();
926
- }
927
-
928
- var post = function (route, body, status, onDone) {
1031
+ armRefresh();
1032
+
1033
+ // The describe callback turns a successful payload into the sentence the
1034
+ // operator reads. Settings and answers succeed differently — one reports a
1035
+ // value that moved, the other what was recorded and under which decision id —
1036
+ // and a single hard-coded message rendered "undefined -> undefined" for the
1037
+ // route it was not written for.
1038
+ var post = function (route, body, status, onDone, describe) {
929
1039
  status.className = 'sstat';
930
1040
  status.textContent = 'saving\\u2026';
931
1041
  fetch(route, {
@@ -959,7 +1069,9 @@ if (data.schema !== 1) {
959
1069
  return;
960
1070
  }
961
1071
  status.className = 'sstat ok';
962
- status.textContent = show('saved \\u2014 ' + JSON.stringify(payload.before) + ' \\u2192 ' + JSON.stringify(payload.after));
1072
+ status.textContent = show(describe
1073
+ ? describe(payload)
1074
+ : 'saved \\u2014 ' + JSON.stringify(payload.before) + ' \\u2192 ' + JSON.stringify(payload.after));
963
1075
  if (onDone) onDone(true);
964
1076
  }).catch(function () {
965
1077
  status.className = 'sstat bad';
@@ -1155,6 +1267,36 @@ if (data.schema !== 1) {
1155
1267
  });
1156
1268
  });
1157
1269
 
1270
+ // Machine-local run state, fetched beside spend. A 404 means this page is
1271
+ // not being served by a board server — a copy on a docs site, a file behind
1272
+ // some other host — and that is an answer, not a failure.
1273
+ fetch('run.json', { headers: { accept: 'application/json' } })
1274
+ .then(function (r) { return r.ok ? r.json() : null; })
1275
+ .then(function (run) {
1276
+ if (run === null || run.schema !== 1) return;
1277
+ var lines = [];
1278
+ if (run.paused) {
1279
+ lines.push(run.paused.overdue
1280
+ ? 'A usage-limit pause was due to resume ' + ago(run.paused.resume_at) + ' and has not.'
1281
+ : 'Paused on the ' + (run.paused.window || 'usage') + ' window at ' +
1282
+ (run.paused.used_percentage === null ? 'the threshold' : run.paused.used_percentage + '%') +
1283
+ '. Resumes ' + (run.paused.wait || 'later') + '.');
1284
+ }
1285
+ if (run.watcher && run.watcher.alive === false) {
1286
+ lines.push('The resume watcher is not running, so nothing will restart this by itself.');
1287
+ }
1288
+ if (run.usage && run.usage.stale === true) {
1289
+ lines.push('Usage telemetry is stale — the statusline helper may not be installed.');
1290
+ }
1291
+ if (lines.length === 0) return;
1292
+ var box = el('div', 'paused');
1293
+ box.appendChild(el('b', null, 'This run is not simply working. '));
1294
+ lines.forEach(function (line) { box.appendChild(el('div', 'hint', line)); });
1295
+ box.appendChild(el('div', 'hint', 'npx @jjanczur/tyran overnight status --dir .tyran'));
1296
+ ov.insertBefore(box, ov.firstChild);
1297
+ })
1298
+ .catch(function () { /* no server, or none of this applies */ });
1299
+
1158
1300
  fetch('settings.json', { headers: { accept: 'application/json' } })
1159
1301
  .then(function (r) { return r.ok ? r.json() : Promise.reject(new Error(String(r.status))); })
1160
1302
  .then(function (payload) {
@@ -1187,7 +1329,7 @@ if (data.schema !== 1) {
1187
1329
  select('overview');
1188
1330
 
1189
1331
  var foot = el('footer');
1190
- foot.appendChild(el('div', null, 'GENERATED by tyran scripts/board.mjs — do not edit. Refreshes every 30 s; ages are computed in this browser.'));
1332
+ 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.'));
1191
1333
  app.appendChild(foot);
1192
1334
  }
1193
1335
  `;
@@ -1237,7 +1379,15 @@ export function renderBoardHtml(payloadJsonText) {
1237
1379
  '<!-- GENERATED by tyran scripts/board.mjs - DO NOT EDIT. Source of truth: the journals under .tyran/state/ -->\n' +
1238
1380
  '<html lang="en"><head><meta charset="utf-8">\n' +
1239
1381
  '<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
1240
- '<meta http-equiv="refresh" content="30">\n' +
1382
+ // NOT `http-equiv="refresh"`. A real meta refresh is scheduled by the
1383
+ // browser the moment it parses the tag, and REMOVING THE NODE DOES NOT
1384
+ // CANCEL IT — measured, after this page reloaded under a half-typed model
1385
+ // name that the code sincerely believed it had protected. The tag is now
1386
+ // inert markup that only this page's own script reads, so the timer it
1387
+ // arms is one the page can actually stop while you are typing into it.
1388
+ // The page is built entirely by that script anyway, so nothing is lost:
1389
+ // a browser that cannot run it has no board to refresh.
1390
+ '<meta name="tyran-refresh" content="30">\n' +
1241
1391
  '<title>Tyran board</title>\n' +
1242
1392
  `<style>${CSS}</style>\n` +
1243
1393
  '</head><body><main id="app"></main>\n' +