@jjanczur/tyran 0.1.30 → 0.1.32

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.
@@ -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,
@@ -53,14 +62,22 @@ import {
53
62
  STATE_FILE,
54
63
  } from './project.mjs';
55
64
  import { classifyPath, normalizePath, validateFile, knowledgeWarnings, MANDATORY_KERNEL_PATHS } from './schema.mjs';
65
+ import { auditEntries, loadEntries as loadKnowledgeEntries } from './knowledge.mjs';
66
+ import { readPlatformUsage } from './usage-source.mjs';
56
67
  import { gitRunner } from './scan-repo.mjs';
57
68
  import { parseMistakes, countSignatures, fenceState, KNOWLEDGE_THRESHOLD, MISTAKES_FILE, CLAUDE_MD_FILE } from './mistakes.mjs';
58
69
 
59
70
  /** Severity order is also the report order. `info` never fails the check. */
60
71
  export const SEVERITIES = Object.freeze(['error', 'warning', 'info']);
61
72
 
62
- /** Default: an agent open this long without the journal moving on is stuck. */
63
- export const DEFAULT_STALE_HOURS = 4;
73
+ /**
74
+ * Default: an agent open this long without the journal moving on is stuck.
75
+ *
76
+ * Re-exported, not redefined. The threshold and the comparison both live in
77
+ * `journal.mjs` so the board renders doctor's answer instead of computing a
78
+ * second one — `--stale-hours` still moves it for this report alone.
79
+ */
80
+ export { DEFAULT_STALE_HOURS };
64
81
 
65
82
  const JOURNAL_FILE = 'journal.jsonl';
66
83
 
@@ -171,6 +188,8 @@ export const SEVERITY_BY_CODE = Object.freeze(
171
188
  'lease-orphan': 'warning',
172
189
  'lease-expired': 'warning',
173
190
  'lease-release-by-non-holder': 'warning',
191
+ // worktrees
192
+ 'worktree-accumulating': 'warning',
174
193
  // projections
175
194
  'projection-drift': 'warning',
176
195
  'projection-absent': 'info',
@@ -187,6 +206,11 @@ export const SEVERITY_BY_CODE = Object.freeze(
187
206
  'knowledge-unreadable': 'error',
188
207
  'knowledge-not-a-directory': 'warning',
189
208
  'knowledge-entry-oversized': 'warning',
209
+ // The AGGREGATE of the line above. `info`, not `warning`: nothing is
210
+ // broken and a store outgrows the budget in the ordinary course of being
211
+ // useful — but "1 of 31 entries reaches a brief" is the number that gets
212
+ // acted on, and five per-entry notes never added up to it for anyone.
213
+ 'knowledge-store-unreachable': 'info',
190
214
  // Not `info`, which is what it was: with `.tyran/` on disk and no policy
191
215
  // under it the gate refuses every write in the repository. A severity that
192
216
  // does not fail the check reports a locked-out repo as a note.
@@ -222,6 +246,16 @@ export const SEVERITY_BY_CODE = Object.freeze(
222
246
  // red during normal operation is a check people learn to skip.
223
247
  'mistakes-unreadable': 'warning',
224
248
  'mistakes-repeat-unpromoted': 'info',
249
+ // `info`, and it fires only where git proves the file NEVER existed —
250
+ // a deletion is the documented opt-out and stays silent. See
251
+ // `absentMistakes` for why the two need telling apart at all.
252
+ 'mistakes-file-missing': 'info',
253
+ // Data keys nothing reads. The near miss is a WARNING because it is silent
254
+ // data loss and a healthy journal has none; the plain count is `info`
255
+ // because extra keys are what the envelope promises, and a warning per
256
+ // improvised key would be red on every healthy repo.
257
+ 'journal-key-near-miss': 'warning',
258
+ 'journal-key-unread': 'info',
225
259
  'claude-md-fence-missing': 'info',
226
260
  // overnight mode
227
261
  'limit-pause-active': 'info',
@@ -300,12 +334,8 @@ function isDirectory(path) {
300
334
  }
301
335
  }
302
336
 
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
- }
337
+ // `hoursBetween` is imported from journal.mjs, next to the staleness rule it
338
+ // serves — see the note on `spawnStaleness` for why that rule cannot live here.
309
339
 
310
340
  // -------------------------------------------------------- policy analysis
311
341
 
@@ -521,6 +551,7 @@ function checkInitiative(stateDir, name, { now, staleHours }) {
521
551
  }
522
552
  };
