@jjanczur/tyran 0.1.25 → 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.25",
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.25",
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,116 @@
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
+
3
114
  ## 0.1.25 — 2026-08-15
4
115
 
5
116
  ### The sandbox is now Tyran building Tyran
@@ -17,8 +128,8 @@ browser verbatim; the hook payload does not carry `rate_limits` and a plugin
17
128
  cannot install a statusline. Every logged error is one that happened, including
18
129
  the backtick in a comment that terminated the client's template literal.
19
130
 
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
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
22
133
  from the payload rather than typed — it said "two invented initiatives" for a
23
134
  release after a third was added.
24
135
 
@@ -30,8 +141,9 @@ release after a third was added.
30
141
  was wrong on the one page whose job is to show what the product looks like.
31
142
  - **The test that was supposed to catch that validated nothing.**
32
143
  `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.
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.
35
147
  - **An `error` event that named a ticket produced two rows on the board**, one
36
148
  from `state.errors` and one from `unknownErrorTickets`. The ticket now
37
149
  travels on the error itself, where a consumer that wants both can have both
@@ -87,7 +199,7 @@ the difference the flag exists to make.
87
199
  comments were expendable because the screen could carry the explanations. That
88
200
  turned out not to be necessary: `scripts/yaml-patch.mjs` rewrites the line
89
201
  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
202
+ serializer, so `templates/config.yaml` keeps all 63 of its comment lines — the
91
203
  only place anyone is told that bare `off` is the YAML boolean false, which is
92
204
  also the value that would have silently changed meaning had this been done the
93
205
  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.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
@@ -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
 
@@ -637,8 +646,14 @@ if (data.schema !== 1) {
637
646
  var count = el('span', 'count', ' (' + cards.length + ')');
638
647
  h.appendChild(count);
639
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.
640
654
  var emptyMark = el('div', 'empty', '—');
641
- if (cards.length === 0) box.appendChild(emptyMark);
655
+ box.appendChild(emptyMark);
656
+ emptyMark.style.display = cards.length === 0 ? '' : 'none';
642
657
  var buttons = [];
643
658
  cards.forEach(function (c) {
644
659
  var button = el('button', 'card');
@@ -702,8 +717,84 @@ if (data.schema !== 1) {
702
717
  'npx @jjanczur/tyran answer apply --dir .tyran # closes what you answered';
703
718
  qs.appendChild(how);
704
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
+ };
705
788
  asks.forEach(function (a) {
706
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'));
707
798
  card.appendChild(el('div', 'q', a.question || '(no question recorded — gate ' + a.kind + ')'));
708
799
  [['answer with', a.kind], ['recommendation', a.recommendation], ['default', a.default],
709
800
  ['ticket', a.ticket], ['initiative', a.init], ['since', a.since]].forEach(function (pair) {
@@ -713,6 +804,7 @@ if (data.schema !== 1) {
713
804
  row.appendChild(el('span', null, pair[1]));
714
805
  card.appendChild(row);
715
806
  });
807
+ card.appendChild(replyBox(a, hasDefault));
716
808
  qs.appendChild(card);
717
809
  });
718
810
 
@@ -905,27 +997,35 @@ if (data.schema !== 1) {
905
997
  st.appendChild(stBody);
906
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.'));
907
999
 
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"]');
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'));
915
1013
  var refreshTimer = null;
916
1014
  var armRefresh = function () {
917
- if (refreshTag === null || refreshTimer !== null) return;
918
- refreshTimer = setTimeout(function () { location.reload(); }, 30000);
1015
+ if (!(refreshSeconds > 0) || refreshTimer !== null) return;
1016
+ refreshTimer = setTimeout(function () { location.reload(); }, refreshSeconds * 1000);
919
1017
  };
920
1018
  var holdRefresh = function () {
921
1019
  if (refreshTimer !== null) { clearTimeout(refreshTimer); refreshTimer = null; }
922
1020
  };
923
- if (refreshTag !== null && refreshTag.parentNode) {
924
- refreshTag.parentNode.removeChild(refreshTag);
925
- armRefresh();
926
- }
927
-
928
- var post = function (route, body, status, onDone) {
1021
+ armRefresh();
1022
+
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) {
929
1029
  status.className = 'sstat';
930
1030
  status.textContent = 'saving\\u2026';
931
1031
  fetch(route, {
@@ -959,7 +1059,9 @@ if (data.schema !== 1) {
959
1059
  return;
960
1060
  }
961
1061
  status.className = 'sstat ok';
962
- 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));
963
1065
  if (onDone) onDone(true);
964
1066
  }).catch(function () {
965
1067
  status.className = 'sstat bad';
@@ -1187,7 +1289,7 @@ if (data.schema !== 1) {
1187
1289
  select('overview');
1188
1290
 
1189
1291
  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.'));
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.'));
1191
1293
  app.appendChild(foot);
1192
1294
  }
1193
1295
  `;
