@ngockhoale/ukit 3.5.17 → 3.5.19

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.
Files changed (62) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/manifests/platform.full.yaml +48 -0
  3. package/package.json +1 -1
  4. package/scripts/audit/field-replay.mjs +7 -7
  5. package/scripts/audit/field-telemetry.mjs +4 -3
  6. package/scripts/release/run-core-batch.mjs +10 -0
  7. package/src/cli/commands/mission.js +102 -0
  8. package/src/cli/commands/rescue.js +83 -0
  9. package/src/cli/index.js +14 -0
  10. package/src/core/compact/contextBudget.js +62 -41
  11. package/src/core/compact/threshold.js +14 -32
  12. package/src/core/observability/schema/registry.js +91 -0
  13. package/src/core/runtimeConfig.js +53 -2
  14. package/src/render/buildVariables.js +2 -5
  15. package/template_project/.claude/commands/ukit/handoff-implement.md +3 -3
  16. package/template_project/.claude/commands/ukit/handoff-review.md +3 -3
  17. package/template_project/.claude/hooks/context-hardcap-gate.sh +47 -20
  18. package/template_project/.claude/hooks/context-window-guard.sh +82 -27
  19. package/template_project/.claude/hooks/handoff-resume.sh +11 -2
  20. package/template_project/.claude/hooks/mission-capture.mjs +37 -0
  21. package/template_project/.claude/hooks/post-compact-observe.mjs +34 -0
  22. package/template_project/.claude/hooks/sensitive-data-guard.mjs +35 -3
  23. package/template_project/.claude/hooks/shell-watch.mjs +34 -0
  24. package/template_project/.claude/hooks/stop-failure-rescue.mjs +109 -0
  25. package/template_project/.claude/settings.json +36 -4
  26. package/template_project/.claude/ukit/index/test-batches-adapters.mjs +8 -3
  27. package/template_project/.claude/ukit/index/test-batches.mjs +80 -28
  28. package/template_project/.claude/ukit/runtime/compact-threshold.mjs +15 -29
  29. package/template_project/.claude/ukit/runtime/context-capacity.mjs +64 -1
  30. package/template_project/.claude/ukit/runtime/execution-ledger.mjs +44 -3
  31. package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs +20 -1
  32. package/template_project/.claude/ukit/runtime/loop-state.mjs +17 -2
  33. package/template_project/.claude/ukit/runtime/mission/checkpoint.mjs +85 -0
  34. package/template_project/.claude/ukit/runtime/mission/classify.mjs +182 -0
  35. package/template_project/.claude/ukit/runtime/mission/drift.mjs +58 -0
  36. package/template_project/.claude/ukit/runtime/mission/graph.mjs +381 -0
  37. package/template_project/.claude/ukit/runtime/mission/hooks.mjs +199 -0
  38. package/template_project/.claude/ukit/runtime/mission/journal.mjs +68 -0
  39. package/template_project/.claude/ukit/runtime/mission/metrics.mjs +64 -0
  40. package/template_project/.claude/ukit/runtime/mission/recall.mjs +132 -0
  41. package/template_project/.claude/ukit/runtime/mission/redact.mjs +25 -0
  42. package/template_project/.claude/ukit/runtime/mission/restore.mjs +107 -0
  43. package/template_project/.claude/ukit/runtime/mission/store.mjs +231 -0
  44. package/template_project/.claude/ukit/runtime/mission/working.mjs +88 -0
  45. package/template_project/.claude/ukit/runtime/prompt-injection-cap.mjs +33 -0
  46. package/template_project/.claude/ukit/runtime/reinject-context.mjs +87 -6
  47. package/template_project/.claude/ukit/runtime/rescue/bundle.mjs +122 -0
  48. package/template_project/.claude/ukit/runtime/rescue/classify-failure.mjs +136 -0
  49. package/template_project/.claude/ukit/runtime/rescue/lease.mjs +65 -0
  50. package/template_project/.claude/ukit/runtime/rescue/reconstruct.mjs +273 -0
  51. package/template_project/.claude/ukit/runtime/rescue/recovery-state.mjs +120 -0
  52. package/template_project/.claude/ukit/runtime/rescue/rollover.mjs +151 -0
  53. package/template_project/.claude/ukit/runtime/sensitive-value-scanner.mjs +1 -1
  54. package/template_project/.claude/ukit/runtime/shell-watch.mjs +294 -0
  55. package/template_project/.claude/ukit/runtime/stop-coordinator.mjs +154 -0
  56. package/template_project/.omp/config.yml +2 -2
  57. package/template_project/.omp/hooks/pre/ukit-bridge.js +69 -2
  58. package/template_project/AGENTS.md +4 -2
  59. package/template_project/CLAUDE.md +4 -2
  60. package/template_project/docs/AI_HANDOFF/RULES.md +4 -4
  61. package/template_project/instructions/core.md +4 -2
  62. package/template_project/ukit/storage/config.json +32 -10
@@ -8,7 +8,7 @@
8
8
  //
9
9
  // Contract (never relaxed):
10
10
  // * Every discovered test file runs. Memory/time thresholds only FLAG; they never skip, filter or kill tests.
11
- // * One batch at a time, one fresh OS process per batch, no parallel workers added by this runner.
11
+ // * One batch at a time, one fresh OS process per batch, in-batch workers only via the `workers` setting (default 1 = serial).
12
12
  // * Batches are whole files (native file paths, never name regexes) so module/file fixtures keep their lifecycle.
13
13
  // * Verdict: PASS only when every inventory test is accounted for, no failure/error, every batch completed and no
14
14
  // guarded path changed. Resource warnings never turn a pass into a failure; an incomplete run is never a pass.
@@ -51,7 +51,7 @@ const toPosix = (p) => String(p).split(path.sep).join('/').replace(/\\/g, '/');
51
51
 