523
553
  guard('journal integrity', () => journalIntegrity(journalPath, at, read));
554
+ guard('data keys nothing reads', () => unreadKeyFindings(at, events));
524
555
  guard('one initiative per file', () => initiativeScope(journalPath, at, name, events));
525
556
  guard('open spawns', () => spawnFindings(journalPath, at, name, events, reference, staleHours));
526
557
  guard('operator asks', () => askFindings(journalPath, at, read, reference));
@@ -702,6 +733,100 @@ function closeSpawnHint(journalPath, init, agent) {
702
733
  : `node scripts/journal.mjs close-spawn ${sq(journalPath)} ${sq(slug)} ${sq(agent)} --reason "<why>"`;
703
734
  }
704
735
 
736
+ /**
737
+ * Is the knowledge store actually READABLE, as a whole?
738
+ *
739
+ * Every failure returns [] rather than throwing: this is advisory, it runs
740
+ * after the checks that decide whether the repo works at all, and a store
741
+ * that cannot be listed is already reported by `yamlFilesIn` above.
742
+ */
743
+ function knowledgeReachability(knowledgeDir) {
744
+ let entries;
745
+ try {
746
+ if (!isDirectory(knowledgeDir)) return [];
747
+ ({ entries } = loadKnowledgeEntries(knowledgeDir));
748
+ } catch {
749
+ return [];
750
+ }
751
+ if (!Array.isArray(entries) || entries.length === 0) return [];
752
+ const report = auditEntries(entries);
753
+ // Silent while the store still fits: pressure that is being obeyed is not a
754
+ // finding, and a check that is red on every healthy repo is one people skip.
755
+ if (report.unreachable === 0) return [];
756
+ const stuck = report.aloneTooBig;
757
+ const detail =
758
+ stuck.length === 0
759
+ ? ''
760
+ : ` ${stuck.length} of them cannot appear in ANY brief even alone (widest: ` +
761
+ `${show(stuck[0].id)} at ${stuck[0].cost}), so no budget a caller passes will reach them.`;
762
+ return [
763
+ finding(
764
+ 'knowledge-store-unreachable',
765
+ show(knowledgeDir),
766
+ `${report.reachable} of ${report.entries} knowledge entries can reach one brief at the ` +
767
+ `${report.budget}-codepoint budget; ${report.unreachable} cannot.${detail} The store is written ` +
768
+ 'by every retrospective and read through that budget, so what does not fit is not merely ' +
769
+ 'crowded — it reaches nobody',
770
+ `node scripts/knowledge.mjs audit --dir ${sq(knowledgeDir)} # the full list, widest first`,
771
+ ),
772
+ ];
773
+ }
774
+
775
+ /** How many unread keys are named before the rest are counted instead. */
776
+ const MAX_NAMED_KEYS = 12;
777
+
778
+ /**
779
+ * Data keys nothing reads — the end of accept-then-ignore, minus the nagging.
780
+ *
781
+ * `append` accepts any key by design, and it must: `data may always carry
782
+ * extra keys` is the envelope's promise, the evidence gate writes four of its
783
+ * own, and turning it into a rule would fail every journal ever written. So
784
+ * this is a REPORT, never a refusal, and it splits into two sentences because
785
+ * the two situations are not the same failure.
786
+ *
787
+ * A NEAR MISS is the defect: `next_step` for `next_steps` is accepted,
788
+ * ignored, and leaves the resume surface empty while the agent that wrote it
789
+ * believes it recorded something. That is worth a warning each, because it is
790
+ * silent data loss and a healthy journal has none.
791
+ *
792
+ * Everything else is the contract working. Measured on one real install: 130
793
+ * distinct (event, key) pairs across 39 initiatives, nearly all of it
794
+ * deliberate annotation. Those are COUNTED — never dropped, ADR-19 correction
795
+ * 1 — at `info`, in one line, because a warning per improvised key would go
796
+ * red on every healthy repo and a check that is red during normal operation is
797
+ * a check people learn to skip.
798
+ */
799
+ function unreadKeyFindings(at, events) {
800
+ const { unread, nearMisses } = unreadDataKeys(events);
801
+ const findings = nearMisses.map((m) =>
802
+ finding(
803
+ 'journal-key-near-miss',
804
+ at,
805
+ `${m.count} ${show(m.ev)} event(s) carry \`${show(m.key)}\`, one edit from \`${show(m.meant)}\`, which is ` +
806
+ 'the key consumers actually read. A misspelled key is accepted, never read, and never reported — ' +
807
+ 'the writer believes it recorded something and nothing did',
808
+ `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`,
809
+ ),
810
+ );
811
+ // Named minus the near-misses: those already have a finding of their own,
812
+ // and listing them twice would read as twice as many problems.
813
+ const rest = [...unread.keys()].filter((id) => !nearMisses.some((m) => `${m.ev}.${m.key}` === id)).sort();
814
+ if (rest.length > 0) {
815
+ const shown = rest.slice(0, MAX_NAMED_KEYS).map((id) => `${id} x${unread.get(id)}`).join(', ');
816
+ findings.push(
817
+ finding(
818
+ 'journal-key-unread',
819
+ at,
820
+ `${rest.length} data key(s) that no consumer reads: ${show(shown)}` +
821
+ (rest.length > MAX_NAMED_KEYS ? ` (+${rest.length - MAX_NAMED_KEYS} more)` : '') +
822
+ '. Extra keys are legal and this is not a defect — it is what the envelope promises. Stated so ' +
823
+ 'that "recorded" and "recorded AND read" stay distinguishable',
824
+ ),
825
+ );
826
+ }
827
+ return findings;
828
+ }
829
+
705
830
  /** How long a self-reported `blocked` may stand before it is a finding. */
