@jjanczur/tyran 0.1.31 → 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.
@@ -62,6 +62,8 @@ import {
62
62
  STATE_FILE,
63
63
  } from './project.mjs';
64
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';
65
67
  import { gitRunner } from './scan-repo.mjs';
66
68
  import { parseMistakes, countSignatures, fenceState, KNOWLEDGE_THRESHOLD, MISTAKES_FILE, CLAUDE_MD_FILE } from './mistakes.mjs';
67
69
 
@@ -186,6 +188,8 @@ export const SEVERITY_BY_CODE = Object.freeze(
186
188
  'lease-orphan': 'warning',
187
189
  'lease-expired': 'warning',
188
190
  'lease-release-by-non-holder': 'warning',
191
+ // worktrees
192
+ 'worktree-accumulating': 'warning',
189
193
  // projections
190
194
  'projection-drift': 'warning',
191
195
  'projection-absent': 'info',
@@ -202,6 +206,11 @@ export const SEVERITY_BY_CODE = Object.freeze(
202
206
  'knowledge-unreadable': 'error',
203
207
  'knowledge-not-a-directory': 'warning',
204
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',
205
214
  // Not `info`, which is what it was: with `.tyran/` on disk and no policy
206
215
  // under it the gate refuses every write in the repository. A severity that
207
216
  // does not fail the check reports a locked-out repo as a note.
@@ -724,6 +733,45 @@ function closeSpawnHint(journalPath, init, agent) {
724
733
  : `node scripts/journal.mjs close-spawn ${sq(journalPath)} ${sq(slug)} ${sq(agent)} --reason "<why>"`;
725
734
  }
726
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
+
727
775
  /** How many unread keys are named before the rest are counted instead. */
728
776
  const MAX_NAMED_KEYS = 12;
729
777
 
@@ -899,7 +947,17 @@ function askFindings(journalPath, at, read, reference) {
899
947
  return findings;
900
948
  }
901
949
 
902
- 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']);
903
961
 
904
962
  function leaseFindings(journalPath, at, events, reference) {
905
963
  const findings = [];
@@ -1416,6 +1474,64 @@ function absentMistakes(repoRoot, path, run) {
1416
1474
  checked: `${checked} — never existed`,
1417
1475
  };
1418
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
+
1419
1535
  export function mistakesFindings(repoRoot, run = null) {
1420
1536
  const path = join(repoRoot, MISTAKES_FILE);
1421
1537
  if (!existsSync(path)) return absentMistakes(repoRoot, path, run);
@@ -1524,7 +1640,7 @@ export const ASK_QUEUE_FILES = Object.freeze(['ANSWERS.md', 'conductor.json']);
1524
1640
  * one); without it a marker is reported as present, never as stale — doctor
1525
1641
  * never reads the wall clock.
1526
1642
  */
1527
- export function overnightFindings(dir, { now = null, configDoc = null } = {}) {
1643
+ export function overnightFindings(dir, { now = null, configDoc = null, usageFallback = () => readPlatformUsage() } = {}) {
1528
1644
  const findings = [];
1529
1645
  const referenceMs = now !== null ? Date.parse(now) : null;
1530
1646
  const markerPath = join(dir, 'state', 'paused-until.json');
@@ -1584,20 +1700,31 @@ export function overnightFindings(dir, { now = null, configDoc = null } = {}) {
1584
1700
  }
1585
1701
 
1586
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.
1587
1711
  const limits = knowsLimits(configDoc);
1588
1712
  if (limits !== null && limits.mode !== 'off') {
1589
1713
  const sidecar = readJsonIfSmall(sidecarPath);
1590
1714
  const writtenMs = sidecar !== null ? Date.parse(typeof sidecar.written_at === 'string' ? sidecar.written_at : '') : NaN;
1591
1715
  const ancient = referenceMs !== null && Number.isFinite(writtenMs) && referenceMs - writtenMs > 24 * 3600 * 1000;
1592
- if (sidecar === null || ancient) {
1716
+ const platform = usageFallback();
1717
+ if ((sidecar === null || ancient) && platform === null) {
1593
1718
  findings.push(
1594
1719
  finding(
1595
1720
  'limit-telemetry-missing',
1596
1721
  show(sidecarPath),
1597
- `limits.mode is "${show(limits.mode)}" but the usage telemetry sidecar is ${sidecar === null ? 'absent' : 'over a day old'} — ` +
1598
- 'the gate fails open without it, so the configured pause protects nothing. The statusline ' +
1599
- 'helper is operator-installed; see https://jjanczur.github.io/tyran/overnight/',
1600
- `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`,
1601
1728
  ),
1602
1729
  );
1603
1730
  }
@@ -1632,7 +1759,13 @@ function knowsLimits(configDoc) {
1632
1759
  return typeof limits.mode === 'string' ? limits : null;
1633
1760
  }
1634
1761
 
1635
- 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
+ } = {}) {
1636
1769
  const root = resolve(dir);
1637
1770
  if (!existsSync(root)) {
1638
1771
  return summarize(dir, [finding('no-state-dir', show(dir), 'no Tyran state directory here — nothing to check')], [
@@ -1699,6 +1832,15 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1699
1832
  }
1700
1833
  }
1701
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')));
1702
1844
 
1703
1845
  const policies = yamlFilesIn(join(dir, 'policies'), 'policies');
1704
1846
  findings.push(...policies.findings);
@@ -1798,7 +1940,11 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
1798
1940
  findings.push(...mistakes.findings);
1799
1941
  checked.push(mistakes.checked);
1800
1942
 
1801
- 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 }));
1802
1948
  checked.push('overnight: checked');
1803
1949
 
1804
1950
  const trackedLeases = trackedLeaseFiles(gitRun, basename(root));
@@ -0,0 +1,254 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * ensure-gitleaks — remove the one prerequisite that blocks day one.
4
+ *
5
+ * The secrets gate refuses every commit and push until `gitleaks` exists, and
6
+ * it refuses rather than warning for a reason that has not changed: a check
7
+ * that passes when its scanner is missing is a check you disable by
8
+ * uninstalling a package.
9
+ *
10
+ * The unstated assumption in that design is that the operator can install a
11
+ * binary. Measured against the people actually adopting this: some have no
12
+ * Homebrew, no admin rights, or are on Windows. For them the realistic
13
+ * outcome of "install gitleaks and re-run" is not a safer repository — it is
14
+ * switching the hook off, or abandoning the tool. A gate nobody can satisfy
15
+ * protects nothing, which is the same argument `.tyran/config.yaml` being
16
+ * AUTO already rests on.
17
+ *
18
+ * So this fetches the scanner instead of asking someone else to. It is the
19
+ * same thing `.github/workflows/ci.yml` has always done — pinned version,
20
+ * pinned checksum — moved to where a user can reach it.
21
+ *
22
+ * ## Why a checksum table and not "download the latest"
23
+ *
24
+ * This writes an executable and something else later runs it. Version alone
25
+ * is not integrity: a tag can be moved, a mirror can lie, and a scanner that
26
+ * has been replaced reports clean on everything. The digests below are the
27
+ * ones GitHub publishes for 8.30.1, and a mismatch DELETES the download and
28
+ * refuses. The linux_x64 line is the same digest ci.yml already pins, which
29
+ * is the cross-check that this table was transcribed and not invented.
30
+ *
31
+ * Usage:
32
+ * node scripts/ensure-gitleaks.mjs [--check]
33
+ *
34
+ * Exit: 0 present or installed · 1 unavailable (reason printed) · 2 usage.
35
+ */
36
+ import { createHash } from 'node:crypto';
37
+ import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
38
+ import { execFileSync } from 'node:child_process';
39
+ import { join } from 'node:path';
40
+ import { homedir, tmpdir } from 'node:os';
41
+
42
+ /** The version this table describes. Bumping it means re-fetching every digest. */
43
+ export const GITLEAKS_VERSION = '8.30.1';
44
+
45
+ /**
46
+ * SHA-256 per platform, from the release's own `checksums.txt`.
47
+ *
48
+ * Keyed `<process.platform>-<process.arch>` so the lookup cannot drift from
49
+ * what Node reports. A platform absent from this table is a REFUSAL with
50
+ * instructions, never a silent skip — an unknown platform is exactly where a
51
+ * "best effort" download would install something unverified.
52
+ */
53
+ export const GITLEAKS_SHA256 = Object.freeze({
54
+ 'darwin-arm64': 'b40ab0ae55c505963e365f271a8d3846efbc170aa17f2607f13df610a9aeb6a5',
55
+ 'darwin-x64': 'dfe101a4db2255fc85120ac7f3d25e4342c3c20cf749f2c20a18081af1952709',
56
+ 'linux-arm64': 'e4a487ee7ccd7d3a7f7ec08657610aa3606637dab924210b3aee62570fb4b080',
57
+ // The digest ci.yml pins. If these two ever disagree, one of them is wrong.
58
+ 'linux-x64': '551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb',
59
+ 'win32-arm64': 'b95f5e4f5c425cedca7ee203d9afd29597e692c4924a12ed42f970537c72cc0f',
60
+ 'win32-x64': 'd29144deff3a68aa93ced33dddf84b7fdc26070add4aa0f4513094c8332afc4e',
61
+ });
62
+
63
+ /**
64
+ * Where a managed scanner lives: under the operator's HOME, never the repo.
65
+ *
66
+ * The first shape of this put it in `<repo>/.tyran/bin/`, which is worse in a
67
+ * way worth recording: a path inside the repository travels with a clone, so
68
+ * a planted binary that reports clean on everything would arrive with the
69
+ * checkout — the attack the tracked-only rule for `.gitleaksignore` already
70
+ * exists to prevent, reopened through a file that is not even in a diff.
71
+ * Under the home directory the scanner is the operator's machine, exactly
72
+ * like anything on PATH, and one install serves every repository on it.
73
+ */
74
+ export const MANAGED_DIR = join(homedir(), '.tyran', 'bin');
75
+
76
+ const ASSET_ARCH = Object.freeze({ arm64: 'arm64', x64: 'x64' });
77
+
78
+ /** The release asset name for a platform key, or null if unsupported. */
79
+ export function assetFor(platform = process.platform, arch = process.arch) {
80
+ const a = ASSET_ARCH[arch];
81
+ if (a === undefined) return null;
82
+ if (platform === 'darwin') return `gitleaks_${GITLEAKS_VERSION}_darwin_${a}.tar.gz`;
83
+ if (platform === 'linux') return `gitleaks_${GITLEAKS_VERSION}_linux_${a}.tar.gz`;
84
+ if (platform === 'win32') return `gitleaks_${GITLEAKS_VERSION}_windows_${a}.zip`;
85
+ return null;
86
+ }
87
+
88
+ export const managedBinPath = (platform = process.platform) =>
89
+ join(MANAGED_DIR, platform === 'win32' ? 'gitleaks.exe' : 'gitleaks');
90
+
91
+ /** SHA-256 of a file on disk, hex. */
92
+ export function digestOf(path) {
93
+ return createHash('sha256').update(readFileSync(path)).digest('hex');
94
+ }
95
+
96
+ /**
97
+ * Is a usable `gitleaks` already reachable? Checks the operator's override
98
+ * first, then PATH — the two the gate itself consults, in the gate's order.
99
+ */
100
+ export function alreadyAvailable({ run = defaultRun } = {}) {
101
+ const explicit = process.env.TYRAN_GITLEAKS_BIN;
102
+ if (typeof explicit === 'string' && explicit !== '') {
103
+ return run(explicit, ['version']) === null ? null : { path: explicit, why: 'TYRAN_GITLEAKS_BIN' };
104
+ }
105
+ const version = run('gitleaks', ['version']);
106
+ return version === null ? null : { path: 'gitleaks', why: 'on PATH', version: version.trim() };
107
+ }
108
+
109
+ function defaultRun(bin, args) {
110
+ try {
111
+ return execFileSync(bin, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000 });
112
+ } catch {
113
+ return null;
114
+ }
115
+ }
116
+
117
+ /**
118
+ * Download one URL to a path, following redirects. GitHub answers a release
119
+ * asset with a 302 to a CDN, so a client that does not follow them downloads
120
+ * an HTML document and hashes it — which fails the digest check rather than
121
+ * installing anything, but reports the wrong reason.
122
+ */
123
+ async function download(url, dest, { redirects = 5 } = {}) {
124
+ const { get } = await import('node:https');
125
+ const { createWriteStream } = await import('node:fs');
126
+ return new Promise((resolvePromise, reject) => {
127
+ get(url, { headers: { 'user-agent': 'tyran-ensure-gitleaks' } }, (res) => {
128
+ const { statusCode, headers } = res;
129
+ if (statusCode !== undefined && statusCode >= 300 && statusCode < 400 && headers.location) {
130
+ res.resume();
131
+ if (redirects === 0) return reject(new Error('too many redirects'));
132
+ return resolvePromise(download(headers.location, dest, { redirects: redirects - 1 }));
133
+ }
134
+ if (statusCode !== 200) {
135
+ res.resume();
136
+ return reject(new Error(`HTTP ${statusCode} from ${url}`));
137
+ }
138
+ const file = createWriteStream(dest);
139
+ res.pipe(file);
140
+ file.on('finish', () => file.close(() => resolvePromise(undefined)));
141
+ file.on('error', reject);
142
+ }).on('error', reject);
143
+ });
144
+ }
145
+
146
+ /**
147
+ * Fetch, verify and unpack the pinned scanner into `<dir>/bin/`.
148
+ *
149
+ * The digest is checked BEFORE anything is unpacked and before the file is
150
+ * made executable: an archive that fails is deleted and nothing it contained
151
+ * ever reaches the disk as a program.
152
+ *
153
+ * `tar` does the unpacking on every platform — bsdtar reads zip, and Windows
154
+ * has shipped it since 10 — so this needs no archive library and no
155
+ * dependency, which is the property that lets it ship inside a plugin.
156
+ */
157
+ export async function installGitleaks({ platform = process.platform, arch = process.arch, run = defaultRun } = {}) {
158
+ const key = `${platform}-${arch}`;
159
+ const asset = assetFor(platform, arch);
160
+ const expected = GITLEAKS_SHA256[key];
161
+ if (asset === null || expected === undefined) {
162
+ return { ok: false, reason: `no pinned build for ${key}`, unsupported: true };
163
+ }
164
+ const target = managedBinPath(platform);
165
+ if (existsSync(target) && digestOf(target) !== '' && run(target, ['version']) !== null) {
166
+ return { ok: true, path: target, already: true };
167
+ }
168
+ const url = `https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/${asset}`;
169
+ const staging = join(tmpdir(), `tyran-gitleaks-${process.pid}`);
170
+ mkdirSync(staging, { recursive: true });
171
+ const archive = join(staging, asset);
172
+ try {
173
+ await download(url, archive);
174
+ const actual = digestOf(archive);
175
+ if (actual !== expected) {
176
+ rmSync(staging, { recursive: true, force: true });
177
+ return {
178
+ ok: false,
179
+ reason: `checksum mismatch for ${asset}: expected ${expected}, got ${actual}. Nothing was installed.`,
180
+ };
181
+ }
182
+ execFileSync('tar', ['-xf', archive, '-C', staging], { stdio: 'ignore', timeout: 60_000 });
183
+ const unpacked = join(staging, platform === 'win32' ? 'gitleaks.exe' : 'gitleaks');
184
+ if (!existsSync(unpacked)) {
185
+ rmSync(staging, { recursive: true, force: true });
186
+ return { ok: false, reason: `the archive did not contain a gitleaks binary` };
187
+ }
188
+ mkdirSync(MANAGED_DIR, { recursive: true });
189
+ writeFileSync(target, readFileSync(unpacked));
190
+ if (platform !== 'win32') chmodSync(target, 0o755);
191
+ rmSync(staging, { recursive: true, force: true });
192
+ if (run(target, ['version']) === null) {
193
+ return { ok: false, reason: 'the installed binary did not run — the platform build may not match this machine' };
194
+ }
195
+ return { ok: true, path: target, installed: true, digest: expected };
196
+ } catch (error) {
197
+ rmSync(staging, { recursive: true, force: true });
198
+ return { ok: false, reason: String(error.message ?? error) };
199
+ }
200
+ }
201
+
202
+ const MANUAL =
203
+ 'Install it by hand and re-run:\n' +
204
+ ' macOS brew install gitleaks\n' +
205
+ ' Linux see https://github.com/gitleaks/gitleaks/releases (or your package manager)\n' +
206
+ 'or point TYRAN_GITLEAKS_BIN at an existing binary.';
207
+
208
+ function usage(message) {
209
+ if (message) console.error(`ensure-gitleaks: ${message}`);
210
+ console.error('usage: node scripts/ensure-gitleaks.mjs [--check]');
211
+ process.exit(2);
212
+ }
213
+
214
+ async function main(argv) {
215
+ const args = argv.slice(2);
216
+ for (const arg of args) {
217
+ if (arg.startsWith('--') && arg !== '--check') usage(`unknown flag ${arg}`);
218
+ }
219
+
220
+ const found = alreadyAvailable();
221
+ if (found !== null) {
222
+ console.log(`ensure-gitleaks: already available (${found.why})${found.version ? ` — ${found.version}` : ''}`);
223
+ process.exit(0);
224
+ }
225
+ const local = managedBinPath();
226
+ if (existsSync(local) && defaultRun(local, ['version']) !== null) {
227
+ console.log(`ensure-gitleaks: present at ${local}`);
228
+ process.exit(0);
229
+ }
230
+ if (args.includes('--check')) {
231
+ console.error('ensure-gitleaks: NOT available — the secrets gate refuses every commit and push until it is.');
232
+ console.error(MANUAL);
233
+ process.exit(1);
234
+ }
235
+
236
+ console.log(`ensure-gitleaks: fetching gitleaks ${GITLEAKS_VERSION} for ${process.platform}-${process.arch}…`);
237
+ const result = await installGitleaks();
238
+ if (!result.ok) {
239
+ console.error(`ensure-gitleaks: could not install it (${result.reason})`);
240
+ console.error(MANUAL);
241
+ process.exit(1);
242
+ }
243
+ console.log(`ensure-gitleaks: installed ${result.path}`);
244
+ console.log(`ensure-gitleaks: verified sha256 ${result.digest}`);
245
+ console.log('ensure-gitleaks: the secrets gate finds this automatically — nothing to add to your shell.');
246
+ process.exit(0);
247
+ }
248
+
249
+ if (import.meta.url === `file://${process.argv[1]}`) {
250
+ main(process.argv).catch((error) => {
251
+ console.error(`ensure-gitleaks: ${error.message}`);
252
+ process.exit(1);
253
+ });
254
+ }
@@ -129,8 +129,16 @@ export const DATA_KNOWN = Object.freeze({
129
129
  // normal operation back at itself.
130
130
  decision: Object.freeze(['id', 'text', 'ask', 'ticket', 'signature', 'occurrences', 'path']),
131
131
  finding: Object.freeze(['area', 'claim', 'proof', 'id', 'ticket', 'confidence']),
132
- 'lease.acquired': Object.freeze(['resource', 'holder', 'mode']),
133
- 'lease.released': Object.freeze(['resource', 'holder']),
132
+ // The expiry spellings doctor reads, plus the human description agents
133
+ // attach. Measured across every journal on a real machine, agents wrote
134
+ // `expiry` 33 times, `purpose` 28, `story` 21, `text` 21 — none of them
135
+ // known, so every lease an agent took the trouble to describe reported
136
+ // `journal-key-unread` back at its author. A schema that flags the fields
137
+ // its own agents naturally write is training them to write less.
138
+ 'lease.acquired': Object.freeze([
139
+ 'resource', 'holder', 'mode', 'expiry', 'expires', 'expires_at', 'until', 'purpose', 'story', 'text', 'note',
140
+ ]),
141
+ 'lease.released': Object.freeze(['resource', 'holder', 'text', 'note']),
134
142
  checkpoint: Object.freeze(['phase', 'next_steps']),
135
143
  'retro.entry': Object.freeze(['kind', 'target', 'confidence']),
136
144
  error: Object.freeze(['class', 'detail', 'ticket']),
@@ -685,6 +693,35 @@ function appendUnderLock(file, event, preread = null) {
685
693
  if (issuePrefix !== undefined && isDataObject(stamped.data) && (stamped.data.id === undefined || stamped.data.id === '')) {
686
694
  // a fresh object: the `data` the caller passed in stays the caller's
687
695
  stamped.data = { ...stamped.data, id: nextIdFrom(read().events, issuePrefix) };
696
+ } else if (issuePrefix !== undefined && isDataObject(stamped.data) && typeof stamped.data.id === 'string') {
697
+ // A caller-supplied id that is ALREADY TAKEN is refused.
698
+ //
699
+ // Measured in the field: two implementers running in parallel each passed
700
+ // an id they had worked out for themselves, and both were honoured — the
701
+ // ledger then held two `F-7`s, and "see F-7" is ambiguous forever, because
702
+ // history is append-only and nothing detects it later.
703
+ //
704
+ // The narrow fix, not the broad one. Refusing EVERY caller-supplied id was
705
+ // the first proposal and it removes a documented capability — the comment
706
+ // above says an explicit id still wins, and a test pins it — to prevent a
707
+ // failure that only ever occurs on COLLISION. So collision is what this
708
+ // refuses, and a fresh explicit id still passes untouched.
709
+ //
710
+ // Inside the lock, on the same read as the mint above: a check outside it
711
+ // would let two concurrent writers both pass and both append, which is the
712
+ // exact race being closed.
713
+ const taken = read().events.some(
714
+ (e) => e?.ev === stamped.ev && typeof e?.data?.id === 'string' && e.data.id === stamped.data.id,
715
+ );
716
+ if (taken) {
717
+ throw new Error(
718
+ `invalid event: ${q(stamped.ev)} id ${q(stamped.data.id)} is already used in ${q(file)}.\n` +
719
+ ' Two events under one id make every later reference to it ambiguous, and the journal is\n' +
720
+ ' append-only, so nothing can disambiguate them afterwards.\n' +
721
+ ` Omit "id" and ${q('append')} issues the next free one, which is what it is for — or run\n` +
722
+ ` node scripts/journal.mjs next-id ${q(file)} ${q(issuePrefix)}`,
723
+ );
724
+ }
688
725
  }
689
726
  const errors = validateEvent(stamped);
690
727
  if (errors.length > 0) {
@@ -143,6 +143,60 @@ export function renderBrief(selected, matched, { budget = DEFAULT_BUDGET, dir =
143
143
  return [header, ...lines, ...tail].join('\n') + '\n';
144
144
  }
145
145
 
146
+ /**
147
+ * Which entries can never reach a handoff, and why.
148
+ *
149
+ * The budget is deliberately the pressure that keeps entries scoped, and the
150
+ * omission line names the cost of every individual brief. What nothing did
151
+ * was AGGREGATE that: measured on a real install, `brief '**'` returned **1
152
+ * of 31 entries** and the other thirty were dropped by the 4000-codepoint
153
+ * budget. Ninety kilobytes of measured detail — migration-number races,
154
+ * TEST/PROD schema drift — accumulated for months and reached nobody.
155
+ *
156
+ * That is the opposite of the failure people expect. The store is not
157
+ * expensive to read; it is unread, while growing without bound, and the
158
+ * pressure the budget applies lands on nothing because no one is looking at
159
+ * the total.
160
+ *
161
+ * So this reports the whole store against the budget at once. It is a
162
+ * MEASUREMENT, never an edit: pruning needs judgement about which of two
163
+ * overlapping entries is the true one, and a script that guessed would delete
164
+ * exactly the hard-won detail this exists to protect.
165
+ *
166
+ * `alone` is the diagnostic that matters most: an entry that does not fit the
167
+ * budget even as the ONLY entry can never appear in any brief, under any
168
+ * paths, ever. It is not competing for space — it is unreachable.
169
+ */
170
+ export function auditEntries(entries, { budget = DEFAULT_BUDGET } = {}) {
171
+ const sized = entries.map((entry) => {
172
+ const cost = Array.from(entryLine(entry)).length + 1;
173
+ return { id: entry.id, kind: entry.kind, confidence: entry.confidence, cost, alone: cost > budget };
174
+ });
175
+ // Ranked the way `brief` ranks, so "would reach a brief" means what a brief
176
+ // would actually do rather than what this function finds convenient.
177
+ const ranked = [...sized].sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
178
+ let used = 0;
179
+ let reachable = 0;
180
+ for (const entry of ranked) {
181
+ if (used + entry.cost > budget && reachable > 0) break;
182
+ used += entry.cost;
183
+ reachable += 1;
184
+ }
185
+ const total = sized.reduce((sum, e) => sum + e.cost, 0);
186
+ return {
187
+ budget,
188
+ entries: sized.length,
189
+ // How many a single widest-possible brief could carry.
190
+ reachable,
191
+ unreachable: sized.length - reachable,
192
+ // Entries too large to appear even alone — the ones pruning must address
193
+ // first, because no budget any caller passes will rescue them.
194
+ aloneTooBig: sized.filter((e) => e.alone).map((e) => ({ id: e.id, cost: e.cost })),
195
+ totalCost: total,
196
+ widest: sized.slice().sort((a, b) => b.cost - a.cost).slice(0, 5).map((e) => ({ id: e.id, cost: e.cost })),
197
+ };
198
+ }
199
+
146
200
  // ---------------------------------------------------------------- CLI
147
201
 
148
202
  const VALUE_FLAGS = ['dir', 'kinds', 'limit', 'budget'];
@@ -190,8 +244,10 @@ function parseArgs(argv) {
190
244
 
191
245
  function main() {
192
246
  const [command, ...rest] = process.argv.slice(2);
193
- const usage = 'usage: knowledge.mjs brief [<path>...] [--dir <knowledge-dir>] [--kinds k,k] [--limit N] [--budget CHARS] [--json]';
194
- if (command !== 'brief') {
247
+ const usage =
248
+ 'usage: knowledge.mjs brief [<path>...] [--dir <knowledge-dir>] [--kinds k,k] [--limit N] [--budget CHARS] [--json]\n' +
249
+ ' knowledge.mjs audit [--dir <knowledge-dir>] [--budget CHARS] [--json]';
250
+ if (command !== 'brief' && command !== 'audit') {
195
251
  console.error(usage);
196
252
  process.exit(2);
197
253
  }
@@ -232,6 +288,37 @@ function main() {
232
288
  return;
233
289
  }
234
290
 
291
+ if (command === 'audit') {
292
+ const report = auditEntries(entries, { budget: flags.budget });
293
+ if (flags.json) {
294
+ console.log(jsonEscapeInvisible(JSON.stringify(report, null, 2)));
295
+ process.exitCode = 0;
296
+ return;
297
+ }
298
+ const out = [
299
+ `knowledge audit (${escapeInvisible(flags.dir)})`,
300
+ ` ${report.entries} entries, ${report.totalCost} codepoints total`,
301
+ ` ${report.reachable} could reach one brief at the ${report.budget}-codepoint budget; ` +
302
+ `${report.unreachable} could not`,
303
+ ];
304
+ if (report.aloneTooBig.length > 0) {
305
+ const n = report.aloneTooBig.length;
306
+ out.push(` ${n} entr${n === 1 ? 'y' : 'ies'} cannot appear in ANY brief, even alone:`);
307
+ for (const e of report.aloneTooBig) out.push(` ${escapeInvisible(e.id)} — ${e.cost} codepoints`);
308
+ }
309
+ if (report.widest.length > 0) {
310
+ out.push(' widest:');
311
+ for (const e of report.widest) out.push(` ${escapeInvisible(e.id)} — ${e.cost}`);
312
+ }
313
+ // A measurement, never an edit: which of two overlapping entries is the
314
+ // true one is a judgement, and a script that guessed would delete the
315
+ // hard-won detail this exists to protect.
316
+ out.push(' This reports; it never edits. /tyran:retro consolidates, writing a NEW file for review.');
317
+ process.stdout.write(out.join('\n') + '\n');
318
+ process.exitCode = 0;
319
+ return;
320
+ }
321
+
235
322
  const { selected, matched, limited } = selectEntries(entries, { paths: normalized, kinds: flags.kinds, limit: flags.limit });
236
323
  if (flags.json) {
237
324
  const payload = selected.map(({ id, kind, confidence, text, applies_to, file }) => ({