@jjanczur/tyran 0.1.29 → 0.1.31

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.
package/scripts/cost.mjs CHANGED
@@ -35,6 +35,7 @@
35
35
  *
36
36
  * CLI:
37
37
  * node cost.mjs [--dir <.tyran>] [--session <id>] [--json] [--projects <dir>]
38
+ * [--transcripts <dir>]...
38
39
  * Exit: 0 ok · 2 usage/IO
39
40
  */
40
41
  import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
@@ -345,6 +346,64 @@ function findTranscriptDir(want, projectsRoot) {
345
346
  return null;
346
347
  }
347
348
 
349
+ /**
350
+ * Where BOTH `transcriptDirFor` heuristics fail: a conductor session started
351
+ * from a working directory OTHER than the repo it operates on — Claude Code
352
+ * Desktop opened in a sibling folder, working the repo through absolute paths
353
+ * and worktrees. The computed slug does not match (it is derived from the
354
+ * conductor's own cwd, not the repo path), and the cwd probe does not match
355
+ * either (every record in that transcript carries the CONDUCTOR's cwd, never
356
+ * the repo's). Measured: a `claude` run once started inside the repo for the
357
+ * trust dialog left a directory the direct lookup matched and stopped at,
358
+ * while ~66 agent transcripts and 2 300 requests sat under the conductor's
359
+ * real project dir with nothing on the board pointing at them.
360
+ *
361
+ * A leading `~` expanded to the home directory — the same narrow rule
362
+ * `main_writable_paths` uses in `config.yaml`, so a transcript dir is written
363
+ * the way an operator already writes every other out-of-repo path in this
364
+ * file.
365
+ */
366
+ function expandHome(p) {
367
+ if (p === '~') return homedir();
368
+ if (p.startsWith('~/')) return join(homedir(), p.slice(2));
369
+ return p;
370
+ }
371
+
372
+ /**
373
+ * The parsed `.tyran/config.yaml`, or null when it is absent or will not
374
+ * parse. Shared by every config-driven reader below (pricing, the transcript
375
+ * override) so there is one place that opens and parses the file, not two
376
+ * loaders that quietly drift apart.
377
+ */
378
+ function loadConfigDoc(tyranDir) {
379
+ try {
380
+ return parse(readFileSync(join(tyranDir, 'config.yaml'), 'utf8'));
381
+ } catch {
382
+ return null;
383
+ }
384
+ }
385
+
386
+ /**
387
+ * `spend.transcript_dirs` out of an ALREADY-PARSED config doc — the middle
388
+ * tier of the transcript-dir precedence (CLI `--transcripts` > this > the
389
+ * derived-slug / cwd-probe fallback above). Operator-written, never
390
+ * scanner-inferred, exactly like `pricing:` and `limits:`: a doc that carries
391
+ * nothing here simply falls through to the fallback, same as an absent block.
392
+ *
393
+ * Takes the parsed doc rather than `tyranDir` so `costReport` can read
394
+ * `config.yaml` once and hand the same doc to this and to `pricingOf` —
395
+ * two readers opening and parsing the same file on every call was the
396
+ * reviewed nit this signature exists to close.
397
+ */
398
+ function spendTranscriptDirsOf(doc) {
399
+ const spend = doc !== null && typeof doc === 'object' ? doc.spend : undefined;
400
+ const list =
401
+ spend !== null && typeof spend === 'object' && Array.isArray(spend.transcript_dirs)
402
+ ? spend.transcript_dirs
403
+ : [];
404
+ return list.filter((d) => typeof d === 'string' && d.trim() !== '');
405
+ }
406
+
348
407
  /** Every transcript belonging to this repo: the sessions and their agents. */