52
52
  export function parseArgs(argv) {
53
53
  const out = { mode: 'run', framework: null, root: null, out: null, json: false, guard: [], changed: false,
54
- batchCases: null, batchFiles: null, heavyMb: null, timeoutMs: null, file: null, python: null,
54
+ batchCases: null, batchFiles: null, workers: null, heavyMb: null, timeoutMs: null, file: null, python: null,
55
55
  resourceWarnings: false, criticalFreeMb: null, extra: [], errors: [] };
56
56
  const num = (flag, v) => { const n = Number(v); if (!Number.isFinite(n) || n <= 0) out.errors.push(`${flag} needs a positive number`); return n; };
57
57
  for (let i = 0; i < argv.length; i += 1) {
@@ -68,6 +68,7 @@ export function parseArgs(argv) {
68
68
  case '--changed': out.changed = true; break;
69
69
  case '--batch-size': out.batchCases = num(a, next()); break;
70
70
  case '--batch-files': out.batchFiles = num(a, next()); break;
71
+ case '--workers': out.workers = Math.floor(num(a, next())); break;
71
72
  case '--heavy-mb': out.heavyMb = num(a, next()); break;
72
73
  case '--timeout-ms': out.timeoutMs = num(a, next()); break;
73
74
  case '--critical-free-mb': { const n = Number(next()); if (!Number.isFinite(n) || n < 0) out.errors.push(`${a} needs a number >= 0`); out.criticalFreeMb = n; break; }
@@ -164,26 +165,68 @@ export function buildInventory(discovered) {
164
165
  // History: .ukit/storage/test-batches/history.json → { files: { "<file>": { isolatedPeakMb, ms } } }.
165
166
  // isolatedPeakMb is recorded ONLY from single-file batches or detect-leaks — a multi-file batch peak is
166
167
  // never attributed to its members.
167
- export function planBatches(inventory, { batchFiles = DEFAULTS.batchFiles, batchCases = null, budgets = BUDGETS, config = {}, history = {}, targetBatchMb = DEFAULTS.targetBatchMb } = {}) {
168
+ export function planBatches(inventory, { batchFiles = DEFAULTS.batchFiles, batchCases = null, budgets = BUDGETS, config = {}, history = {}, targetBatchMb = DEFAULTS.targetBatchMb, workers = 1 } = {}) {
169
+ const W = Number.isInteger(workers) && workers > 1 ? workers : 1;
168
170
  const batches = [];
169
- let cur = null;
170
- const close = () => { if (cur && cur.files.length) batches.push(cur); cur = null; };
171
- for (const file of inventory.files) {
171
+ const info = inventory.files.map((file) => {
172
172
  const category = classifyFile(file, config);
173
- const cases = inventory.caseCounts.get(file);
174
- const caseCap = batchCases ?? budgets[category]?.batch ?? BUDGETS.unit.batch;
175
- const knownMb = history.files?.[file]?.isolatedPeakMb ?? null;
176
- // Measured-heavy and e2e files run alone: no other file shares their process.
177
- const solo = category === 'e2e' || (knownMb != null && knownMb >= targetBatchMb / 2);
178
- if (solo) { close(); batches.push({ files: [file], cases, categories: [category], memMb: knownMb, solo: true }); continue; }
179
- const fits = cur && cur.files.length < batchFiles
180
- && (cases == null || cur.cases == null || cur.cases + cases <= caseCap || cur.files.length === 0)
181
- && (knownMb == null || cur.memMb == null || cur.memMb + knownMb <= targetBatchMb);
182
- if (!fits) { close(); cur = { files: [], cases: cases == null ? null : 0, categories: [], memMb: null, solo: false }; }
183
- cur.files.push(file);
184
- if (cur.cases != null && cases != null) cur.cases += cases; else cur.cases = null;
185
- if (!cur.categories.includes(category)) cur.categories.push(category);
186
- if (knownMb != null) cur.memMb = (cur.memMb ?? 0) + knownMb;
173
+ const hist = history.files?.[file];
174
+ return {
175
+ file, category, cases: inventory.caseCounts.get(file),
176
+ // Case budget is per worker: W workers each run a budget-sized share of the batch.
177
+ caseCap: (batchCases ?? budgets[category]?.batch ?? BUDGETS.unit.batch) * W,
178
+ knownMb: hist?.isolatedPeakMb ?? null,
179
+ ms: Number.isFinite(hist?.ms) ? hist.ms : null,
180
+ };
181
+ });
182
+ const isSolo = (f) => f.category === 'e2e' || (f.knownMb != null && f.knownMb >= targetBatchMb / 2);
183
+ const soloBatch = (f) => ({ files: [f.file], cases: f.cases, categories: [f.category], memMb: f.knownMb, solo: true, ...(W > 1 ? { workers: 1 } : {}) });
184
+ const newBatch = (f) => ({ files: [], cases: f.cases == null ? null : 0, categories: [], memMb: null, solo: false, ms: 0, mems: [] });
185
+ // workers=1 keeps the historical rule (sum of every known peak); workers>1 predicts the peak as the sum of the
186
+ // `workers` largest known peaks, because only that many files execute concurrently.
187
+ const predictedMb = (mems) => (W === 1 ? mems.reduce((x, y) => x + y, 0) : [...mems].sort((x, y) => y - x).slice(0, W).reduce((x, y) => x + y, 0));
188
+ const fits = (cur, f, cap) => cur.files.length < cap
189
+ && (f.cases == null || cur.cases == null || cur.cases + f.cases <= f.caseCap || cur.files.length === 0)
190
+ && (f.knownMb == null || predictedMb([...cur.mems, f.knownMb]) <= targetBatchMb);
191
+ const add = (cur, f) => {
192
+ cur.files.push(f.file);
193
+ if (cur.cases != null && f.cases != null) cur.cases += f.cases; else cur.cases = null;
194
+ if (!cur.categories.includes(f.category)) cur.categories.push(f.category);
195
+ if (f.knownMb != null) { cur.mems.push(f.knownMb); cur.memMb = (cur.memMb ?? 0) + f.knownMb; }
196
+ cur.ms += f.ms ?? 0;
197
+ };
198
+ const finish = (b) => { const { ms, mems, ...rest } = b; return W > 1 ? { ...rest, workers: Math.min(W, b.files.length), ...(ms > 0 ? { estMs: ms } : {}) } : rest; };
199
+ const cap = batchFiles * W;
200
+ const known = info.filter((f) => !isSolo(f) && f.ms != null);
201
+ if (W > 1 && known.length) {
202
+ // Duration-aware packing. Batches run one after another, so a batch costs ~max(longest file, sum/W).
203
+ // Sorting by duration (longest first) and filling each batch with similar-length files lets the long
204
+ // files run CONCURRENTLY in one batch instead of each one becoming its own sequential tail.
205
+ // A batch closes before its work would exceed W lanes as long as its first (longest) file, or on cap/budget/memory.
206
+ const pool = info.filter((f) => !isSolo(f));
207
+ const sorted = known.map((f) => f.ms).sort((x, y) => x - y);
208
+ const median = sorted[Math.floor(sorted.length / 2)];
209
+ const byMs = pool.map((f) => ({ ...f, ms: f.ms ?? median }))
210
+ .sort((x, y) => y.ms - x.ms || (x.file < y.file ? -1 : 1));
211
+ for (const f of info) if (isSolo(f)) batches.push(soloBatch(f));
212
+ let cur = null;
213
+ let lane = 0;
214
+ // Floor so short files are not split into many tiny batches (each fresh process costs ~1 s to start).
215
+ const MIN_BATCH_WORK_MS = 60_000;
216
+ for (const f of byMs) {
217
+ if (cur && (!fits(cur, f, cap) || cur.ms + f.ms > Math.max(lane * W, MIN_BATCH_WORK_MS))) { batches.push(finish(cur)); cur = null; }
218
+ if (!cur) { cur = newBatch(f); lane = f.ms; }
219
+ add(cur, f);
220
+ }
221
+ if (cur && cur.files.length) batches.push(finish(cur));
222
+ return batches.map((b, i) => ({ index: i + 1, ...b }));
223
+ }
224
+ let cur = null;
225
+ const close = () => { if (cur && cur.files.length) batches.push(finish(cur)); cur = null; };
226
+ for (const f of info) {
227
+ if (isSolo(f)) { close(); batches.push(soloBatch(f)); continue; }
228
+ if (!cur || !fits(cur, f, cap)) { close(); cur = newBatch(f); }
229
+ add(cur, f);
187
230
  }
188
231
  close();
189
232
  return batches.map((b, i) => ({ index: i + 1, ...b }));
@@ -224,7 +267,7 @@ export function timeWrapper(platform = process.platform, fileExists = fs.existsS
224
267
 
225
268
  const OUTCOMES = ['passed', 'failed', 'error', 'skipped', 'xfailed', 'xpassed'];
226
269
 
227
- export function aggregate({ inventory, batches, batchResults, guard = null, heavyMb = DEFAULTS.heavyMb, framework, version, runId, startedAt, finishedAt, deferred = null }) {
270
+ export function aggregate({ inventory, batches, batchResults, guard = null, heavyMb = DEFAULTS.heavyMb, framework, version, runId, startedAt, finishedAt, deferred = null, workers = 1 }) {
228
271
  const counts = Object.fromEntries(OUTCOMES.map((o) => [o, 0]));
229
272
  const failedIds = [];
230
273
  const outcomeById = new Map();
@@ -267,7 +310,7 @@ export function aggregate({ inventory, batches, batchResults, guard = null, heav
267
310
  else if (counts.failed || counts.error || fileErrors.length) verdict = 'FAIL';
268
311
  else verdict = 'PASS';
269
312
  return {
270
- runId, framework, frameworkVersion: version ?? null, startedAt, finishedAt,
313
+ runId, framework, frameworkVersion: version ?? null, workers, startedAt, finishedAt,
271
314
  durationMs: finishedAt && startedAt ? Date.parse(finishedAt) - Date.parse(startedAt) : null,
272
315
  inventory: { files: inventory.files.length, tests: total, idLevel: Boolean(inventory.ids), duplicateIds: inventory.duplicates },
273
316
  batches: { planned: batches.length, completed: completed.length, incomplete, notRun },
@@ -390,7 +433,7 @@ export async function runBatch(ctx, adapter, batch, { wrap = timeWrapper() } = {
390
433
  const logFile = path.join(dir, 'output.log');
391
434
  const tmp = path.join(dir, 'tmp');
392
435
  fs.mkdirSync(tmp, { recursive: true });
393
- const command = adapter.batchCommand(ctx, batch.files, report);
436
+ const command = adapter.batchCommand(batch.workers != null ? { ...ctx, workers: batch.workers } : ctx, batch.files, report);
394
437
  const t0 = Date.now();
395
438
  const proc = await spawnBatch({ ...command, env: { ...command.env, UKIT_TEST_TMPDIR: tmp }, cwd: ctx.root, logFile, timeoutMs: ctx.timeoutMs, wrap });
396
439
  const durationMs = Date.now() - t0;
@@ -409,7 +452,7 @@ export async function runBatch(ctx, adapter, batch, { wrap = timeWrapper() } = {
409
452
  index: batch.index, files: batch.files, cases: batch.cases, durationMs, exitCode: proc.code, signal: proc.signal,
410
453
  timedOut: proc.timedOut, complete: !crashed, error: crashed ? (proc.error ?? (proc.timedOut ? `timed out after ${ctx.timeoutMs} ms` : parsed.error ?? `exit ${proc.code}${proc.signal ? ` signal ${proc.signal}` : ''}`)) : null,
411
454
  peakRss, peakRssSource: timeRss != null ? `${wrap.cmd} ${wrap.flag}` : pluginRss != null ? 'in-process ru_maxrss' : 'unknown',
412
- results: parsed.results ?? [], fileErrors: parsed.fileErrors ?? [],
455
+ results: parsed.results ?? [], fileErrors: parsed.fileErrors ?? [], fileMs: parsed.fileMs ?? null,
413
456
  liveThreads: parsed.session?.liveThreads ?? [], liveChildren: parsed.session?.liveChildren ?? [],
414
457
  logTail: crashed ? log.slice(-2000) : undefined,
415
458
  };
@@ -459,6 +502,7 @@ export function makeContext(args, root) {
459
502
  heavyMb: args.heavyMb ?? config.heavyMb ?? DEFAULTS.heavyMb,
460
503
  batchFiles: args.batchFiles ?? config.batchFiles ?? DEFAULTS.batchFiles,
461
504
  batchCases: args.batchCases ?? config.batchCases ?? null,
505
+ workers: (() => { const w = args.workers ?? config.workers ?? 1; return Number.isInteger(w) && w >= 1 ? w : 1; })(),
462
506
  criticalFreeMb: args.criticalFreeMb ?? config.criticalFreeMb ?? DEFAULTS.criticalFreeMb,
463
507
  guard: [...(config.guard ?? []), ...args.guard],
464
508
  };
@@ -468,9 +512,16 @@ export function readHistory(storage) {
468
512
  try { const h = JSON.parse(fs.readFileSync(path.join(storage, 'history.json'), 'utf8')); return h && typeof h === 'object' ? h : { files: {} }; } catch { return { files: {} }; }
469
513
  }
470
514
 
471
- // Only single-file batches give per-file truth; multi-file peaks stay batch-level evidence.
515
+ // Only single-file batches give per-file memory truth; multi-file peaks stay batch-level evidence.
516
+ // Per-file durations come from the framework report of any completed batch (planning hint for balancing).
472
517
  export function updateHistory(history, batchResults) {
473
518
  const next = { files: { ...(history.files ?? {}) }, updatedAt: new Date().toISOString() };
519
+ for (const b of batchResults) {
520
+ if (!b.complete || !b.fileMs) continue;
521
+ for (const [file, ms] of Object.entries(b.fileMs)) {
522
+ if (b.files.includes(file) && Number.isFinite(ms)) next.files[file] = { ...(next.files[file] ?? {}), ms, at: next.updatedAt };
523
+ }
524
+ }
474
525
  for (const b of batchResults) {
475
526
  if (b.complete && b.files.length === 1 && b.peakRss != null) {
476
527
  next.files[b.files[0]] = { isolatedPeakMb: toMb(b.peakRss), ms: b.durationMs, at: next.updatedAt };
@@ -496,7 +547,7 @@ function discoverAndPlan(ctx, adapter) {
496
547
  if (!discovered.ok) return { error: discovered.error, version: discovered.version };
497
548
  const inventory = buildInventory(discovered);
498
549
  const history = readHistory(ctx.storage);
499
- const batches = planBatches(inventory, { batchFiles: ctx.batchFiles, batchCases: ctx.batchCases, budgets: resolveBudgets(ctx.config), config: ctx.config, history });
550
+ const batches = planBatches(inventory, { batchFiles: ctx.batchFiles, batchCases: ctx.batchCases, budgets: resolveBudgets(ctx.config), config: ctx.config, history, workers: ctx.workers });
500
551
  const check = verifyPlan(inventory, batches);
501
552
  if (check.missing.length || check.duplicated.length || check.extra.length) return { error: `internal plan invariant broken: ${JSON.stringify(check)}`, version: discovered.version };
502
553
  return { inventory, batches, version: discovered.version };
@@ -512,7 +563,7 @@ export async function runSuite(ctx, framework, deps = {}) {
512
563
  return { runId: ctx.runId, framework, frameworkVersion: planned.version ?? null, verdict: 'INCOMPLETE', exitCode: EXIT.INCOMPLETE, error: planned.error };
513
564
  }
514
565
  const { inventory, batches } = planned;
515
- fs.writeFileSync(path.join(ctx.runDir, 'manifest.json'), `${JSON.stringify({ framework, files: inventory.files, ids: inventory.ids, batches: batches.map((b) => ({ index: b.index, files: b.files, cases: b.cases })) }, null, 2)}\n`);
566
+ fs.writeFileSync(path.join(ctx.runDir, 'manifest.json'), `${JSON.stringify({ framework, workers: ctx.workers, files: inventory.files, ids: inventory.ids, batches: batches.map((b) => ({ index: b.index, files: b.files, cases: b.cases, ...(b.workers != null ? { workers: b.workers } : {}) })) }, null, 2)}\n`);
516
567
  const guard = ctx.guard.length ? createGuard(ctx.root, ctx.guard) : null;
517
568
  const batchResults = [];
518
569
  let deferred = null;
@@ -523,7 +574,7 @@ export async function runSuite(ctx, framework, deps = {}) {
523
574
  batchResults.push(result);
524
575
  deps.onBatch?.(result, batches.length);
525
576
  }
526
- const summary = aggregate({ inventory, batches, batchResults, guard: guard ? guard.check() : null, heavyMb: ctx.heavyMb, framework, version: planned.version, runId: ctx.runId, startedAt, finishedAt: new Date().toISOString(), deferred });
577
+ const summary = aggregate({ inventory, batches, batchResults, guard: guard ? guard.check() : null, heavyMb: ctx.heavyMb, framework, version: planned.version, runId: ctx.runId, startedAt, finishedAt: new Date().toISOString(), deferred, workers: ctx.workers });
527
578
  if (guard?.truncated) summary.warnings.push({ kind: 'guard-truncated', detail: `guard snapshot capped at ${DEFAULTS.guardMaxEntries} entries — narrow --guard paths` });
528
579
  summary.batchDetail = batchResults.map((b) => ({ index: b.index, files: b.files.length, cases: b.cases, reported: b.results.length, durationMs: b.durationMs, msPerTest: b.msPerTest, peakMb: toMb(b.peakRss), peakSource: b.peakRssSource, complete: b.complete, error: b.error, silentFiles: b.silentFiles }));
529
580
  fs.mkdirSync(ctx.storage, { recursive: true });
@@ -781,6 +832,7 @@ export function renderSummary(s) {
781
832
  L.push(` inventory: ${s.inventory.files} files, ${s.inventory.tests ?? 'n/a (file-level)'} tests · reported ${s.reported}`);
782
833
  L.push(` batches: ${s.batches.completed}/${s.batches.planned} complete${s.batches.incomplete.length ? ` · incomplete #${s.batches.incomplete.join(',#')}` : ''}${s.batches.notRun.length ? ` · not run #${s.batches.notRun.join(',#')}` : ''}`);
783
834
  L.push(` passed ${c.passed} · failed ${c.failed} · error ${c.error} · skipped ${c.skipped} · xfailed ${c.xfailed} · xpassed ${c.xpassed}`);
835
+ L.push(` workers ${s.workers ?? 1}`);
784
836
  L.push(` duration ${Math.round((s.durationMs ?? 0) / 1000)} s · max batch RSS ${s.maxBatchRssMb ?? 'unknown'} MB`);
785
837
  for (const id of s.failedIds.slice(0, 50)) L.push(` FAILED ${id}`);
786
838
  if (s.failedIds.length > 50) L.push(` … ${s.failedIds.length - 50} more failed ids in summary.json`);
@@ -14,7 +14,7 @@ import {
14
14
  } from './token-utils.mjs';
15
15
  // Sibling runtime module: installs copy the whole runtime dir, so the negotiated-capacity
16
16
  // resolver is always present next to this file.
17
- import { resolveContextCapTokens } from './context-capacity.mjs';
17
+ import { resolveContextCapTokens, resolveContextTiers } from './context-capacity.mjs';
18
18
 
19
19
  const DEFAULT_MAX_PROMPT_ENTRIES = 12;
20
20
  const DEFAULT_MAX_OUTPUT_ENTRIES = 12;
@@ -488,38 +488,28 @@ export async function resolveCompactCapacity(config = {}, { record } = {}) {
488
488
  }
489
489
 
490
490
  export async function buildCompactThresholds(config = {}) {
491
- const explicitSoftThreshold = finiteNumber(config?.compact?.tokenThreshold, 0);
492
- const shippedHardCap = positiveInteger(config?.compact?.hardCapTokens, 235_000);
493
- // Upgrade safety: an install that predates compact.contextWindowTokens still carries the
494
- // old 500k hard cap; the cap must never sit above the declared window it guards.
495
- const declaredWindow = positiveInteger(config?.compact?.contextWindowTokens, 0);
496
- const effectiveShippedHardCap = declaredWindow > 0 ? Math.min(shippedHardCap, declaredWindow) : shippedHardCap;
497
- // Only tighten once a record exists: an install with no evidence yet (and every caller
498
- // that passes no project root) keeps the shipped tuning unchanged.
499
- const record = await readContextCapacityRecord(config?.projectRoot);
500
- const negotiated = record ? await resolveCompactCapacity(config, { record }) : null;
501
- const hardCapTokens = negotiated
502
- ? Math.max(1, Math.min(effectiveShippedHardCap, negotiated.capTokens))
503
- : effectiveShippedHardCap;
504
- // An explicit operator tokenThreshold is honoured but still clamped under the
505
- // negotiated cap: an advisory soft/hard pair sitting at or above hardCapTokens can
506
- // never fire, because context-hardcap-gate.sh already refuses tools at the cap
507
- // (C92-H-01 — on a default install tokenThreshold is the shipped 150k default, not a
508
- // real operator choice, so this is correcting a number, not overriding intent).
509
- const softThreshold = explicitSoftThreshold > 0
510
- ? Math.max(1, Math.min(explicitSoftThreshold, hardCapTokens - 1))
511
- : Math.max(1, Math.round(hardCapTokens * SOFT_TO_CAP_RATIO));
491
+ // UKit-owned tiers (compact.bestTokens/okTokens/mandatoryTokens/stopTokens, legacy
492
+ // hardCapTokens -> stopTokens, tokenThreshold -> bestTokens). They are deliberately NOT
493
+ // clamped to contextWindowTokens or the negotiated model window: the tiers are UKit
494
+ // policy, and the host auto-compaction window (rendered separately) keeps sessions below
495
+ // stopTokens. The capacity record is still read for diagnostics only.
496
+ const tiers = resolveContextTiers(config);
497
+ const hardCapTokens = tiers.stopTokens;
498
+ const softThreshold = Math.max(1, Math.min(tiers.bestTokens, hardCapTokens - 1));
512
499
  const hardThreshold = Math.min(
513
500
  hardCapTokens,
514
501
  Math.max(softThreshold + 1, Math.round(softThreshold * 1.6)),
515
502
  );
516
503
  const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
504
+ const record = await readContextCapacityRecord(config?.projectRoot);
505
+ const negotiated = record ? await resolveCompactCapacity(config, { record }) : null;
517
506
 
518
507
  return {
519
508
  softThreshold,
520
509
  hardThreshold,
521
510
  baselineTokens,
522
511
  hardCapTokens,
512
+ tiers,
523
513
  capacitySource: negotiated?.capacity?.source ?? 'shipped',
524
514
  capacityTokens: negotiated?.capacity?.tokens ?? null,
525
515
  };
@@ -958,13 +948,9 @@ export async function buildCompactPressureState(rawState = null, config = {}) {
958
948
  const thresholds = await buildCompactThresholds(config);
959
949
  const rawSoftThreshold = finiteNumber(rawState?.softThreshold, 0);
960
950
  const rawHardThreshold = finiteNumber(rawState?.hardThreshold, 0);
961
- if (!finiteNumber(config?.compact?.tokenThreshold, 0) && rawSoftThreshold > 0) {
962
- // A persisted pair is only honoured while it still sits inside the negotiated cap.
963
- // The record outlives capacity negotiation: an install that ran before the record
964
- // existed, or before the model was verified, carries thresholds tuned for the
965
- // shipped 500k ceiling — restoring them re-pins the advisory ABOVE the live
966
- // hardCapTokens forever (C92-H-02). Falling through keeps the freshly derived
967
- // pair, which is also what the rewritten record persists, so the file self-heals.
951
+ if (!finiteNumber(config?.compact?.tokenThreshold, 0) && !finiteNumber(config?.compact?.bestTokens, 0) && rawSoftThreshold > 0) {
952
+ // A persisted pair is honoured only while it sits strictly inside stopTokens, so a stale
953
+ // record can never pin the advisory at/above the stop line (C92-H-02).
968
954
  if (rawSoftThreshold < thresholds.hardCapTokens) {
969
955
  thresholds.softThreshold = rawSoftThreshold;
970
956
  thresholds.hardThreshold = Math.min(
@@ -30,7 +30,7 @@ export const CAPACITY_ENV_VAR = 'UKIT_CONTEXT_WINDOW_TOKENS';
30
30
  export const DEFAULT_CAPACITY_TOKENS = 100_000;
31
31
  // The shipped operator ceiling (compact.hardCapTokens) — only ever an UPPER bound; negotiated
32
32
  // capacity can tighten it but never raise it.
33
- export const SHIPPED_HARD_CAP_TOKENS = 235_000;
33
+ export const SHIPPED_HARD_CAP_TOKENS = 185_000;
34
34
  // A verified window is only ever usable as an estimate: the response itself plus the
35
35
  // char/token estimator's own undercount must fit too, so only half the window becomes
36
36
  // the advisory cap (500k cap from a 1M window — the original tuning, made explicit).
@@ -149,3 +149,66 @@ export function resolveContextCapTokens({ env, config, modelMetadata } = {}) {
149
149
  capTokens: Math.max(1, Math.min(ceiling, derived)),
150
150
  };
151
151
  }
152
+
153
+ // ── UKit-owned context tiers ──
154
+ // UKit owns these four numbers (compact.bestTokens / okTokens / mandatoryTokens / stopTokens)
155
+ // and they do NOT depend on any model's context window:
156
+ // < best green silent
157
+ // best..ok yellow one-line advisory (delegate broad reads, short replies)
158
+ // ok..mandatory orange staying under mandatoryTokens is required: land, persist, delegate
159
+ // mandatory..stop red over the mandatory line: persist now; new work is blocked at stop
160
+ // >= stop stop the hard gate blocks new work except persist-to-disk writes; host
161
+ // auto-compaction (always automatic) fires and UKit restores the work.
162
+ // Legacy keys keep working: compact.hardCapTokens maps to stopTokens and
163
+ // compact.tokenThreshold maps to bestTokens WHEN SET (they win over the new keys, so an
164
+ // install that pinned them behaves as before; delete them to adopt the shipped tiers).
165
+ export const DEFAULT_CONTEXT_TIERS = Object.freeze({
166
+ bestTokens: 100_000,
167
+ okTokens: 150_000,
168
+ mandatoryTokens: 200_000,
169
+ stopTokens: 250_000,
170
+ });
171
+
172
+ function positiveInt(value) {
173
+ return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0
174
+ ? value
175
+ : null;
176
+ }
177
+
178
+ export function resolveContextTiers(config = {}) {
179
+ const compact = config?.compact ?? {};
180
+ const stop = positiveInt(compact.hardCapTokens) ?? positiveInt(compact.stopTokens) ?? DEFAULT_CONTEXT_TIERS.stopTokens;
181
+ const mandatory = Math.min(positiveInt(compact.mandatoryTokens) ?? DEFAULT_CONTEXT_TIERS.mandatoryTokens, stop);
182
+ const ok = Math.min(positiveInt(compact.okTokens) ?? DEFAULT_CONTEXT_TIERS.okTokens, mandatory);
183
+ const best = Math.min(positiveInt(compact.tokenThreshold) ?? positiveInt(compact.bestTokens) ?? DEFAULT_CONTEXT_TIERS.bestTokens, ok);
184
+ return { bestTokens: best, okTokens: ok, mandatoryTokens: mandatory, stopTokens: stop };
185
+ }
186
+
187
+ // -> 'green' | 'yellow' | 'orange' | 'red' | 'stop'
188
+ export function classifyContextTier(tokens, tiers = DEFAULT_CONTEXT_TIERS) {
189
+ const value = Number(tokens);
190
+ if (!Number.isFinite(value)) return 'green';
191
+ if (value >= tiers.stopTokens) return 'stop';
192
+ if (value >= tiers.mandatoryTokens) return 'red';
193
+ if (value >= tiers.okTokens) return 'orange';
194
+ if (value >= tiers.bestTokens) return 'yellow';
195
+ return 'green';
196
+ }
197
+
198
+ // One-line tier text, shared by the prompt guard and the tool gate. Compaction is always
199
+ // automatic: no tier ever asks the user to run /compact.
200
+ export function contextTierMessage(tier, tokens, tiers = DEFAULT_CONTEXT_TIERS) {
201
+ const n = Math.round(Number(tokens) || 0).toLocaleString('en-US');
202
+ switch (tier) {
203
+ case 'yellow':
204
+ return `UKit context ~${n} tokens (OK): prefer delegating broad reads to subagents and keep replies short.`;
205
+ case 'orange':
206
+ return `UKit context ~${n} tokens (MANDATORY zone ${tiers.okTokens.toLocaleString('en-US')}-${tiers.mandatoryTokens.toLocaleString('en-US')}): staying under ${tiers.mandatoryTokens.toLocaleString('en-US')} is required. Land the current item, defer the rest to docs/STATUS.md or handoff tasks, delegate broad work, start nothing new inline.`;
207
+ case 'red':
208
+ return `UKit context ~${n} tokens: over the mandatory ${tiers.mandatoryTokens.toLocaleString('en-US')} line - land and persist state to disk now; new work is blocked at ${tiers.stopTokens.toLocaleString('en-US')}. Host auto-compaction is automatic; do not ask the user to /compact.`;
209
+ case 'stop':
210
+ return `STOP new work: context >=${tiers.stopTokens.toLocaleString('en-US')} (~${n}) - persist state to disk now (STATUS/handoff); the host auto-compaction will fire and UKit restores the work after it - do not ask the user to /compact.`;
211
+ default:
212
+ return '';
213
+ }
214
+ }
@@ -19,7 +19,9 @@ import { operationCompletionPolicy, foldOperationEvidence, compactOperation, con
19
19
 
20
20
  const LEDGER_VERSION = 1;
21
21
  const RESUME_INTENT_VERSION = 1;
22
- const RESUME_INTENT_TTL_MS = 30 * 60 * 1000;
22
+ // Cross-session reuse bound only. A same-session compaction restore (`compact: true` read)
23
+ // ignores age: multi-hour runs compact long after the intent's PreCompact write.
24
+ const RESUME_INTENT_TTL_MS = 24 * 60 * 60 * 1000;
23
25
  const MAX_RECEIPTS = 24;
24
26
  // TASK-005 (FR-005): bounded OutcomeRecord dedupe slot — a resumable-run
25
27
  // pointer (interrupted run) emits `outcome.observed` once per task; replays
@@ -482,13 +484,17 @@ export async function readResumableExecution(projectRoot, payload = {}) {
482
484
  return { state, ledger, sessionId };
483
485
  }
484
486
 
485
- export async function readResumeIntent(projectRoot, payload = {}, { consume = false, now = Date.now() } = {}) {
487
+ export async function readResumeIntent(projectRoot, payload = {}, { consume = false, now = Date.now(), compact = false } = {}) {
486
488
  const sessionId = explicitSessionId(payload);
487
489
  if (!sessionId) return null;
488
490
  const intent = await readJson(resumeIntentPath(projectRoot, sessionId), null);
489
491
  if (!intent || intent.version !== RESUME_INTENT_VERSION) return null;
490
492
  if (intent.sessionKey !== safeSegment(sessionId) || intent.sessionHash !== resumeSessionHash(sessionId)) return null;
491
- if (!intent.promptKey || !intent.requestKey || !Number.isFinite(intent.expiresAt) || intent.expiresAt <= now) return null;
493
+ if (!intent.promptKey || !intent.requestKey) return null;
494
+ // The file is keyed by session id and re-checked against sessionHash above, so a compact
495
+ // read is same-session by construction: age is irrelevant there.
496
+ if (!compact && (!Number.isFinite(intent.expiresAt) || intent.expiresAt <= now)) return null;
497
+ if (intent.cwd && intent.cwd !== projectRoot) return null;
492
498
 
493
499
  const state = await readRouteState(projectRoot, payload);
494
500
  const ledger = await readExecutionLedger(projectRoot, payload);
@@ -515,6 +521,39 @@ export async function readResumeIntent(projectRoot, payload = {}, { consume = fa
515
521
  return intent;
516
522
  }
517
523
 
524
+ // Durable mission snapshot persisted at PreCompact so the post-compaction session can
525
+ // re-orient without the host summary: goal, contract, evidence, next step, git state.
526
+ function resumeIntentSnapshot(state, ledger, cwd) {
527
+ const routing = state?.routingContext || {};
528
+ const goal = String(routing.lastExplicitUserPromptText ?? routing.promptText ?? '').slice(0, 4000);
529
+ const contract = state?.routeSummary?.executionContract?.taskKind
530
+ || state?.routeSummary?.taskKind || state?.routeSummary?.executionMode || null;
531
+ let unmet = [];
532
+ let reason = '';
533
+ try {
534
+ if (state?.routeSummary?.executionContract?.taskKind) {
535
+ const verdict = evaluateCompletion({ state, ledger, cwd });
536
+ unmet = verdict.missingEvidence || [];
537
+ reason = String(verdict.reason || '').slice(0, 400);
538
+ } else {
539
+ unmet = requiredEvidence(state).filter((item) => !evidenceSatisfied(item, ledger, state));
540
+ }
541
+ } catch { /* snapshot is best-effort; the identity fields above stay authoritative */ }
542
+ const observed = [ledger?.sourceSucceeded && 'source-read', ledger?.writeSucceeded && 'write-receipt',
543
+ ledger?.verificationSucceeded && 'verification-receipt'].filter(Boolean);
544
+ const dirty = gitOutputRaw(['status', '--porcelain'], cwd);
545
+ return {
546
+ goal,
547
+ contract,
548
+ observedEvidence: observed,
549
+ unmetEvidence: unmet.slice(0, 12),
550
+ nextStep: unmet.length
551
+ ? `Produce the missing evidence (${unmet.slice(0, 6).join(', ')}) for the goal above${reason ? ` — ${reason}` : ''}`
552
+ : 'Re-check completion evidence against the goal, then finish or continue the next missing milestone',
553
+ git: { head: gitOutputRaw(['rev-parse', 'HEAD'], cwd), dirtyFiles: dirty ? dirty.split('\n').length : 0 },
554
+ };
555
+ }
556
+
518
557
  export async function writeResumeIntent(projectRoot, payload = {}, { now = Date.now() } = {}) {
519
558
  const sessionId = explicitSessionId(payload);
520
559
  if (!sessionId) return null;
@@ -533,6 +572,8 @@ export async function writeResumeIntent(projectRoot, payload = {}, { now = Date.
533
572
  taskInstanceId: state.taskInstanceId || null,
534
573
  requestKey: ledger.requestKey,
535
574
  routeFingerprint: state.fingerprint || null,
575
+ cwd: projectRoot,
576
+ ...resumeIntentSnapshot(state, ledger, projectRoot),
536
577
  createdAt: now,
537
578
  expiresAt: now + RESUME_INTENT_TTL_MS,
538
579
  };
@@ -16,6 +16,7 @@ let recordAllowedSuccess = () => 0;
16
16
  try { ({ adviseOnBlock, recordAllowedSuccess } = await import('./block-breaker.mjs')); } catch { /* advisory only */ }
17
17
  // TASK-019: chain rows and direct-hook rows share one versioned schema and one
18
18
  // append API (hook-telemetry.mjs) — including safeName for session files.
19
+ import { capPromptInjection, DEFAULT_MAX_PROMPT_INJECTION_CHARS } from './prompt-injection-cap.mjs';
19
20
  import { appendTelemetryRow, recordHookTiming, TELEMETRY_VERSION } from './hook-telemetry.mjs';
20
21
  // TASK-018 review fix round 1: the chain budget is resolved by ONE shared module
21
22
  // so the runner's inner deadline and the bridge's outer pi.exec timeout can never
@@ -224,6 +225,24 @@ function coalesceJsonStdout(text) {
224
225
  return `${JSON.stringify(merged)}\n`;
225
226
  }
226
227
 
228
+ function readPromptInjectionCap(projectRoot) {
229
+ try {
230
+ const cfg = JSON.parse(fs.readFileSync(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8'));
231
+ const n = Number(cfg?.compact?.maxPromptInjectionChars);
232
+ return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_PROMPT_INJECTION_CHARS;
233
+ } catch { return DEFAULT_MAX_PROMPT_INJECTION_CHARS; }
234
+ }
235
+
236
+ function capPromptOutput(out, payloadText, firstScriptArg) {
237
+ try {
238
+ const payload = JSON.parse(payloadText || '{}');
239
+ if (payload?.hook_event_name !== 'UserPromptSubmit') return out;
240
+ const first = firstScriptArg ? parseScriptArg(firstScriptArg).scriptPath : '';
241
+ const projectRoot = first ? path.resolve(path.dirname(first), '../..') : (payload.cwd || process.cwd());
242
+ return capPromptInjection(out, readPromptInjectionCap(projectRoot));
243
+ } catch { return out; }
244
+ }
245
+
227
246
  // B1 (TASK-001, SPEC §FR-001): a child that emits a `hookSpecificOutput`
228
247
  // permission decision owns the verdict. `hookSpecificOutput` alone is NOT
229
248
  // enough — a child killed mid-write can carry the marker in a truncated
@@ -980,7 +999,7 @@ try {
980
999
  else process.stderr.write(breakerAdvice(`${last.scriptName} blocked (exit 2) with no reason`));
981
1000
  process.exitCode = 2;
982
1001
  } else {
983
- process.stdout.write(coalesceJsonStdout(`${contextStdout}${last.stdout || ''}`));
1002
+ process.stdout.write(capPromptOutput(coalesceJsonStdout(`${contextStdout}${last.stdout || ''}`), payloadText, scriptPaths[0]));
984
1003
  // A spawn-unavailable `last` carries only the warning already written above.
985
1004
  if (last.stderr && last.failureKind !== 'spawn-unavailable') process.stderr.write(last.stderr);
986
1005
  process.exitCode = last.code === 0 ? 0 : (lastIsFailClosed ? 2 : 0);
@@ -53,6 +53,19 @@ async function coherentRoutingContext(root, sessionId) {
53
53
  return state.routingContext || {};
54
54
  }
55
55
 
56
+ // Git HEAD sha read straight from .git (no spawn). A commit moves HEAD, which stales prior
57
+ // verification verdicts, so re-verifying after a commit is progress, not a stalled retry.
58
+ async function gitHead(root) {
59
+ try {
60
+ const head = (await fs.readFile(path.join(root, '.git', 'HEAD'), 'utf8')).trim();
61
+ const m = /^ref:\s*(\S+)$/.exec(head);
62
+ if (!m) return head.slice(0, 40);
63
+ try { return (await fs.readFile(path.join(root, '.git', ...m[1].split('/')), 'utf8')).trim().slice(0, 40); } catch {}
64
+ const packed = await fs.readFile(path.join(root, '.git', 'packed-refs'), 'utf8');
65
+ return packed.split('\n').find((l) => l.endsWith(` ${m[1]}`))?.split(' ')[0] || '';
66
+ } catch { return ''; }
67
+ }
68
+
56
69
  export async function progressFingerprint(root, runRoot = root, payload = {}) {
57
70
  let cur = 'no-run';
58
71
  try {
@@ -66,7 +79,7 @@ export async function progressFingerprint(root, runRoot = root, payload = {}) {
66
79
  const led = await readJson(cache(root, path.join('exec-ledger', `${id || 'default'}.json`)), {});
67
80
  const bank = (f) => Object.keys(led[f] && typeof led[f] === 'object' ? led[f] : {}).sort();
68
81
  const rc = await coherentRoutingContext(root, payload.session_id);
69
- return sha(JSON.stringify([cur, bank('bankedWrites'), bank('bankedVerifications'), rc.lastExplicitUserPromptText || '', rc.mutationOrder, rc.planOnly]));
82
+ return sha(JSON.stringify([cur, bank('bankedWrites'), bank('bankedVerifications'), rc.lastExplicitUserPromptText || '', rc.mutationOrder, rc.planOnly, await gitHead(root)]));
70
83
  }
71
84
 
72
85
  // Mode: router-stamped routingContext only.
@@ -142,8 +155,10 @@ export async function applyLoopBreak({ merged, projectRoot, runRoot, payload, se
142
155
  });
143
156
  if (!res?.limitReached) return merged;
144
157
  const minutes = Math.max(0, Math.round((now - res.firstBlockedAt) / 60_000));
158
+ // attemptCount includes the current block, which is released rather than refused.
159
+ const refused = Math.max(1, res.attemptCount - 1);
145
160
  const note = [
146
- `[ukit-loop-breaker] BLOCKED/ESCALATED: ${merged.policyOwner} refused this stop ${res.attemptCount - 1} consecutive times with no change in the work state (~${minutes} min, mode ${mode || 'UNKNOWN'}).`,
161
+ `[ukit-loop-breaker] BLOCKED/ESCALATED: ${merged.policyOwner} refused this stop ${refused} consecutive ${refused === 1 ? 'time' : 'times'} with no change in the work state (~${minutes} min, mode ${mode || 'UNKNOWN'}).`,
147
162
  `Unresolved blocker: ${String(merged.reason || '').split('\n', 1)[0].slice(0, 200)}`,
148
163
  'Stop released. This is NOT approval: completion evidence was not accepted by the blocking policy; this does not mean no verification ran; no safety/permission denial is lifted.',
149
164
  'Report it verbatim; do not retry, wake up, or resume any handoff.',
@@ -0,0 +1,85 @@
1
+ // Mission semantic checkpoint (WP3). Contract:
2
+ // writeCheckpoint({projectRoot, missionId, trigger, git, graph?, now?}) -> Promise<checkpoint|null>
3
+ // writes <mid>/checkpoints/<seq>.json atomically (tmp+rename), keeps the last 5, never throws.
4
+ // latestCheckpoint(projectRoot, missionId) -> checkpoint|null
5
+ // Checkpoint {v,seq,ts,graphRev,trigger,objective:{promptId,text},facts[{text,src}],activeReqIds,decisions[{id,text,status}],
6
+ // hypotheses[],assumptions[],pending[],failures[],restrictions[],activeTaskId,nextAction,git:{head,branch,dirty},
7
+ // stop:{ownerStop,blockers[]}}
8
+ // Typed buckets never merge. facts come ONLY from verified ACs that hold ac.evidence; a hypothesis linked to an AC
9
+ // (acId) moves to facts only when that AC has evidence. Planned/unverified work is listed under pending, never as done.
10
+ import fs from 'node:fs';
11
+ import path from 'node:path';
12
+ import { loadGraph } from './graph.mjs';
13
+ import { listPrompts } from './journal.mjs';
14
+ import { missionDir, readJsonFile, writeJsonAtomicFile } from './store.mjs';
15
+ import { activeTaskOf, buildWorkingMemory, readMemoryItems } from './working.mjs';
16
+
17
+ export const KEEP_CHECKPOINTS = 5;
18
+ const num = (id) => Number(String(id).replace(/\D/g, '')) || 0;
19
+ const dirOf = (projectRoot, mid) => path.join(missionDir(projectRoot, mid), 'checkpoints');
20
+
21
+ function seqs(projectRoot, mid) {
22
+ try { return fs.readdirSync(dirOf(projectRoot, mid)).filter((f) => /^\d+\.json$/.test(f)).map((f) => num(f)).sort((a, b) => a - b); } catch { return []; }
23
+ }
24
+
25
+ export function latestCheckpoint(projectRoot, missionId) {
26
+ const all = seqs(projectRoot, missionId);
27
+ for (let i = all.length - 1; i >= 0; i -= 1) {
28
+ const c = readJsonFile(path.join(dirOf(projectRoot, missionId), `${all[i]}.json`), null);
29
+ if (c) return c;
30
+ }
31
+ return null;
32
+ }
33
+
34
+ export function buildBuckets(g, items, prompts) {
35
+ const first = prompts.find((p) => p.origin === 'user');
36
+ const facts = [];
37
+ for (const ac of Object.values(g.state.acs)) {
38
+ const ev = ac.status === 'verified' ? (ac.evidence || [])[ac.evidence.length - 1] : null;
39
+ if (ev) facts.push({ text: `${ac.id} verified: ${g.acText(ac)}`.slice(0, 200), src: `${ev.kind}:${ev.ref}` });
40
+ }
41
+ const verifiedAc = (id) => id && g.state.acs[id]?.status === 'verified' && (g.state.acs[id].evidence || []).length > 0;
42
+ const hypotheses = [];
43
+ for (const h of items.hypotheses) {
44
+ if (verifiedAc(h.acId)) { const ev = g.state.acs[h.acId].evidence.slice(-1)[0]; facts.push({ text: h.text, src: `${ev.kind}:${ev.ref}` }); } else hypotheses.push({ id: h.id, text: h.text });
45
+ }
46
+ const live = Object.values(g.state.reqs).filter((r) => (r.status === 'active' || r.status === 'conflict') && r.kind !== 'question');
47
+ const pending = Object.values(g.state.tasks).filter((t) => !['verified', 'cancelled'].includes(t.status))
48
+ .sort((a, b) => num(a.id) - num(b.id)).slice(0, 40).map((t) => ({ id: t.id, status: t.status, title: t.title.slice(0, 100) }));
49
+ const lastUser = [...prompts].reverse().find((p) => p.origin === 'user');
50
+ const restrictions = Object.values(g.state.reqs).filter((r) => (r.kind === 'prohibition' || r.kind === 'constraint') && r.status !== 'superseded')
51
+ .slice(0, 20).map((r) => ({ id: r.id, text: r.text.slice(0, 160), promptId: r.promptId }));
52
+ return {
53
+ objective: first ? { promptId: first.promptId, text: first.text.slice(0, 300) } : { promptId: null, text: '' },
54
+ facts: facts.slice(-40), hypotheses: hypotheses.slice(-20), pending, restrictions,
55
+ activeReqIds: live.map((r) => r.id).slice(0, 60),
56
+ decisions: items.decisions.slice(-30).map((d) => ({ id: d.id, text: d.text, status: d.status || 'accepted' })),
57
+ assumptions: items.assumptions.slice(-20).map((a) => ({ id: a.id, text: a.text })),
58
+ failures: items.failures.slice(-20).map((f) => ({ id: f.id, text: f.text })),
59
+ stop: {
60
+ ownerStop: Boolean(lastUser?.ownerStop),
61
+ blockers: Object.entries(g.state.blockers).map(([taskId, b]) => ({ taskId, code: b.code, reason: String(b.reason || '').slice(0, 120) })).slice(0, 20),
62
+ },
63
+ };
64
+ }
65
+
66
+ export async function writeCheckpoint({ projectRoot, missionId, trigger = 'manual', git = {}, graph, now = Date.now() } = {}) {
67
+ try {
68
+ const g = graph || await loadGraph({ projectRoot, missionId });
69
+ const items = readMemoryItems(projectRoot, missionId);
70
+ const b = buildBuckets(g, items, listPrompts(projectRoot, missionId));
71
+ const working = await buildWorkingMemory({ projectRoot, missionId, graph: g, now });
72
+ const all = seqs(projectRoot, missionId);
73
+ const seq = (all[all.length - 1] || 0) + 1;
74
+ const cp = {
75
+ v: 1, seq, ts: now, graphRev: g.state.rev, trigger, ...b,
76
+ activeTaskId: activeTaskOf(g)?.id || null, nextAction: working?.nextAction || '',
77
+ git: { head: git.head || null, branch: git.branch || null, dirty: Boolean(git.dirty) },
78
+ };
79
+ writeJsonAtomicFile(path.join(dirOf(projectRoot, missionId), `${seq}.json`), cp);
80
+ for (const old of seqs(projectRoot, missionId).slice(0, -KEEP_CHECKPOINTS)) {
81
+ try { fs.unlinkSync(path.join(dirOf(projectRoot, missionId), `${old}.json`)); } catch { /* */ }
82
+ }
83
+ return cp;
84
+ } catch { return null; }
85
+ }