@jjanczur/tyran 0.1.9 → 0.1.11
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 +58 -0
- package/README.md +4 -1
- package/agents/implementer.md +23 -6
- package/agents/retro.md +4 -0
- package/agents/reviewer.md +4 -0
- package/agents/scout.md +4 -1
- package/bin/tyran.mjs +8 -0
- package/hooks/HOOK-CONTRACT-MEASURED.md +50 -3
- package/hooks/hooks.json +10 -0
- package/hooks/scripts/policy-gate.mjs +3 -4
- package/hooks/scripts/session-start.mjs +43 -4
- package/hooks/scripts/usage-gate.mjs +465 -0
- package/package.json +1 -1
- package/scripts/doctor.mjs +181 -4
- package/scripts/hooks-check.mjs +41 -4
- package/scripts/journal.mjs +73 -2
- package/scripts/overnight.mjs +599 -0
- package/scripts/project.mjs +178 -24
- package/scripts/scan-repo.mjs +59 -16
- package/scripts/schema.mjs +62 -1
- package/scripts/statusline.mjs +161 -0
- package/skills/run/SKILL.md +34 -1
- package/skills/setup/SKILL.md +20 -0
- package/skills/status/SKILL.md +9 -5
- package/templates/config.yaml +20 -0
package/scripts/doctor.mjs
CHANGED
|
@@ -35,7 +35,7 @@
|
|
|
35
35
|
* with no answer inside the state directory, because a plugin whose hooks are
|
|
36
36
|
* dead writes no state to be inconsistent with.
|
|
37
37
|
*/
|
|
38
|
-
import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
|
|
38
|
+
import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
|
|
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';
|
|
@@ -154,6 +154,7 @@ export const SEVERITY_BY_CODE = Object.freeze(
|
|
|
154
154
|
// spawns
|
|
155
155
|
'spawn-open': 'info',
|
|
156
156
|
'spawn-stale': 'warning',
|
|
157
|
+
'spawn-blocked': 'warning',
|
|
157
158
|
'spawn-duplicate': 'warning',
|
|
158
159
|
'spawn-orphan-report': 'warning',
|
|
159
160
|
'agent-name-unusable': 'warning',
|
|
@@ -196,6 +197,11 @@ export const SEVERITY_BY_CODE = Object.freeze(
|
|
|
196
197
|
'state-stray-file': 'warning',
|
|
197
198
|
'state-legacy-initiatives-dir': 'warning',
|
|
198
199
|
'lease-file-tracked': 'warning',
|
|
200
|
+
// overnight mode
|
|
201
|
+
'limit-pause-active': 'info',
|
|
202
|
+
'limit-pause-stale': 'warning',
|
|
203
|
+
'limit-resume-watcher-dead': 'warning',
|
|
204
|
+
'limit-telemetry-missing': 'warning',
|
|
199
205
|
}),
|
|
200
206
|
);
|
|
201
207
|
|
|
@@ -669,14 +675,50 @@ function closeSpawnHint(journalPath, init, agent) {
|
|
|
669
675
|
: `node scripts/journal.mjs close-spawn ${sq(journalPath)} ${sq(slug)} ${sq(agent)} --reason "<why>"`;
|
|
670
676
|
}
|
|
671
677
|
|
|
678
|
+
/** How long a self-reported `blocked` may stand before it is a finding. */
|
|
679
|
+
export const DEFAULT_BLOCKED_HOURS = 1;
|
|
680
|
+
|
|
681
|
+
/** The latest `progress` signal per agent, from the raw events. */
|
|
682
|
+
function lastSignals(events) {
|
|
683
|
+
const signals = new Map();
|
|
684
|
+
for (const e of events) {
|
|
685
|
+
if (e?.ev === 'progress' && typeof e?.data?.agent === 'string') {
|
|
686
|
+
signals.set(e.data.agent, { state: e.data.state ?? null, detail: e.data.detail ?? null, ts: e.ts ?? null });
|
|
687
|
+
}
|
|
688
|
+
}
|
|
689
|
+
return signals;
|
|
690
|
+
}
|
|
691
|
+
|
|
672
692
|
function spawnFindings(journalPath, at, dirName, events, reference, staleHours) {
|
|
673
693
|
const findings = [];
|
|
674
694
|
const { open } = pairSpawns(events);
|
|
695
|
+
const signals = lastSignals(events);
|
|
675
696
|
for (const agent of sortedNames(open.keys())) {
|
|
676
697
|
for (const spawn of open.get(agent)) {
|
|
677
698
|
const age = reference === null ? null : hoursBetween(spawn.ts, reference);
|
|
678
699
|
const where = `${show(spawn.data.ticket ?? 'no ticket')}, role ${show(spawn.data.role)}`;
|
|
679
|
-
|
|
700
|
+
// `lastSignals` is keyed by agent NAME, and ADR-18 permits a name to be
|
|
701
|
+
// re-spawned once its previous spawn is closed — so the latest signal
|
|
702
|
+
// under this name may belong to an incarnation that has already
|
|
703
|
+
// reported, whose blockage the report cleared. Only a signal emitted
|
|
704
|
+
// during THIS spawn describes the agent running now; a pair that cannot
|
|
705
|
+
// be ordered (a hand-edited timestamp) is not evidence either.
|
|
706
|
+
const latest = signals.get(agent) ?? null;
|
|
707
|
+
const sinceSpawn = latest === null ? null : hoursBetween(spawn.ts, latest.ts);
|
|
708
|
+
const signal = sinceSpawn !== null && sinceSpawn >= 0 ? latest : null;
|
|
709
|
+
const blockedHours =
|
|
710
|
+
signal?.state === 'blocked' && reference !== null ? hoursBetween(signal.ts, reference) : null;
|
|
711
|
+
if (blockedHours !== null && blockedHours >= DEFAULT_BLOCKED_HOURS) {
|
|
712
|
+
findings.push(
|
|
713
|
+
finding(
|
|
714
|
+
'spawn-blocked',
|
|
715
|
+
at,
|
|
716
|
+
`agent "${show(agent)}" reported itself BLOCKED ${blockedHours.toFixed(1)} h of journal time ago ` +
|
|
717
|
+
`(${show(signal.detail ?? 'no detail')}) and nothing has cleared it. ${where}`,
|
|
718
|
+
closeSpawnHint(journalPath, spawn.init ?? dirName, agent),
|
|
719
|
+
),
|
|
720
|
+
);
|
|
721
|
+
} else if (age !== null && age >= staleHours) {
|
|
680
722
|
findings.push(
|
|
681
723
|
finding(
|
|
682
724
|
'spawn-stale',
|
|
@@ -692,7 +734,9 @@ function spawnFindings(journalPath, at, dirName, events, reference, staleHours)
|
|
|
692
734
|
finding(
|
|
693
735
|
'spawn-open',
|
|
694
736
|
at,
|
|
695
|
-
`agent "${show(agent)}" is still working (spawned ${show(spawn.ts)})
|
|
737
|
+
`agent "${show(agent)}" is still working (spawned ${show(spawn.ts)})` +
|
|
738
|
+
(signal ? ` — last signal ${show(signal.state)} at ${show(signal.ts)}` : '') +
|
|
739
|
+
`. ${where}`,
|
|
696
740
|
),
|
|
697
741
|
);
|
|
698
742
|
}
|
|
@@ -1031,6 +1075,129 @@ export function trackedLeaseFiles(run, tyranDirName = '.tyran') {
|
|
|
1031
1075
|
return listing.split('\n').filter((line) => line !== '' && lease.test(line));
|
|
1032
1076
|
}
|
|
1033
1077
|
|
|
1078
|
+
/** The repo-global overnight runtime files that legally live at state/ level. */
|
|
1079
|
+
export const OVERNIGHT_RUNTIME_FILES = Object.freeze([
|
|
1080
|
+
'paused-until.json',
|
|
1081
|
+
'resume.json',
|
|
1082
|
+
'resume.log',
|
|
1083
|
+
'usage.json',
|
|
1084
|
+
]);
|
|
1085
|
+
|
|
1086
|
+
/**
|
|
1087
|
+
* Overnight-mode consistency: the pause marker, the resume watcher, and the
|
|
1088
|
+
* telemetry a configured gate depends on. Deterministic: staleness questions
|
|
1089
|
+
* are answered only against an explicit `now` (the SessionStart probe passes
|
|
1090
|
+
* one); without it a marker is reported as present, never as stale — doctor
|
|
1091
|
+
* never reads the wall clock.
|
|
1092
|
+
*/
|
|
1093
|
+
export function overnightFindings(dir, { now = null, configDoc = null } = {}) {
|
|
1094
|
+
const findings = [];
|
|
1095
|
+
const referenceMs = now !== null ? Date.parse(now) : null;
|
|
1096
|
+
const markerPath = join(dir, 'state', 'paused-until.json');
|
|
1097
|
+
const resumePath = join(dir, 'state', 'resume.json');
|
|
1098
|
+
const sidecarPath = join(dir, 'state', 'usage.json');
|
|
1099
|
+
|
|
1100
|
+
const marker = readJsonIfSmall(markerPath);
|
|
1101
|
+
if (marker !== null) {
|
|
1102
|
+
const resumeAtMs = Date.parse(typeof marker.resume_at === 'string' ? marker.resume_at : '');
|
|
1103
|
+
const stale = referenceMs !== null && Number.isFinite(resumeAtMs) && resumeAtMs < referenceMs;
|
|
1104
|
+
if (stale) {
|
|
1105
|
+
findings.push(
|
|
1106
|
+
finding(
|
|
1107
|
+
'limit-pause-stale',
|
|
1108
|
+
show(markerPath),
|
|
1109
|
+
`the pause marker's resume time (${show(marker.resume_at)}) has PASSED and the marker is still ` +
|
|
1110
|
+
'here — the watcher died with the machine, or was never scheduled. Autonomous work stays ' +
|
|
1111
|
+
'wound down until this is resolved; the usage gate also self-clears it on the next tool call',
|
|
1112
|
+
`node scripts/overnight.mjs status --dir ${sq(dirname(resolve(dir)))} # then schedule again, or let the gate self-clear`,
|
|
1113
|
+
),
|
|
1114
|
+
);
|
|
1115
|
+
} else {
|
|
1116
|
+
findings.push(
|
|
1117
|
+
finding(
|
|
1118
|
+
'limit-pause-active',
|
|
1119
|
+
show(markerPath),
|
|
1120
|
+
`paused on the ${show(marker.window)} usage window until ${show(marker.resume_at)}` +
|
|
1121
|
+
(marker.long_wait === true ? ' — a LONG pause; the scheduler holds unless told otherwise' : ''),
|
|
1122
|
+
),
|
|
1123
|
+
);
|
|
1124
|
+
}
|
|
1125
|
+
}
|
|
1126
|
+
|
|
1127
|
+
// Outside the marker guard: the watcher unlinks the marker BEFORE spawning
|
|
1128
|
+
// the resume and never restores it, so a failed resume leaves resume.json
|
|
1129
|
+
// with no marker beside it.
|
|
1130
|
+
const resume = readJsonIfSmall(resumePath);
|
|
1131
|
+
if (resume !== null) {
|
|
1132
|
+
const waitingDead =
|
|
1133
|
+
resume.state === 'waiting' && !(Number.isInteger(resume.pid) && resume.pid > 0 && processAlive(resume.pid));
|
|
1134
|
+
if (waitingDead || resume.state === 'failed') {
|
|
1135
|
+
findings.push(
|
|
1136
|
+
finding(
|
|
1137
|
+
'limit-resume-watcher-dead',
|
|
1138
|
+
show(resumePath),
|
|
1139
|
+
waitingDead
|
|
1140
|
+
? `resume.json says a watcher is waiting (pid ${show(String(resume.pid))}) but no such process is alive — a reboot kills detached watchers`
|
|
1141
|
+
: `the last scheduled resume FAILED (${show(resume.reason ?? 'see resume.log')})`,
|
|
1142
|
+
// `schedule` needs the pause marker, and a failed resume has already
|
|
1143
|
+
// consumed it — the fix must be executable in the state that fires.
|
|
1144
|
+
marker !== null
|
|
1145
|
+
? `node scripts/overnight.mjs schedule --dir ${sq(dirname(resolve(dir)))}`
|
|
1146
|
+
: `resume the session by hand (claude --resume; .tyran/state/resume.log names the attempt), then node scripts/overnight.mjs cancel --dir ${sq(dirname(resolve(dir)))} to reset the watcher state`,
|
|
1147
|
+
),
|
|
1148
|
+
);
|
|
1149
|
+
}
|
|
1150
|
+
}
|
|
1151
|
+
|
|
1152
|
+
// A configured control that cannot see is the silent-absence class.
|
|
1153
|
+
const limits = knowsLimits(configDoc);
|
|
1154
|
+
if (limits !== null && limits.mode !== 'off') {
|
|
1155
|
+
const sidecar = readJsonIfSmall(sidecarPath);
|
|
1156
|
+
const writtenMs = sidecar !== null ? Date.parse(typeof sidecar.written_at === 'string' ? sidecar.written_at : '') : NaN;
|
|
1157
|
+
const ancient = referenceMs !== null && Number.isFinite(writtenMs) && referenceMs - writtenMs > 24 * 3600 * 1000;
|
|
1158
|
+
if (sidecar === null || ancient) {
|
|
1159
|
+
findings.push(
|
|
1160
|
+
finding(
|
|
1161
|
+
'limit-telemetry-missing',
|
|
1162
|
+
show(sidecarPath),
|
|
1163
|
+
`limits.mode is "${show(limits.mode)}" but the usage telemetry sidecar is ${sidecar === null ? 'absent' : 'over a day old'} — ` +
|
|
1164
|
+
'the gate fails open without it, so the configured pause protects nothing. The statusline ' +
|
|
1165
|
+
'helper is operator-installed; see docs/overnight.md',
|
|
1166
|
+
`node scripts/statusline.mjs --sidecar-only # wired into the user-settings statusLine command`,
|
|
1167
|
+
),
|
|
1168
|
+
);
|
|
1169
|
+
}
|
|
1170
|
+
}
|
|
1171
|
+
return findings;
|
|
1172
|
+
}
|
|
1173
|
+
|
|
1174
|
+
function readJsonIfSmall(path) {
|
|
1175
|
+
try {
|
|
1176
|
+
if (!existsSync(path) || statSync(path).size > 64 * 1024) return null;
|
|
1177
|
+
const doc = JSON.parse(readFileSync(path, 'utf8'));
|
|
1178
|
+
return doc !== null && typeof doc === 'object' && !Array.isArray(doc) ? doc : null;
|
|
1179
|
+
} catch {
|
|
1180
|
+
return null;
|
|
1181
|
+
}
|
|
1182
|
+
}
|
|
1183
|
+
|
|
1184
|
+
function processAlive(pid) {
|
|
1185
|
+
try {
|
|
1186
|
+
process.kill(pid, 0);
|
|
1187
|
+
return true;
|
|
1188
|
+
} catch {
|
|
1189
|
+
return false;
|
|
1190
|
+
}
|
|
1191
|
+
}
|
|
1192
|
+
|
|
1193
|
+
/** The limits block when the config carries a usable one, else null. */
|
|
1194
|
+
function knowsLimits(configDoc) {
|
|
1195
|
+
if (configDoc === null || typeof configDoc !== 'object') return null;
|
|
1196
|
+
const limits = configDoc.limits;
|
|
1197
|
+
if (limits === null || typeof limits !== 'object' || Array.isArray(limits)) return null;
|
|
1198
|
+
return typeof limits.mode === 'string' ? limits : null;
|
|
1199
|
+
}
|
|
1200
|
+
|
|
1034
1201
|
export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAULT_STALE_HOURS, run = null } = {}) {
|
|
1035
1202
|
const root = resolve(dir);
|
|
1036
1203
|
if (!existsSync(root)) {
|
|
@@ -1045,8 +1212,11 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1045
1212
|
const checked = [];
|
|
1046
1213
|
|
|
1047
1214
|
const configPath = join(dir, 'config.yaml');
|
|
1215
|
+
let configDoc = null;
|
|
1048
1216
|
if (existsSync(configPath)) {
|
|
1049
|
-
|
|
1217
|
+
const configResult = checkSchemaFile('config', configPath);
|
|
1218
|
+
findings.push(...configResult.findings);
|
|
1219
|
+
configDoc = configResult.doc;
|
|
1050
1220
|
checked.push('config.yaml: checked');
|
|
1051
1221
|
} else {
|
|
1052
1222
|
findings.push(
|
|
@@ -1130,6 +1300,10 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1130
1300
|
for (const name of sortedNames(names)) {
|
|
1131
1301
|
const path = join(stateDir, name);
|
|
1132
1302
|
if (!isDirectory(path)) {
|
|
1303
|
+
// Named exemption, not a silent skip: the overnight runtime files
|
|
1304
|
+
// live at the state/ level by design (repo-global, machine-local,
|
|
1305
|
+
// gitignored) and are checked by overnightFindings instead.
|
|
1306
|
+
if (OVERNIGHT_RUNTIME_FILES.includes(name)) continue;
|
|
1133
1307
|
findings.push(
|
|
1134
1308
|
finding(
|
|
1135
1309
|
'state-stray-file',
|
|
@@ -1163,6 +1337,9 @@ export function runStateChecks({ dir = '.tyran', now = null, staleHours = DEFAUL
|
|
|
1163
1337
|
}
|
|
1164
1338
|
checked.push(`initiatives/ (legacy): ${isDirectory(legacyDir) ? 'PRESENT' : 'absent'}`);
|
|
1165
1339
|
|
|
1340
|
+
findings.push(...overnightFindings(dir, { now, configDoc }));
|
|
1341
|
+
checked.push('overnight: checked');
|
|
1342
|
+
|
|
1166
1343
|
const trackedLeases = trackedLeaseFiles(gitRun, basename(root));
|
|
1167
1344
|
if (trackedLeases.length > 0) {
|
|
1168
1345
|
findings.push(
|
package/scripts/hooks-check.mjs
CHANGED
|
@@ -650,7 +650,7 @@ export function shebangInterpreter(firstLine) {
|
|
|
650
650
|
* also be reported as "no shebang", which would bury the finding that
|
|
651
651
|
* actually says what to do.
|
|
652
652
|
*/
|
|
653
|
-
function checkHookFile(path, where, { env }) {
|
|
653
|
+
function checkHookFile(path, where, { env, dispatcher = null }) {
|
|
654
654
|
const findings = [];
|
|
655
655
|
let stat;
|
|
656
656
|
try {
|
|
@@ -688,6 +688,34 @@ function checkHookFile(path, where, { env }) {
|
|
|
688
688
|
// and is the same on every machine. Raised in review as a CI hazard that
|
|
689
689
|
// would have disarmed the mutant for this guard; measuring the bits removes
|
|
690
690
|
// the dependency instead of hoping about the runner.
|
|
691
|
+
// A command of the form `node "<script>"` dispatches through the named
|
|
692
|
+
// interpreter, so neither the mode bits nor a shebang decide whether it can
|
|
693
|
+
// run — the file only has to exist and be readable, and `node` itself has
|
|
694
|
+
// to resolve. Registering this way is the sanctioned route for a hook file
|
|
695
|
+
// an agent authored: the policy gate refuses agent-run chmod on hook paths,
|
|
696
|
+
// deliberately, so the exec bit cannot be set from inside a session.
|
|
697
|
+
if (dispatcher !== null) {
|
|
698
|
+
if (!interpreterExists(dispatcher, env)) {
|
|
699
|
+
findings.push(
|
|
700
|
+
finding(
|
|
701
|
+
'hook-interpreter-absent',
|
|
702
|
+
where,
|
|
703
|
+
`the command dispatches through "${q(dispatcher)}", which is not on PATH and is not an ` +
|
|
704
|
+
'existing absolute path. The spawn fails in the non-blocking way, so the action proceeds.',
|
|
705
|
+
`command -v ${q(dispatcher)}`,
|
|
706
|
+
),
|
|
707
|
+
);
|
|
708
|
+
}
|
|
709
|
+
try {
|
|
710
|
+
readFileSync(path, 'utf8');
|
|
711
|
+
} catch (err) {
|
|
712
|
+
findings.push(
|
|
713
|
+
finding('hook-file-unreadable', where, `cannot read the hook file (${q(err.code ?? err.message)})`),
|
|
714
|
+
);
|
|
715
|
+
}
|
|
716
|
+
return findings;
|
|
717
|
+
}
|
|
718
|
+
|
|
691
719
|
let executable = (stat.mode & 0o111) !== 0;
|
|
692
720
|
if (executable) {
|
|
693
721
|
try {
|
|
@@ -1265,20 +1293,29 @@ export function checkHooks({ root = DEFAULT_PLUGIN_ROOT, env = process.env } = {
|
|
|
1265
1293
|
);
|
|
1266
1294
|
return;
|
|
1267
1295
|
}
|
|
1268
|
-
|
|
1296
|
+
// `node "<script>"` dispatches through the interpreter: the SCRIPT is
|
|
1297
|
+
// the file to check, and mode bits/shebang stop being requirements
|
|
1298
|
+
// (checkHookFile handles that under `dispatcher`).
|
|
1299
|
+
let programWord = lexed.argv[0] ?? '';
|
|
1300
|
+
let dispatcher = null;
|
|
1301
|
+
if (substitute(programWord, vars) === 'node' && typeof lexed.argv[1] === 'string') {
|
|
1302
|
+
dispatcher = 'node';
|
|
1303
|
+
programWord = lexed.argv[1];
|
|
1304
|
+
}
|
|
1305
|
+
const program = substitute(programWord, vars);
|
|
1269
1306
|
if (program === '' || /\$\{/.test(program)) {
|
|
1270
1307
|
findings.push(
|
|
1271
1308
|
finding(
|
|
1272
1309
|
'hook-command-not-modellable',
|
|
1273
1310
|
where,
|
|
1274
|
-
`the command's program word "${q(
|
|
1311
|
+
`the command's program word "${q(programWord)}" still contains a variable this check ` +
|
|
1275
1312
|
'cannot resolve, so the file it names is unknown here.',
|
|
1276
1313
|
),
|
|
1277
1314
|
);
|
|
1278
1315
|
return;
|
|
1279
1316
|
}
|
|
1280
1317
|
const path = resolve(pluginRoot, program);
|
|
1281
|
-
const fileFindings = checkHookFile(path, `${where} -> ${q(path)}`, { env });
|
|
1318
|
+
const fileFindings = checkHookFile(path, `${where} -> ${q(path)}`, { env, dispatcher });
|
|
1282
1319
|
findings.push(...fileFindings);
|
|
1283
1320
|
|
|
1284
1321
|
// Only cross-check the declared event when the file was readable —
|
package/scripts/journal.mjs
CHANGED
|
@@ -40,12 +40,15 @@ export const EVENT_TYPES = Object.freeze([
|
|
|
40
40
|
'init.created',
|
|
41
41
|
'plan.accepted',
|
|
42
42
|
'ticket.created',
|
|
43
|
+
'ticket.status',
|
|
43
44
|
'spawn',
|
|
44
45
|
'report',
|
|
46
|
+
'progress',
|
|
45
47
|
'gate',
|
|
46
48
|
'review',
|
|
47
49
|
'merge',
|
|
48
50
|
'decision',
|
|
51
|
+
'finding',
|
|
49
52
|
'lease.acquired',
|
|
50
53
|
'lease.released',
|
|
51
54
|
'checkpoint',
|
|
@@ -58,17 +61,20 @@ export const EVENT_TYPES = Object.freeze([
|
|
|
58
61
|
* prefix to issue it under. `ticket.created` is deliberately absent: a ticket
|
|
59
62
|
* id comes from the plan, which numbers its own stories.
|
|
60
63
|
*/
|
|
61
|
-
export const ID_ISSUED_FOR = Object.freeze(Object.assign(Object.create(null), { decision: 'D' }));
|
|
64
|
+
export const ID_ISSUED_FOR = Object.freeze(Object.assign(Object.create(null), { decision: 'D', finding: 'F' }));
|
|
62
65
|
|
|
63
66
|
/** Per-type required keys inside `data` (data may always carry extra keys). */
|
|
64
67
|
export const DATA_REQUIRED = Object.freeze({
|
|
65
68
|
'ticket.created': ['id'],
|
|
69
|
+
'ticket.status': ['ticket', 'column'],
|
|
66
70
|
spawn: ['agent', 'role'],
|
|
67
71
|
report: ['agent', 'verdict'],
|
|
72
|
+
progress: ['agent', 'state'],
|
|
68
73
|
gate: ['kind', 'result'],
|
|
69
74
|
review: ['ticket', 'verdict', 'by'],
|
|
70
75
|
merge: ['ticket', 'sha'],
|
|
71
76
|
decision: ['id', 'text'],
|
|
77
|
+
finding: ['area', 'claim'],
|
|
72
78
|
'lease.acquired': ['resource', 'holder'],
|
|
73
79
|
'lease.released': ['resource', 'holder'],
|
|
74
80
|
checkpoint: ['phase', 'next_steps'],
|
|
@@ -76,6 +82,30 @@ export const DATA_REQUIRED = Object.freeze({
|
|
|
76
82
|
error: ['class'],
|
|
77
83
|
});
|
|
78
84
|
|
|
85
|
+
/**
|
|
86
|
+
* Closed VALUE sets inside `data`, for the same reason the event set is
|
|
87
|
+
* closed: an unknown value must be a loud rejection at append time, not a
|
|
88
|
+
* surprise in a projection. Hard errors are safe here because both types are
|
|
89
|
+
* new — no legacy journal can retroactively fail `validate`.
|
|
90
|
+
*
|
|
91
|
+
* `ticket.status.column` is deliberately NARROW: only the lanes no lifecycle
|
|
92
|
+
* event can ever derive. Anything broader would be a second source of truth
|
|
93
|
+
* against the derived board (`done` is what `merge` means; an override saying
|
|
94
|
+
* so would let the two disagree).
|
|
95
|
+
*/
|
|
96
|
+
export const DATA_ENUMS = Object.freeze({
|
|
97
|
+
progress: Object.freeze({ state: Object.freeze(['started', 'working', 'blocked', 'unblocked']) }),
|
|
98
|
+
'ticket.status': Object.freeze({ column: Object.freeze(['blocked', 'waiting-operator', 'parked']) }),
|
|
99
|
+
});
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Free-text keys with a size ceiling, in codepoints. REJECTED at append,
|
|
103
|
+
* never truncated — the journal does not silently shorten anything. Long
|
|
104
|
+
* material belongs in NOTES.md with a reference here. `validateJournal`
|
|
105
|
+
* reports historical oversizes as warnings only (no retroactive errors).
|
|
106
|
+
*/
|
|
107
|
+
export const CAPPED_DATA_KEYS = Object.freeze({ detail: 2000, claim: 2000, proof: 2000 });
|
|
108
|
+
|
|
79
109
|
/**
|
|
80
110
|
* A journal-derived value on its way into a HUMAN-READABLE MESSAGE.
|
|
81
111
|
*
|
|
@@ -130,10 +160,37 @@ export function validateEvent(event) {
|
|
|
130
160
|
errors.push(`data.id must be a string for ev "${q(event.ev)}" (got ${typeof event.data.id})`);
|
|
131
161
|
}
|
|
132
162
|
}
|
|
163
|
+
const enums = DATA_ENUMS[event.ev];
|
|
164
|
+
if (enums) {
|
|
165
|
+
for (const [key, allowed] of Object.entries(enums)) {
|
|
166
|
+
if (key in event.data && !allowed.includes(event.data[key])) {
|
|
167
|
+
// Name the whole set, same as the closed event set above: the agent
|
|
168
|
+
// recovering from this error has no other source of truth.
|
|
169
|
+
errors.push(
|
|
170
|
+
`data.${q(key)} "${q(event.data[key])}" is not valid for ev "${q(event.ev)}" — valid: ${allowed.join(', ')}`,
|
|
171
|
+
);
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
133
175
|
}
|
|
134
176
|
return errors;
|
|
135
177
|
}
|
|
136
178
|
|
|
179
|
+
/**
|
|
180
|
+
* The oversize problem of one capped data key, or null. Codepoints, not
|
|
181
|
+
* UTF-16 units, same as every other length rule in this repo.
|
|
182
|
+
*/
|
|
183
|
+
export function cappedKeyProblem(data) {
|
|
184
|
+
if (data === null || typeof data !== 'object') return null;
|
|
185
|
+
for (const [key, cap] of Object.entries(CAPPED_DATA_KEYS)) {
|
|
186
|
+
const value = data[key];
|
|
187
|
+
if (typeof value === 'string' && Array.from(value).length > cap) {
|
|
188
|
+
return `data.${key} is ${Array.from(value).length} codepoints (cap ${cap}) — put the full text in NOTES.md and reference it here`;
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
return null;
|
|
192
|
+
}
|
|
193
|
+
|
|
137
194
|
// -------------------------------------------------- spawn ↔ report pairing
|
|
138
195
|
|
|
139
196
|
/**
|
|
@@ -410,7 +467,10 @@ function appendUnderLock(file, event, preread = null) {
|
|
|
410
467
|
if (errors.length > 0) {
|
|
411
468
|
throw new Error('invalid event: ' + errors.join('; '));
|
|
412
469
|
}
|
|
413
|
-
if (stamped.ev === 'spawn' || stamped.ev === 'report') {
|
|
470
|
+
if (stamped.ev === 'spawn' || stamped.ev === 'report' || stamped.ev === 'progress') {
|
|
471
|
+
// `progress` joins the guard because data.agent is how a signal attaches
|
|
472
|
+
// to the agent row in the fold — a non-canonical name would silently
|
|
473
|
+
// fail to attach rather than error anywhere.
|
|
414
474
|
const problem = agentNameProblem(stamped.data.agent);
|
|
415
475
|
if (problem) {
|
|
416
476
|
throw new Error(
|
|
@@ -419,6 +479,10 @@ function appendUnderLock(file, event, preread = null) {
|
|
|
419
479
|
);
|
|
420
480
|
}
|
|
421
481
|
}
|
|
482
|
+
{
|
|
483
|
+
const oversize = cappedKeyProblem(stamped.data);
|
|
484
|
+
if (oversize) throw new Error(`invalid event: ${oversize}`);
|
|
485
|
+
}
|
|
422
486
|
if (stamped.ev === 'spawn') {
|
|
423
487
|
// ADR-18: refuse a second OPEN spawn for one agent name. Same lock as the
|
|
424
488
|
// write, same read as the clamp — a check outside the lock would let two
|
|
@@ -556,6 +620,13 @@ export function validateJournal(file) {
|
|
|
556
620
|
for (const [raw, problem] of badNames) {
|
|
557
621
|
warnings.push(`unusable data.agent ${q(raw)}: ${problem} — excluded from spawn↔report pairing`);
|
|
558
622
|
}
|
|
623
|
+
// Historical oversizes are warnings, never errors: the cap is enforced at
|
|
624
|
+
// append time, and a hand-edited file must stay visible without turning a
|
|
625
|
+
// whole journal's `validate` red retroactively.
|
|
626
|
+
events.forEach((e, i) => {
|
|
627
|
+
const oversize = cappedKeyProblem(e?.data);
|
|
628
|
+
if (oversize) warnings.push(`event ${i + 1}: ${oversize}`);
|
|
629
|
+
});
|
|
559
630
|
return { ok: errors.length === 0, errors, warnings, count: events.length, truncatedTail };
|
|
560
631
|
}
|
|
561
632
|
|