349
408
  export function listSources(transcriptDir, sessionFilter) {
350
409
  const out = [];
@@ -644,6 +703,10 @@ export function renderReport(report) {
644
703
  if (report.unpriced.length > 0) {
645
704
  out.push(`Unpriced models (counted in tokens, absent from every amount): ${report.unpriced.join(', ')}`);
646
705
  }
706
+ if ((report.transcript_dirs_missing ?? []).length > 0) {
707
+ const noun = report.transcript_dirs_missing.length === 1 ? 'directory' : 'directories';
708
+ out.push(`Given transcript ${noun} not found: ${report.transcript_dirs_missing.join(', ')}`);
709
+ }
647
710
  return out.join('\n') + '\n';
648
711
  }
649
712
 
@@ -654,14 +717,16 @@ export function costJson(report) {
654
717
 
655
718
  /* ---------------------------------- CLI ---------------------------------- */
656
719
 
657
- function loadPricing(tyranDir) {
658
- try {
659
- return pricingOf(parse(readFileSync(join(tyranDir, 'config.yaml'), 'utf8')));
660
- } catch {
661
- // A config that will not parse is doctor's problem to report, not this
662
- // reader's problem to refuse over: tokens are still worth counting.
663
- return { rate_card: null, models: Object.create(null) };
664
- }
720
+ /**
721
+ * The rate card out of an ALREADY-PARSED config doc — see `spendTranscriptDirsOf`
722
+ * for why this takes a doc instead of `tyranDir` and reading the file itself.
723
+ * A config that will not parse is doctor's problem to report, not this
724
+ * reader's problem to refuse over: tokens are still worth counting.
725
+ * `pricingOf(null)` already reads as "no pricing block" (see schema.mjs), so
726
+ * an absent/unparseable doc needs no separate branch here.
727
+ */
728
+ function pricingOfDoc(doc) {
729
+ return pricingOf(doc ?? {});
665
730
  }
666
731
 
667
732
  function readCache(path) {
@@ -683,20 +748,21 @@ function writeAtomic(path, text) {
683
748
  renameSync(tmp, path);
684
749
  }
685
750
 
686
- /** Build the report for a repo. Exported so the board server reuses it. */
687
- export function costReport({ tyranDir, projectsRoot, session = null, repoRoot = null } = {}) {
688
- const root = repoRoot ?? resolve(tyranDir, '..');
689
- const dir = transcriptDirFor(root, projectsRoot ?? join(homedir(), '.claude', 'projects'));
690
- const pricing = loadPricing(tyranDir);
691
- if (dir === null) {
692
- const empty = rollup([], pricing, {});
693
- empty.transcripts_found = false;
694
- return empty;
695
- }
751
+ /**
752
+ * The scan-and-persist tail shared by every path through `costReport`: fold
753
+ * `sources` against the on-disk cache, roll it up, attach the fields callers
754
+ * read straight off the report, and write the sidecar. One function so the
755
+ * caching contract — persisted here, not only in the `--json` branch, so the
756
+ * served board benefits too — cannot drift between the derived-dir path and
757
+ * the explicit-dirs path below.
758
+ */
759
+ function finishReport({ sources, pricing, tyranDir, session, transcriptDirsUsed, transcriptDirsMissing }) {
696
760
  const cachePath = join(tyranDir, 'state', COST_FILE);
697
- const { scanned, unreadable, reused } = scanAll(listSources(dir, session), readCache(cachePath));
761
+ const { scanned, unreadable, reused } = scanAll(sources, readCache(cachePath));
698
762
  const report = rollup(scanned, pricing, { unreadable, reused });
699
763
  report.transcripts_found = true;
764
+ report.transcript_dirs = transcriptDirsUsed;
765
+ report.transcript_dirs_missing = transcriptDirsMissing;
700
766
  report.session = session;
701
767
  report.sources = scanned.map((s) => ({
702
768
  path: s.path,
@@ -738,12 +804,90 @@ export function costReport({ tyranDir, projectsRoot, session = null, repoRoot =
738
804
  return report;
739
805
  }
740
806
 
807
+ /**
808
+ * Build the report for a repo. Exported so the board server reuses it.
809
+ *
810
+ * `transcriptDirs` is the explicit override — the fix for a conductor that
811
+ * ran from a working directory other than the repo it operates on (see the
812
+ * comment above `expandHome`). Precedence, highest first: the `transcriptDirs`
813
+ * this caller passed in (the CLI's repeatable `--transcripts`) · `.tyran/
814
+ * config.yaml`'s `spend.transcript_dirs` · the derived-slug / cwd-probe
815
+ * fallback `transcriptDirFor` already does. Reading the config tier HERE
816
+ * rather than in every caller is what lets `board.mjs --serve` honour
817
+ * `spend:` with no `--transcripts` flag at all — one precedence order, read
818
+ * once, for both the CLI and the served page.
819
+ *
820
+ * A dir that does not exist is never silently dropped: it is reported in
821
+ * `transcript_dirs_missing` on the returned report, and if EVERY given dir is
822
+ * missing the report reads exactly like "no transcripts found" — gaps are
823
+ * reported, never zeroed (property 3 above).
824
+ */
825
+ export function costReport({ tyranDir, projectsRoot, session = null, repoRoot = null, transcriptDirs = [] } = {}) {
826
+ const root = repoRoot ?? resolve(tyranDir, '..');
827
+ // Read ONCE and handed to both readers below: `pricingOfDoc` and
828
+ // `spendTranscriptDirsOf` used to each open and parse config.yaml
829
+ // themselves, which meant every `costReport` call — including the ones
830
+ // `board.mjs --serve` makes per request — read the same file twice.
831
+ const configDoc = loadConfigDoc(tyranDir);
832
+ const pricing = pricingOfDoc(configDoc);
833
+
834
+ const given = transcriptDirs.length > 0 ? transcriptDirs : spendTranscriptDirsOf(configDoc);
835
+ // De-duplicated: two spellings of the same directory (a repeated flag, or a
836
+ // flag that repeats what the config already says) must not double-count
837
+ // every transcript under it.
838
+ const explicit = [...new Set(given.map((d) => resolve(expandHome(d))))];
839
+
840
+ if (explicit.length > 0) {
841
+ const present = explicit.filter((d) => existsSync(d));
842
+ const missing = explicit.filter((d) => !existsSync(d));
843
+ if (present.length === 0) {
844
+ const empty = rollup([], pricing, {});
845
+ empty.transcripts_found = false;
846
+ empty.transcript_dirs = [];
847
+ empty.transcript_dirs_missing = missing;
848
+ return empty;
849
+ }
850
+ const sources = present.flatMap((dir) => listSources(dir, session));
851
+ return finishReport({
852
+ sources,
853
+ pricing,
854
+ tyranDir,
855
+ session,
856
+ transcriptDirsUsed: present,
857
+ transcriptDirsMissing: missing,
858
+ });
859
+ }
860
+
861
+ const dir = transcriptDirFor(root, projectsRoot ?? join(homedir(), '.claude', 'projects'));
862
+ if (dir === null) {
863
+ const empty = rollup([], pricing, {});
864
+ empty.transcripts_found = false;
865
+ empty.transcript_dirs = [];
866
+ empty.transcript_dirs_missing = [];
867
+ return empty;
868
+ }
869
+ return finishReport({
870
+ sources: listSources(dir, session),
871
+ pricing,
872
+ tyranDir,
873
+ session,
874
+ transcriptDirsUsed: [dir],
875
+ transcriptDirsMissing: [],
876
+ });
877
+ }
878
+
741
879
  function parseArgs(argv) {
742
- const flags = { dir: '.tyran', session: null, projects: null, json: false };
880
+ const flags = { dir: '.tyran', session: null, projects: null, json: false, transcripts: [] };
743
881
  for (let i = 0; i < argv.length; i += 1) {
744
882
  const arg = argv[i];
745
883
  if (arg === '--json') flags.json = true;
746
- else if (arg === '--dir' || arg === '--session' || arg === '--projects') {
884
+ else if (arg === '--transcripts') {
885
+ const value = argv[i + 1];
886
+ if (value === undefined || value.startsWith('--')) throw new UsageError(`${arg} needs a value`);
887
+ // Repeatable: sources are the union over every directory given.
888
+ flags.transcripts.push(value);
889
+ i += 1;
890
+ } else if (arg === '--dir' || arg === '--session' || arg === '--projects') {
747
891
  const value = argv[i + 1];
748
892
  if (value === undefined || value.startsWith('--')) throw new UsageError(`${arg} needs a value`);
749
893
  flags[arg.slice(2)] = value;
@@ -759,7 +903,10 @@ function main(argv) {
759
903
  flags = parseArgs(argv);
760
904
  } catch (err) {
761
905
  console.error(String(err.message ?? err));
762
- console.error('usage: cost.mjs [--dir <.tyran>] [--session <id>] [--projects <dir>] [--json]');
906
+ console.error(
907
+ 'usage: cost.mjs [--dir <.tyran>] [--session <id>] [--projects <dir>] ' +
908
+ '[--transcripts <dir>]... [--json]'
909
+ );
763
910
  return 2;
764
911
  }
765
912
  const tyranDir = resolve(flags.dir);
@@ -767,12 +914,27 @@ function main(argv) {
767
914
  console.error(`cost: no such directory: ${tyranDir}`);
768
915
  return 2;
769
916
  }
770
- const report = costReport({ tyranDir, projectsRoot: flags.projects, session: flags.session });
917
+ const report = costReport({
918
+ tyranDir,
919
+ projectsRoot: flags.projects,
920
+ session: flags.session,
921
+ transcriptDirs: flags.transcripts,
922
+ });
771
923
  if (report.transcripts_found === false) {
772
- console.error(
773
- 'cost: no transcripts found for this repo under the Claude Code projects directory.\n' +
774
- 'Spend is read from the transcripts the platform writes; nothing here estimates it.'
775
- );
924
+ // Two different gaps, two different sentences: a `--transcripts` (or
925
+ // `spend.transcript_dirs`) dir that does not exist is an operator typo,
926
+ // not the same "nothing to find" as the derived directory being absent.
927
+ if ((report.transcript_dirs_missing ?? []).length > 0) {
928
+ console.error(
929
+ 'cost: none of the given transcript directories exist:\n' +
930
+ report.transcript_dirs_missing.map((d) => ` - ${d}`).join('\n')
931
+ );
932
+ } else {
933
+ console.error(
934
+ 'cost: no transcripts found for this repo under the Claude Code projects directory.\n' +
935
+ 'Spend is read from the transcripts the platform writes; nothing here estimates it.'
936
+ );
937
+ }
776
938
  return 2;
777
939
  }
778
940
  if (flags.json) {
@@ -39,7 +39,16 @@ import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'n
39
39
  import { join, dirname, resolve, basename } from 'node:path';
40
40
  import { fileURLToPath } from 'node:url';
41
41
  import { checkHooks, DEFAULT_PLUGIN_ROOT } from './hooks-check.mjs';
42
- import { readJournal, validateJournal, pairSpawns, tail } from './journal.mjs';
42
+ import {
43
+ readJournal,
44
+ validateJournal,
45
+ pairSpawns,
46
+ tail,
47
+ hoursBetween,
48
+ spawnStaleness,
49
+ unreadDataKeys,
50
+ DEFAULT_STALE_HOURS,
51
+ } from './journal.mjs';
43
52
  import {
44
53
  boardOf,
45
54
  checkFile,
@@ -59,8 +68,14 @@ import { parseMistakes, countSignatures, fenceState, KNOWLEDGE_THRESHOLD, MISTAK
59
68
  /** Severity order is also the report order. `info` never fails the check. */
60
69
  export const SEVERITIES = Object.freeze(['error', 'warning', 'info']);
61
70
 
62
- /** Default: an agent open this long without the journal moving on is stuck. */
63
- export const DEFAULT_STALE_HOURS = 4;
71
+ /**
72
+ * Default: an agent open this long without the journal moving on is stuck.
73
+ *
74
+ * Re-exported, not redefined. The threshold and the comparison both live in
75
+ * `journal.mjs` so the board renders doctor's answer instead of computing a
76
+ * second one — `--stale-hours` still moves it for this report alone.
77
+ */
78
+ export { DEFAULT_STALE_HOURS };
64
79
 
65
80
  const JOURNAL_FILE = 'journal.jsonl';
66
81
 
@@ -222,6 +237,16 @@ export const SEVERITY_BY_CODE = Object.freeze(
222
237
  // red during normal operation is a check people learn to skip.
223
238
  'mistakes-unreadable': 'warning',
224
239
  'mistakes-repeat-unpromoted': 'info',
240
+ // `info`, and it fires only where git proves the file NEVER existed —
241
+ // a deletion is the documented opt-out and stays silent. See
242
+ // `absentMistakes` for why the two need telling apart at all.
243
+ 'mistakes-file-missing': 'info',
244
+ // Data keys nothing reads. The near miss is a WARNING because it is silent
245
+ // data loss and a healthy journal has none; the plain count is `info`
246
+ // because extra keys are what the envelope promises, and a warning per
247
+ // improvised key would be red on every healthy repo.
248
+ 'journal-key-near-miss': 'warning',
249
+ 'journal-key-unread': 'info',
225
250
  'claude-md-fence-missing': 'info',
226
251
  // overnight mode
227
252
  'limit-pause-active': 'info',
@@ -300,12 +325,8 @@ function isDirectory(path) {
300
325
  }
301
326
  }
302
327
 
303
- function hoursBetween(fromTs, toTs) {
304
- const from = Date.parse(fromTs);
305
- const to = Date.parse(toTs);
306
- if (Number.isNaN(from) || Number.isNaN(to)) return null;
307
- return (to - from) / 3_600_000;
308
- }
328
+ // `hoursBetween` is imported from journal.mjs, next to the staleness rule it
329
+ // serves — see the note on `spawnStaleness` for why that rule cannot live here.
309
330
 
310
331
  // -------------------------------------------------------- policy analysis
311
332
 
@@ -521,6 +542,7 @@ function checkInitiative(stateDir, name, { now, staleHours }) {
521
542
  }
522
543
  };
523
544
  guard('journal integrity', () => journalIntegrity(journalPath, at, read));
545
+ guard('data keys nothing reads', () => unreadKeyFindings(at, events));
524
546
  guard('one initiative per file', () => initiativeScope(journalPath, at, name, events));
525
547
  guard('open spawns', () => spawnFindings(journalPath, at, name, events, reference, staleHours));
526
548
  guard('operator asks', () => askFindings(journalPath, at, read, reference));
@@ -702,6 +724,61 @@ function closeSpawnHint(journalPath, init, agent) {
702
724
  : `node scripts/journal.mjs close-spawn ${sq(journalPath)} ${sq(slug)} ${sq(agent)} --reason "<why>"`;
703
725
  }
704
726
 
727
+ /** How many unread keys are named before the rest are counted instead. */
728
+ const MAX_NAMED_KEYS = 12;
729
+
730
+ /**
731
+ * Data keys nothing reads — the end of accept-then-ignore, minus the nagging.
732
+ *
733
+ * `append` accepts any key by design, and it must: `data may always carry
734
+ * extra keys` is the envelope's promise, the evidence gate writes four of its
735
+ * own, and turning it into a rule would fail every journal ever written. So
736
+ * this is a REPORT, never a refusal, and it splits into two sentences because
737
+ * the two situations are not the same failure.
738
+ *
739
+ * A NEAR MISS is the defect: `next_step` for `next_steps` is accepted,
740
+ * ignored, and leaves the resume surface empty while the agent that wrote it
741
+ * believes it recorded something. That is worth a warning each, because it is
742
+ * silent data loss and a healthy journal has none.
743
+ *
744
+ * Everything else is the contract working. Measured on one real install: 130
745
+ * distinct (event, key) pairs across 39 initiatives, nearly all of it
746
+ * deliberate annotation. Those are COUNTED — never dropped, ADR-19 correction
747
+ * 1 — at `info`, in one line, because a warning per improvised key would go
748
+ * red on every healthy repo and a check that is red during normal operation is
749
+ * a check people learn to skip.
750
+ */
751
+ function unreadKeyFindings(at, events) {
752
+ const { unread, nearMisses } = unreadDataKeys(events);
753
+ const findings = nearMisses.map((m) =>
754
+ finding(
755
+ 'journal-key-near-miss',
756
+ at,
757
+ `${m.count} ${show(m.ev)} event(s) carry \`${show(m.key)}\`, one edit from \`${show(m.meant)}\`, which is ` +
758
+ 'the key consumers actually read. A misspelled key is accepted, never read, and never reported — ' +
759
+ 'the writer believes it recorded something and nothing did',
760
+ `node scripts/journal.mjs query ${sq(at)} --ev ${sq(m.ev)} # then correct the writer; the journal is append-only, so past events keep the typo`,
761
+ ),
762
+ );
763
+ // Named minus the near-misses: those already have a finding of their own,
764
+ // and listing them twice would read as twice as many problems.
765
+ const rest = [...unread.keys()].filter((id) => !nearMisses.some((m) => `${m.ev}.${m.key}` === id)).sort();
766
+ if (rest.length > 0) {
767
+ const shown = rest.slice(0, MAX_NAMED_KEYS).map((id) => `${id} x${unread.get(id)}`).join(', ');
768
+ findings.push(
769
+ finding(
770
+ 'journal-key-unread',
771
+ at,
772
+ `${rest.length} data key(s) that no consumer reads: ${show(shown)}` +
773
+ (rest.length > MAX_NAMED_KEYS ? ` (+${rest.length - MAX_NAMED_KEYS} more)` : '') +
774
+ '. Extra keys are legal and this is not a defect — it is what the envelope promises. Stated so ' +
775
+ 'that "recorded" and "recorded AND read" stay distinguishable',
776
+ ),
777
+ );
778
+ }
779
+ return findings;
780
+ }
781
+
705
782
  /** How long a self-reported `blocked` may stand before it is a finding. */
706
783
  export const DEFAULT_BLOCKED_HOURS = 1;
707
784
 
@@ -722,7 +799,10 @@ function spawnFindings(journalPath, at, dirName, events, reference, staleHours)
722
799
  const signals = lastSignals(events);
723
800
  for (const agent of sortedNames(open.keys())) {
724
801
  for (const spawn of open.get(agent)) {
725
- const age = reference === null ? null : hoursBetween(spawn.ts, reference);
802
+ // The shared rule, not a local one: the board reads the same predicate,
803
+ // so an agent doctor calls abandoned can never still read `running`
804
+ // there. `--stale-hours` moves the threshold for this report alone.
805
+ const { ageHours: age, stale } = spawnStaleness(spawn.ts, reference, staleHours);
726
806
  const where = `${show(spawn.data.ticket ?? 'no ticket')}, role ${show(spawn.data.role)}`;
727
807
  // `lastSignals` is keyed by agent NAME, and ADR-18 permits a name to be
728
808
  // re-spawned once its previous spawn is closed — so the latest signal
@@ -745,7 +825,7 @@ function spawnFindings(journalPath, at, dirName, events, reference, staleHours)
745
825
  closeSpawnHint(journalPath, spawn.init ?? dirName, agent),
746
826
  ),
747
827
  );
748
- } else if (age !== null && age >= staleHours) {
828
+ } else if (stale) {
749
829
  findings.push(
750
830
  finding(
751
831
  'spawn-stale',
@@ -1289,9 +1369,56 @@ export function trackedLeaseFiles(run, tyranDirName = '.tyran') {
1289
1369
  * owned by `mistakes.mjs`, the same discipline doctor already follows for
1290
1370
  * `validateKnowledge` and `pairSpawns` (ADR-18).
1291
1371
  */
1292
- export function mistakesFindings(repoRoot) {
1372
+
1373
+ /**
1374
+ * Absence, split into the two situations that look identical on disk.
1375
+ *
1376
+ * Deleting the file is the documented opt-out and it stays silent — a tool
1377
+ * that nags about a file you deliberately removed is a tool you disable, and
1378
+ * that argument has not changed. But an install created before this ledger
1379
+ * existed never made that choice: there is nothing to opt out of, nobody was
1380
+ * ever offered the file, and silence there is not respect for a decision, it
1381
+ * is a feature the operator has never heard of.
1382
+ *
1383
+ * Git is the only witness that can tell the two apart. A file with history is
1384
+ * one somebody had and removed; a file with no history in a repo git can read
1385
+ * never existed. When git cannot answer at all — no repository, no git on the
1386
+ * PATH — this says NOTHING, because a guess here would nag exactly the
1387
+ * operator who already opted out.
1388
+ *
1389
+ * `info`, never a warning: nothing is broken, and the check exists to make an
1390
+ * offer rather than to report a defect.
1391
+ */
1392
+ function absentMistakes(repoRoot, path, run) {
1393
+ const checked = `${MISTAKES_FILE}: absent`;
1394
+ if (run === null) return { findings: [], checked };
1395
+ // The same probe `untrackedTyranDir` uses, for the same reason: `run`
1396
+ // returns '' for "git said nothing" and for "git is not here", and those
1397
+ // need opposite conclusions.
1398
+ if (run(['rev-parse', '--is-inside-work-tree']).trim() !== 'true') {
1399
+ return { findings: [], checked: `${checked} (no git here to say whether it ever existed)` };
1400
+ }
1401
+ const history = run(['log', '--max-count=1', '--format=%H', '--', MISTAKES_FILE]).trim();
1402
+ if (history !== '') {
1403
+ return { findings: [], checked: `${checked} — deleted deliberately, which IS the opt-out` };
1404
+ }
1405
+ return {
1406
+ findings: [
1407
+ finding(
1408
+ 'mistakes-file-missing',
1409
+ show(path),
1410
+ `no ${MISTAKES_FILE}, and git has never seen one — this repository predates the incident ledger ` +
1411
+ 'rather than having opted out of it. Nothing is broken; the ledger is what turns a mistake that ' +
1412
+ 'happened three times into a rule that stops the fourth',
1413
+ `node scripts/scan-repo.mjs --dir ${sq(repoRoot)} --ensure-policy # seeds it from the shipped template; deleting it again is the opt-out, and this will not put it back on its own`,
1414
+ ),
1415
+ ],
1416
+ checked: `${checked} — never existed`,
1417
+ };
1418
+ }
1419
+ export function mistakesFindings(repoRoot, run = null) {
1293
1420
  const path = join(repoRoot, MISTAKES_FILE);
1294
- if (!existsSync(path)) return { findings: [], checked: `${MISTAKES_FILE}: absent` };
1421
+ if (!existsSync(path)) return absentMistakes(repoRoot, path, run);
1295
1422
 
1296
1423
  let parsed;
1297
1424
  try {
@@ -1656,13 +1783,18 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1656
1783
  'legacy layout — initiative files (PLAN.md, NOTES.md, RETRO.md, locks/) live under ' +
1657
1784
  'state/<initiative>/ since 0.1.9. Mechanical consumers read only state/, so anything ' +
1658
1785
  'kept here is invisible to the projections, the retrospective and the session summary',
1659
- `ls -la ${sq(legacyDir)} # relocate the contents by hand, one initiative directory at a time, into ${sq(join(dir, 'state'))} — see https://jjanczur.github.io/tyran/journal/`,
1786
+ // Was "relocate the contents by hand, one initiative directory at a
1787
+ // time" — which is advice, not a remedy, on the one class of install
1788
+ // that by definition nobody has touched since 0.1.8. The script says
1789
+ // what it WOULD move until asked twice, never overwrites, and never
1790
+ // deletes anything it did not empty.
1791
+ `node scripts/migrate.mjs --dir ${sq(dir)} # what it would move; add --apply to move it`,
1660
1792
  ),
1661
1793
  );
1662
1794
  }
1663
1795
  checked.push(`initiatives/ (legacy): ${isDirectory(legacyDir) ? 'PRESENT' : 'absent'}`);
1664
1796
 
1665
- const mistakes = mistakesFindings(repoRoot);
1797
+ const mistakes = mistakesFindings(repoRoot, gitRun);
1666
1798
  findings.push(...mistakes.findings);
1667
1799
  checked.push(mistakes.checked);
1668
1800