@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/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +186 -0
- package/README.md +1 -1
- package/package.json +1 -1
- package/scripts/board-html.mjs +99 -3
- package/scripts/board.mjs +38 -5
- package/scripts/cost.mjs +189 -27
- package/scripts/doctor.mjs +147 -15
- package/scripts/journal.mjs +179 -0
- package/scripts/migrate.mjs +191 -0
- package/scripts/project.mjs +159 -7
- package/scripts/schema.mjs +27 -1
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
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
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
|
-
/**
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
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(
|
|
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 === '--
|
|
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(
|
|
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({
|
|
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
|
-
|
|
773
|
-
|
|
774
|
-
|
|
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) {
|
package/scripts/doctor.mjs
CHANGED
|
@@ -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 {
|
|
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
|
-
/**
|
|
63
|
-
|
|
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
|
-
|
|
304
|
-
|
|
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
|
-
|
|
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 (
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|