706
831
  export const DEFAULT_BLOCKED_HOURS = 1;
707
832
 
@@ -722,7 +847,10 @@ function spawnFindings(journalPath, at, dirName, events, reference, staleHours)
722
847
  const signals = lastSignals(events);
723
848
  for (const agent of sortedNames(open.keys())) {
724
849
  for (const spawn of open.get(agent)) {
725
- const age = reference === null ? null : hoursBetween(spawn.ts, reference);
850
+ // The shared rule, not a local one: the board reads the same predicate,
851
+ // so an agent doctor calls abandoned can never still read `running`
852
+ // there. `--stale-hours` moves the threshold for this report alone.
853
+ const { ageHours: age, stale } = spawnStaleness(spawn.ts, reference, staleHours);
726
854
  const where = `${show(spawn.data.ticket ?? 'no ticket')}, role ${show(spawn.data.role)}`;
727
855
  // `lastSignals` is keyed by agent NAME, and ADR-18 permits a name to be
728
856
  // re-spawned once its previous spawn is closed — so the latest signal
@@ -745,7 +873,7 @@ function spawnFindings(journalPath, at, dirName, events, reference, staleHours)
745
873
  closeSpawnHint(journalPath, spawn.init ?? dirName, agent),
746
874
  ),
747
875
  );