@@ -1237,7 +1339,15 @@ export function renderBoardHtml(payloadJsonText) {
1237
1339
  '<!-- GENERATED by tyran scripts/board.mjs - DO NOT EDIT. Source of truth: the journals under .tyran/state/ -->\n' +
1238
1340
  '<html lang="en"><head><meta charset="utf-8">\n' +
1239
1341
  '<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
1240
- '<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' +
1241
1351
  '<title>Tyran board</title>\n' +
1242
1352
  `<style>${CSS}</style>\n` +
1243
1353
  '</head><body><main id="app"></main>\n' +
package/scripts/board.mjs CHANGED
@@ -46,6 +46,7 @@ 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
48
  import { checkStopAt } from './stop-check.mjs';
49
+ import { answerOne, answerProblem, classify, openAsks, partitionAsks, reRender } from './answer.mjs';
49
50
 
50
51
  export const BOARD_HTML_FILE = 'board.html';
51
52
 
@@ -66,8 +67,15 @@ export function readInitiativeBoards(tyranDir) {
66
67
  let names;
67
68
  try {
68
69
  names = readdirSync(stateDir).sort();
69
- } catch {
70
- 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')}` }] };
71
79
  }
72
80
  const dirs = names.filter((name) => {
73
81
  try {
@@ -87,7 +95,17 @@ export function readInitiativeBoards(tyranDir) {
87
95
  const warned = [];
88
96
  for (const name of dirs) {
89
97
  const journal = join(stateDir, name, 'journal.jsonl');
90
- 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
+ }
91
109
  try {
92
110
  const state = fold(readJournal(journal));
93
111
  // PARTIAL damage, which the guard below cannot see. That guard fires only
@@ -118,7 +136,17 @@ export function readInitiativeBoards(tyranDir) {
118
136
  // where an initiative's journal lives (ADR-21).
119
137
  initiatives.push({ name, journal, state, board: boardOf(state), files: initiativeFiles(tyranDir, name) });
120
138
  } catch (err) {
121
- 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
+ });
122
150
  }
123
151
  }
124
152
  return { initiatives, errors, warned };
@@ -383,8 +411,13 @@ function readJsonBody(req) {
383
411
  req.on('data', (chunk) => {
384
412
  size += chunk.length;
385
413
  if (size > MAX_BODY_BYTES) {
386
- reject(new SettingsError('request body is too large'));
387
- 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`));
388
421
  return;
389
422
  }
390
423
  chunks.push(chunk);
@@ -434,6 +467,47 @@ const sendJson = (res, status, body) => {
434
467
  res.end(JSON.stringify(body) + '\n');
435
468
  };
436
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
+
437
511
  /**
438
512
  * Apply one edit and write it, or change nothing and say why.
439
513
  *
@@ -450,6 +524,16 @@ function handleSettingsWrite(dir, route, body) {
450
524
  route === 'config'
451
525
  ? applySetting(dir, String(body.id ?? ''), body.value, confirm)
452
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
+ }
453
537
  writeAtomic(applied.file, applied.text);
454
538
  // The operator's terminal is the audit trail. A change made from a web page
455
539
  // that left no trace anywhere a person looks is how a settings screen turns
@@ -502,6 +586,21 @@ function main() {
502
586
  console.error(`board: no such directory ${dir}`);
503
587
  process.exit(2);
504
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
+ }
505
604
  const outDir = join(dir, 'state');
506
605
 
507
606
  if (flags.serve) {
@@ -538,8 +637,8 @@ function main() {
538
637
  sendJson(res, 200, { ...readSettings(dir), writable: flags.write });
539
638
  return;
540
639
  }
541
- if (req.url === '/settings/config' || req.url === '/settings/policy') {
542
- 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);
543
642
  if (req.method !== 'POST') {
544
643
  sendJson(res, 405, { ok: false, error: 'this route takes POST' });
545
644
  return;
@@ -550,6 +649,10 @@ function main() {
550
649
  // that and editing the autonomy policy through it is the difference
551
650
  // this flag exists to make. The refusal names the flag, because a
552
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.
553
656
  if (!flags.write) {
554
657
  sendJson(res, 403, {
555
658
  ok: false,
@@ -562,7 +665,7 @@ function main() {
562
665
  return;
563
666
  }
564
667
  readJsonBody(req)
565
- .then((body) => sendJson(res, 200, handleSettingsWrite(dir, route, body)))
668
+ .then((body) => sendJson(res, 200, route === 'answer' ? handleAnswer(dir, body) : handleSettingsWrite(dir, route, body)))
566
669
  .catch((err) => {
567
670
  const known = err instanceof SettingsError;
568
671
  if (!known) console.error(`board: settings write failed: ${String(err?.message ?? err)}`);
@@ -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
  }
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.