748
- } else if (age !== null && age >= staleHours) {
876
+ } else if (stale) {
749
877
  findings.push(
750
878
  finding(
751
879
  'spawn-stale',
@@ -819,7 +947,17 @@ function askFindings(journalPath, at, read, reference) {
819
947
  return findings;
820
948
  }
821
949
 
822
- const EXPIRY_KEYS = Object.freeze(['expires', 'expires_at', 'until']);
950
+ /**
951
+ * Every spelling an agent has actually used for a lease's expiry.
952
+ *
953
+ * `expiry` leads because it is what agents overwhelmingly write: measured
954
+ * across every journal on a real machine, 33 `expiry` against 3 `expires`, so
955
+ * this finding read 3 of 36 recorded expiries and `lease-expired` was
956
+ * effectively dead. A denylist of spellings is a poor mechanism, but the
957
+ * alternative — refusing the ones agents naturally reach for — trades a quiet
958
+ * miss for a loud one over a field that is advisory anyway.
959
+ */
960
+ const EXPIRY_KEYS = Object.freeze(['expiry', 'expires', 'expires_at', 'until']);
823
961
 
824
962
  function leaseFindings(journalPath, at, events, reference) {
825
963
  const findings = [];
@@ -1289,9 +1427,114 @@ export function trackedLeaseFiles(run, tyranDirName = '.tyran') {
1289
1427
  * owned by `mistakes.mjs`, the same discipline doctor already follows for
1290
1428
  * `validateKnowledge` and `pairSpawns` (ADR-18).
1291
1429
  */
1292
- export function mistakesFindings(repoRoot) {
1430
+
1431
+ /**
1432
+ * Absence, split into the two situations that look identical on disk.
1433
+ *
1434
+ * Deleting the file is the documented opt-out and it stays silent — a tool
1435
+ * that nags about a file you deliberately removed is a tool you disable, and
1436
+ * that argument has not changed. But an install created before this ledger
1437
+ * existed never made that choice: there is nothing to opt out of, nobody was
1438
+ * ever offered the file, and silence there is not respect for a decision, it
1439
+ * is a feature the operator has never heard of.
1440
+ *
1441
+ * Git is the only witness that can tell the two apart. A file with history is
1442
+ * one somebody had and removed; a file with no history in a repo git can read
1443
+ * never existed. When git cannot answer at all — no repository, no git on the
1444
+ * PATH — this says NOTHING, because a guess here would nag exactly the
1445
+ * operator who already opted out.
1446
+ *
1447
+ * `info`, never a warning: nothing is broken, and the check exists to make an
1448
+ * offer rather than to report a defect.
1449
+ */
1450
+ function absentMistakes(repoRoot, path, run) {
1451
+ const checked = `${MISTAKES_FILE}: absent`;
1452
+ if (run === null) return { findings: [], checked };
1453
+ // The same probe `untrackedTyranDir` uses, for the same reason: `run`
1454
+ // returns '' for "git said nothing" and for "git is not here", and those
1455
+ // need opposite conclusions.
1456
+ if (run(['rev-parse', '--is-inside-work-tree']).trim() !== 'true') {
1457
+ return { findings: [], checked: `${checked} (no git here to say whether it ever existed)` };
1458
+ }
1459
+ const history = run(['log', '--max-count=1', '--format=%H', '--', MISTAKES_FILE]).trim();
1460
+ if (history !== '') {
1461
+ return { findings: [], checked: `${checked} — deleted deliberately, which IS the opt-out` };
1462
+ }
1463
+ return {
1464
+ findings: [
1465
+ finding(
1466
+ 'mistakes-file-missing',
1467
+ show(path),
1468
+ `no ${MISTAKES_FILE}, and git has never seen one — this repository predates the incident ledger ` +
1469
+ 'rather than having opted out of it. Nothing is broken; the ledger is what turns a mistake that ' +
1470
+ 'happened three times into a rule that stops the fourth',
1471
+ `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`,
1472
+ ),
1473
+ ],
1474
+ checked: `${checked} — never existed`,
1475
+ };
1476
+ }
1477
+ /**
1478
+ * How many git worktrees this repository is carrying, and whether that has
1479
+ * become a problem nobody is looking at.
1480
+ *
1481
+ * Tyran's parallel model is a worktree per agent, and NOTHING removes one.
1482
+ * There is no removal path in any skill, agent or script; the journal has no
1483
+ * event that can even represent a worktree being destroyed; and doctor has
1484
+ * never enumerated them. Measured on one real machine: 26 in one repository,
1485
+ * 33 GB under another's `.worktrees/`, the oldest active for 68 days.
1486
+ *
1487
+ * REPORTS, never removes — and that restraint is the finding's whole design,
1488
+ * not doctor's general rule applied by rote. Most of those worktrees turned
1489
+ * out to hold work that never CONCLUDED rather than work that finished, so a
1490
+ * tool deleting "merged" ones would clear almost nothing while being able, on
1491
+ * a bad day, to delete something someone wanted. The operator gets the count,
1492
+ * the ages, and a command they can read before running.
1493
+ *
1494
+ * The threshold is deliberately generous: a handful of worktrees is the system
1495
+ * working as designed. This fires when they have stopped being cleaned up at
1496
+ * all, which is what the measured installs look like.
1497
+ */
1498
+ export const WORKTREE_CEILING = 8;
1499
+
1500
+ export function worktreeFindings(repoRoot, run = null) {
1501
+ const checked = 'git worktrees';
1502
+ if (run === null) return { findings: [], checked: `${checked}: not checked (no git runner)` };
1503
+ if (run(['rev-parse', '--is-inside-work-tree']).trim() !== 'true') {
1504
+ return { findings: [], checked: `${checked}: no git here` };
1505
+ }
1506
+ const listing = run(['worktree', 'list', '--porcelain']);
1507
+ if (listing.trim() === '') return { findings: [], checked: `${checked}: none reported` };
1508
+ // One record per blank-line-separated block; the main checkout is one of
1509
+ // them and is never a leak, so it is counted and then subtracted.
1510
+ const blocks = listing.split(/\n\s*\n/).filter((b) => b.trim() !== '');
1511
+ const extra = Math.max(0, blocks.length - 1);
1512
+ const prunable = blocks.filter((b) => /^prunable /m.test(b)).length;
1513
+ if (extra <= WORKTREE_CEILING) {
1514
+ return { findings: [], checked: `${checked}: ${extra} beside the main checkout` };
1515
+ }
1516
+ return {
1517
+ findings: [
1518
+ finding(
1519
+ 'worktree-accumulating',
1520
+ show(repoRoot),
1521
+ `${extra} git worktrees beside the main checkout` +
1522
+ (prunable > 0 ? `, ${prunable} of them already prunable` : '') +
1523
+ ' — Tyran creates one per parallel agent and removes none, so they accumulate silently. ' +
1524
+ 'They cost disk, and a stale one has already cost a validation baseline: a lint run swept ' +
1525
+ 'leftover worktrees and reported 32,243 phantom errors. Nothing here is deleted for you; ' +
1526
+ 'read the list before removing anything, because an unmerged worktree may hold work that ' +
1527
+ 'was never finished rather than work that was',
1528
+ `git -C ${sq(repoRoot)} worktree list # then: git worktree remove <path>, after checking git -C <path> status`,
1529
+ ),
1530
+ ],
1531
+ checked: `${checked}: ${extra} beside the main checkout`,
1532
+ };
1533
+ }
1534
+
1535
+ export function mistakesFindings(repoRoot, run = null) {
1293
1536
  const path = join(repoRoot, MISTAKES_FILE);
1294
- if (!existsSync(path)) return { findings: [], checked: `${MISTAKES_FILE}: absent` };
1537
+ if (!existsSync(path)) return absentMistakes(repoRoot, path, run);
1295
1538
 
1296
1539
  let parsed;
1297
1540
  try {
@@ -1397,7 +1640,7 @@ export const ASK_QUEUE_FILES = Object.freeze(['ANSWERS.md', 'conductor.json']);
1397
1640
  * one); without it a marker is reported as present, never as stale — doctor
1398
1641
  * never reads the wall clock.
1399
1642
  */
1400
- export function overnightFindings(dir, { now = null, configDoc = null } = {}) {
1643
+ export function overnightFindings(dir, { now = null, configDoc = null, usageFallback = () => readPlatformUsage() } = {}) {
1401
1644
  const findings = [];
1402
1645
  const referenceMs = now !== null ? Date.parse(now) : null;
1403
1646
  const markerPath = join(dir, 'state', 'paused-until.json');
@@ -1457,20 +1700,31 @@ export function overnightFindings(dir, { now = null, configDoc = null } = {}) {
1457
1700
  }
1458
1701
 
1459
1702
  // A configured control that cannot see is the silent-absence class.
1703
+ //
1704
+ // The sidecar is no longer the only channel: the gate falls back to the
1705
+ // platform's own usage cache in `~/.claude.json`, which is why this finding
1706
+ // now asks whether ANY telemetry is reachable rather than whether the
1707
+ // statusline was installed. It used to fire on every install that had not
1708
+ // pasted a statusLine command — which, since the statusline was the only
1709
+ // writer and its payload is not always populated, was most of them, while
1710
+ // the real fault was usually that the platform was sending nothing.
1460
1711
  const limits = knowsLimits(configDoc);
1461
1712
  if (limits !== null && limits.mode !== 'off') {
1462
1713
  const sidecar = readJsonIfSmall(sidecarPath);
1463
1714
  const writtenMs = sidecar !== null ? Date.parse(typeof sidecar.written_at === 'string' ? sidecar.written_at : '') : NaN;
1464
1715
  const ancient = referenceMs !== null && Number.isFinite(writtenMs) && referenceMs - writtenMs > 24 * 3600 * 1000;
1465
- if (sidecar === null || ancient) {
1716
+ const platform = usageFallback();
1717
+ if ((sidecar === null || ancient) && platform === null) {
1466
1718
  findings.push(
1467
1719
  finding(
1468
1720
  'limit-telemetry-missing',
1469
1721
  show(sidecarPath),
1470
- `limits.mode is "${show(limits.mode)}" but the usage telemetry sidecar is ${sidecar === null ? 'absent' : 'over a day old'} — ` +
1471
- 'the gate fails open without it, so the configured pause protects nothing. The statusline ' +
1472
- 'helper is operator-installed; see https://jjanczur.github.io/tyran/overnight/',
1473
- `node scripts/statusline.mjs --sidecar-only # wired into the user-settings statusLine command`,
1722
+ `limits.mode is "${show(limits.mode)}" and NO usage telemetry is reachable — the sidecar is ` +
1723
+ `${sidecar === null ? 'absent' : 'over a day old'} and the platform's own cache in ~/.claude.json ` +
1724
+ 'carries no window that is still running. The gate fails open without one, so the configured ' +
1725
+ 'pause protects nothing. Usually this means the account is signed out, or the platform has not ' +
1726
+ 'reported usage yet; see https://jjanczur.github.io/tyran/overnight/',
1727
+ `node scripts/statusline.mjs --sidecar-only # optional: a statusline is fresher, but no longer required`,
1474
1728
  ),
1475
1729
  );
1476
1730
  }
@@ -1505,7 +1759,13 @@ function knowsLimits(configDoc) {
1505
1759
  return typeof limits.mode === 'string' ? limits : null;
1506
1760
  }
1507
1761
 
1508
- export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAULT_STALE_HOURS, run = null } = {}) {
1762
+ export function runStateChecks({
1763
+ dir = '.tyran',
1764
+ now = null,
1765
+ staleHours = DEFAULT_STALE_HOURS,
1766
+ run = null,
1767
+ usageFallback = () => readPlatformUsage(),
1768
+ } = {}) {
1509
1769
  const root = resolve(dir);
1510
1770
  if (!existsSync(root)) {
1511
1771
  return summarize(dir, [finding('no-state-dir', show(dir), 'no Tyran state directory here — nothing to check')], [
@@ -1572,6 +1832,15 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1572
1832
  }
1573
1833
  }
1574
1834
  checked.push(`knowledge/: ${knowledge.files.length} file(s)`);
1835
+ // The AGGREGATE, which the per-entry warning above cannot show.
1836
+ //
1837
+ // `knowledge-entry-oversized` fires once per fat entry and each one reads as
1838
+ // a small, local untidiness. Measured on a real install it fired five times
1839
+ // while the true state was that `brief` returned ONE of thirty-one entries:
1840
+ // 104,178 codepoints of hard-won detail, reaching nobody. Five tidy-up notes
1841
+ // and "your knowledge store is 97% unread" are not the same message, and
1842
+ // only the second one gets acted on.
1843
+ findings.push(...knowledgeReachability(join(dir, 'knowledge')));
1575
1844
 
1576
1845
  const policies = yamlFilesIn(join(dir, 'policies'), 'policies');
1577
1846
  findings.push(...policies.findings);
@@ -1656,17 +1925,26 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1656
1925
  'legacy layout — initiative files (PLAN.md, NOTES.md, RETRO.md, locks/) live under ' +
1657
1926
  'state/<initiative>/ since 0.1.9. Mechanical consumers read only state/, so anything ' +
1658
1927
  '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/`,
1928
+ // Was "relocate the contents by hand, one initiative directory at a
1929
+ // time" — which is advice, not a remedy, on the one class of install
1930
+ // that by definition nobody has touched since 0.1.8. The script says
1931
+ // what it WOULD move until asked twice, never overwrites, and never
1932
+ // deletes anything it did not empty.
1933
+ `node scripts/migrate.mjs --dir ${sq(dir)} # what it would move; add --apply to move it`,
1660
1934
  ),
1661
1935
  );
1662
1936
  }
1663
1937
  checked.push(`initiatives/ (legacy): ${isDirectory(legacyDir) ? 'PRESENT' : 'absent'}`);
1664
1938
 
1665
- const mistakes = mistakesFindings(repoRoot);
1939
+ const mistakes = mistakesFindings(repoRoot, gitRun);
1666
1940
  findings.push(...mistakes.findings);
1667
1941
  checked.push(mistakes.checked);
1668
1942
 
1669
- findings.push(...overnightFindings(dir, { now, configDoc }));
1943
+ const worktrees = worktreeFindings(repoRoot, gitRun);
1944
+ findings.push(...worktrees.findings);
1945
+ checked.push(worktrees.checked);
1946
+
1947
+ findings.push(...overnightFindings(dir, { now, configDoc, usageFallback }));
1670
1948
  checked.push('overnight: checked');
1671
1949
 
1672
1950
  const trackedLeases = trackedLeaseFiles(gitRun, basename(root));