@ngockhoale/ukit 3.5.17 → 3.5.18

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 (55) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/manifests/platform.full.yaml +48 -0
  3. package/package.json +1 -1
  4. package/src/cli/commands/mission.js +102 -0
  5. package/src/cli/commands/rescue.js +83 -0
  6. package/src/cli/index.js +14 -0
  7. package/src/core/compact/contextBudget.js +62 -41
  8. package/src/core/compact/threshold.js +14 -32
  9. package/src/core/observability/schema/registry.js +91 -0
  10. package/src/core/runtimeConfig.js +53 -2
  11. package/src/render/buildVariables.js +2 -5
  12. package/template_project/.claude/commands/ukit/handoff-implement.md +3 -3
  13. package/template_project/.claude/commands/ukit/handoff-review.md +3 -3
  14. package/template_project/.claude/hooks/context-hardcap-gate.sh +47 -20
  15. package/template_project/.claude/hooks/context-window-guard.sh +82 -27
  16. package/template_project/.claude/hooks/handoff-resume.sh +11 -2
  17. package/template_project/.claude/hooks/mission-capture.mjs +37 -0
  18. package/template_project/.claude/hooks/post-compact-observe.mjs +34 -0
  19. package/template_project/.claude/hooks/shell-watch.mjs +34 -0
  20. package/template_project/.claude/hooks/stop-failure-rescue.mjs +109 -0
  21. package/template_project/.claude/settings.json +36 -4
  22. package/template_project/.claude/ukit/runtime/compact-threshold.mjs +15 -29
  23. package/template_project/.claude/ukit/runtime/context-capacity.mjs +64 -1
  24. package/template_project/.claude/ukit/runtime/execution-ledger.mjs +44 -3
  25. package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs +20 -1
  26. package/template_project/.claude/ukit/runtime/mission/checkpoint.mjs +85 -0
  27. package/template_project/.claude/ukit/runtime/mission/classify.mjs +182 -0
  28. package/template_project/.claude/ukit/runtime/mission/drift.mjs +58 -0
  29. package/template_project/.claude/ukit/runtime/mission/graph.mjs +381 -0
  30. package/template_project/.claude/ukit/runtime/mission/hooks.mjs +199 -0
  31. package/template_project/.claude/ukit/runtime/mission/journal.mjs +68 -0
  32. package/template_project/.claude/ukit/runtime/mission/metrics.mjs +64 -0
  33. package/template_project/.claude/ukit/runtime/mission/recall.mjs +132 -0
  34. package/template_project/.claude/ukit/runtime/mission/redact.mjs +25 -0
  35. package/template_project/.claude/ukit/runtime/mission/restore.mjs +107 -0
  36. package/template_project/.claude/ukit/runtime/mission/store.mjs +231 -0
  37. package/template_project/.claude/ukit/runtime/mission/working.mjs +88 -0
  38. package/template_project/.claude/ukit/runtime/prompt-injection-cap.mjs +33 -0
  39. package/template_project/.claude/ukit/runtime/reinject-context.mjs +87 -6
  40. package/template_project/.claude/ukit/runtime/rescue/bundle.mjs +122 -0
  41. package/template_project/.claude/ukit/runtime/rescue/classify-failure.mjs +136 -0
  42. package/template_project/.claude/ukit/runtime/rescue/lease.mjs +65 -0
  43. package/template_project/.claude/ukit/runtime/rescue/reconstruct.mjs +273 -0
  44. package/template_project/.claude/ukit/runtime/rescue/recovery-state.mjs +120 -0
  45. package/template_project/.claude/ukit/runtime/rescue/rollover.mjs +151 -0
  46. package/template_project/.claude/ukit/runtime/sensitive-value-scanner.mjs +1 -1
  47. package/template_project/.claude/ukit/runtime/shell-watch.mjs +278 -0
  48. package/template_project/.claude/ukit/runtime/stop-coordinator.mjs +154 -0
  49. package/template_project/.omp/config.yml +2 -2
  50. package/template_project/.omp/hooks/pre/ukit-bridge.js +69 -2
  51. package/template_project/AGENTS.md +3 -1
  52. package/template_project/CLAUDE.md +3 -1
  53. package/template_project/docs/AI_HANDOFF/RULES.md +4 -4
  54. package/template_project/instructions/core.md +3 -1
  55. package/template_project/ukit/storage/config.json +32 -10
@@ -0,0 +1,199 @@
1
+ // Mission hook steps (WP4). Thin glue between host hooks and the mission library; every export is fail-open
2
+ // (never throws, returns '' / null on any error) and cheap. Callers: hooks/mission-capture.mjs (UserPromptSubmit,
3
+ // PostToolUse todo mirror) and runtime/reinject-context.mjs (PreCompact checkpoint, SessionStart restore).
4
+ // captureStep({projectRoot,payload,config?}) -> Promise<string> drift line ('' when none/unchanged); NEVER prompt text
5
+ // todoMirrorStep({projectRoot,payload}) -> Promise<{ok,changed}> TodoWrite/TaskCreate/TaskUpdate -> graph task status
6
+ // preCompactStep({projectRoot,payload}) -> Promise<string> <=600-char note for the PreCompact summary instructions
7
+ // sessionRestoreStep({projectRoot,payload,rescue}) -> Promise<string> mission restore + rescue bundle, <=6000 chars total
8
+ // Lock rule: recordPrompt/persistGraph/appendEvent lock internally, so they are NOT wrapped; checkpoint/restore/metrics
9
+ // write files unlocked and ARE wrapped in withMissionLock (one lock hold, no nested appendEvent inside).
10
+ import crypto from 'node:crypto';
11
+ import fs from 'node:fs';
12
+ import path from 'node:path';
13
+ import { execFileSync } from 'node:child_process';
14
+ import { pathToFileURL, fileURLToPath } from 'node:url';
15
+ import { recordPrompt } from './journal.mjs';
16
+ import { loadGraph, persistGraph } from './graph.mjs';
17
+ import { readActive, ensureMission, missionDir, withMissionLock } from './store.mjs';
18
+ import { writeCheckpoint, latestCheckpoint } from './checkpoint.mjs';
19
+ import { detectDrift } from './drift.mjs';
20
+ import { buildWorkingMemory } from './working.mjs';
21
+ import { renderRestore } from './restore.mjs';
22
+ import { recordCompaction, recordInjection } from './metrics.mjs';
23
+ import { redactText } from './redact.mjs';
24
+
25
+ export const COMBINED_RESTORE_CAP = 6000;
26
+ const MISSION_RESTORE_CAP = 3500;
27
+ const NOTE_CAP = 600;
28
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
29
+
30
+ const sessionKeyOf = (payload) => String(payload?.session_id || payload?.sessionId || 'default').replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 80) || 'default';
31
+ async function emitEvent(projectRoot, type, payload) {
32
+ try { await (await import('../rescue/rollover.mjs')).emitRescueEvent(projectRoot, type, payload); } catch { /* observability is best-effort */ }
33
+ }
34
+ const clip = (s, n) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t; };
35
+
36
+ export function missionEnabled(config) {
37
+ return config?.mission?.enabled !== false;
38
+ }
39
+
40
+ function readConfig(projectRoot) {
41
+ try { return JSON.parse(fs.readFileSync(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8')); } catch { return null; }
42
+ }
43
+
44
+ function existingMissionId(projectRoot, sessionKey) {
45
+ const active = readActive(projectRoot);
46
+ return active?.sessions?.[sessionKey]?.missionId || active?.activeMissionId || null;
47
+ }
48
+
49
+ function gitInfo(projectRoot) {
50
+ const run = (args) => { try { return execFileSync('git', args, { cwd: projectRoot, encoding: 'utf8', timeout: 700, stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return null; } };
51
+ return { head: run(['rev-parse', 'HEAD']), branch: run(['rev-parse', '--abbrev-ref', 'HEAD']), dirty: false, repoRoot: projectRoot };
52
+ }
53
+
54
+ async function ownerStopOf(payload, text) {
55
+ if (payload?.ukit_owner_input === 'contains-stop') return true;
56
+ try {
57
+ const mod = await import(pathToFileURL(path.join(HERE, '..', '..', 'index', 'publication-intent.mjs')).href);
58
+ return mod.classifyOwnerControl(text).kind === 'stop';
59
+ } catch { return false; }
60
+ }
61
+
62
+ const SYSTEM_PROMPT_RE = /^\s*(?:\[SYSTEM NOTIFICATION|<instructions>|<system-reminder>|<task-notification>)/;
63
+
64
+ function driftSignature(findings) {
65
+ return crypto.createHash('sha1').update(findings.map((f) => `${f.code}:${f.ref}`).sort().join('|')).digest('hex').slice(0, 12);
66
+ }
67
+
68
+ export async function captureStep({ projectRoot, payload, config } = {}) {
69
+ try {
70
+ if (!missionEnabled(config ?? readConfig(projectRoot))) return '';
71
+ const text = [payload?.prompt, payload?.user_prompt].find((v) => typeof v === 'string') || '';
72
+ if (!text.trim()) return '';
73
+ const sessionKey = sessionKeyOf(payload);
74
+ const engine = payload?.ukit_harness === 'omp' ? 'omp' : 'claude';
75
+ const system = payload?.ukit_prompt_origin === 'system' || SYSTEM_PROMPT_RE.test(text);
76
+ const ownerStop = system ? false : await ownerStopOf(payload, text);
77
+ const r = await recordPrompt({ projectRoot, sessionKey, text, origin: system ? 'system' : 'user', engine, ownerStop });
78
+ if (!r?.ok || system) return '';
79
+ const g = await loadGraph({ projectRoot, missionId: r.missionId });
80
+ g.applyPrompt(r.prompt);
81
+ await persistGraph(g, { projectRoot, missionId: r.missionId });
82
+ const findings = detectDrift(g, { checkpoint: latestCheckpoint(projectRoot, r.missionId) }).filter((f) => f.severity === 'warn');
83
+ const sigFile = path.join(missionDir(projectRoot, r.missionId), 'drift-sig.txt');
84
+ let prev = '';
85
+ try { prev = fs.readFileSync(sigFile, 'utf8'); } catch { /* first prompt */ }
86
+ const sig = findings.length ? driftSignature(findings) : '';
87
+ if (sig !== prev) { try { fs.writeFileSync(sigFile, sig); } catch { /* best effort */ } }
88
+ if (!sig || sig === prev) return '';
89
+ return clip(`[mission] drift: ${findings[0].code} ${findings[0].ref}${findings.length > 1 ? ` (+${findings.length - 1} more)` : ''} — ukit mission recall`, 160);
90
+ } catch { return ''; }
91
+ }
92
+
93
+ const TODO_STATUS = { pending: 'pending', in_progress: 'in_progress', completed: 'done_unverified', deleted: 'cancelled', cancelled: 'cancelled' };
94
+ const iidOf = (kind, key) => `${kind}:${crypto.createHash('sha1').update(String(key)).digest('hex').slice(0, 16)}`;
95
+
96
+ function responseText(payload) {
97
+ const r = payload?.tool_response ?? payload?.tool_result ?? payload?.tool_output;
98
+ if (typeof r === 'string') return r;
99
+ try { return JSON.stringify(r ?? ''); } catch { return ''; }
100
+ }
101
+
102
+ export async function todoMirrorStep({ projectRoot, payload, config } = {}) {
103
+ try {
104
+ if (!missionEnabled(config ?? readConfig(projectRoot))) return { ok: true, changed: false };
105
+ const tool = payload?.tool_name;
106
+ const input = payload?.tool_input || {};
107
+ const sessionKey = sessionKeyOf(payload);
108
+ const mid = existingMissionId(projectRoot, sessionKey) || ensureMission({ projectRoot, sessionKey })?.missionId;
109
+ if (!mid) return { ok: false, changed: false };
110
+ const g = await loadGraph({ projectRoot, missionId: mid });
111
+ const reqs = Object.values(g.state.reqs).filter((r) => r.status === 'active' && r.kind !== 'question');
112
+ const anchor = reqs[reqs.length - 1] || null; // newest live requirement owns mirrored todos
113
+ let changed = false;
114
+ const sync = (iid, title, rawStatus) => {
115
+ const status = TODO_STATUS[String(rawStatus || 'pending').toLowerCase()] || 'pending';
116
+ let taskId = g.getBinding(iid)?.taskId;
117
+ if (!taskId || !g.state.tasks[taskId]) {
118
+ const dup = Object.values(g.state.tasks).find((t) => t.status !== 'cancelled' && title && t.title === title);
119
+ if (dup) taskId = dup.id;
120
+ else if (title && anchor) {
121
+ const t = g.addTask({ reqIds: [anchor.id], title: clip(title, 200), workstream: anchor.ws });
122
+ if (t) { g.addAc({ taskId: t.id, reqId: anchor.id }); taskId = t.id; }
123
+ }
124
+ if (taskId) g.bindTaskInstance(iid, taskId);
125
+ }
126
+ const cur = taskId && g.state.tasks[taskId];
127
+ if (cur && cur.status !== status && cur.status !== 'verified' && g.setTaskStatus(taskId, status)) changed = true;
128
+ else if (cur && !changed) changed = true; // task created/bound
129
+ };
130
+ if (tool === 'TodoWrite') {
131
+ for (const t of (Array.isArray(input.todos) ? input.todos : []).slice(0, 100)) sync(iidOf('todo', t.id || t.content), t.content || t.subject, t.status);
132
+ } else if (tool === 'TaskCreate') {
133
+ const idMatch = /"id"\s*:\s*"?(\w+)"?|#(\d+)/.exec(responseText(payload));
134
+ const key = idMatch ? (idMatch[1] || idMatch[2]) : input.subject;
135
+ sync(iidOf('task', key), input.subject || input.title, input.status || 'pending');
136
+ } else if (tool === 'TaskUpdate') {
137
+ const key = input.taskId ?? input.id;
138
+ if (key !== undefined) sync(iidOf('task', key), input.subject || input.title || null, input.status);
139
+ }
140
+ if (changed) await persistGraph(g, { projectRoot, missionId: mid });
141
+ return { ok: true, changed };
142
+ } catch { return { ok: false, changed: false }; }
143
+ }
144
+
145
+ export async function preCompactStep({ projectRoot, payload, config } = {}) {
146
+ try {
147
+ if (!missionEnabled(config ?? readConfig(projectRoot))) return '';
148
+ const sessionKey = sessionKeyOf(payload);
149
+ const mid = existingMissionId(projectRoot, sessionKey);
150
+ if (!mid) return '';
151
+ const git = gitInfo(projectRoot);
152
+ const r = await withMissionLock(projectRoot, mid, async () => {
153
+ const g = await loadGraph({ projectRoot, missionId: mid });
154
+ const prev = latestCheckpoint(projectRoot, mid);
155
+ const cp = await writeCheckpoint({ projectRoot, missionId: mid, trigger: 'pre-compact', git, graph: g });
156
+ const findings = detectDrift(g, { checkpoint: prev || cp });
157
+ await buildWorkingMemory({ projectRoot, missionId: mid, graph: g });
158
+ recordCompaction({ projectRoot, missionId: mid });
159
+ return { cp, findings };
160
+ }, { deadlineMs: 800 });
161
+ if (!r.ok || !r.value?.cp) return '';
162
+ const { cp, findings } = r.value;
163
+ await emitEvent(projectRoot, 'CONTEXT_PRESSURE_DETECTED', { missionId: mid, trigger: String(payload?.trigger || 'pre-compact').slice(0, 20) });
164
+ await emitEvent(projectRoot, 'CHECKPOINT_SAVED', { missionId: mid, seq: cp.seq });
165
+ await emitEvent(projectRoot, 'COMPACT_STARTED', { missionId: mid, trigger: String(payload?.trigger || '').slice(0, 20) });
166
+ const warn = findings.filter((f) => f.severity === 'warn');
167
+ const note = `[mission ${mid}] checkpoint #${cp.seq} saved. In the summary keep: objective, active requirement ids (R-*), pending work separate from done, hypotheses marked unverified, owner STOP/blockers.${warn.length ? ` Drift: ${warn.slice(0, 3).map((f) => `${f.code} ${f.ref}`).join(', ')}.` : ''}`;
168
+ return redactText(note).text.slice(0, NOTE_CAP);
169
+ } catch { return ''; }
170
+ }
171
+
172
+ export async function sessionRestoreStep({ projectRoot, payload, rescue = '', config } = {}) {
173
+ try {
174
+ const rescueText = String(rescue || '');
175
+ let mission = '';
176
+ if (missionEnabled(config ?? readConfig(projectRoot))) {
177
+ const sessionKey = sessionKeyOf(payload);
178
+ const mid = existingMissionId(projectRoot, sessionKey);
179
+ if (mid) {
180
+ const git = gitInfo(projectRoot);
181
+ const r = await withMissionLock(projectRoot, mid, async () => {
182
+ const out = await renderRestore({ projectRoot, missionId: mid, sessionKey, git, maxChars: MISSION_RESTORE_CAP });
183
+ recordInjection(out.text.length, { projectRoot, missionId: mid, hash: out.hash, deduped: out.deduped });
184
+ return out;
185
+ }, { deadlineMs: 800 });
186
+ if (r.ok && r.value?.text) {
187
+ mission = r.value.text;
188
+ await emitEvent(projectRoot, 'SESSION_RESTORED', { missionId: mid, chars: mission.length, deduped: r.value.deduped === true });
189
+ }
190
+ }
191
+ }
192
+ if (!mission) return rescueText.slice(0, COMBINED_RESTORE_CAP);
193
+ // Rescue bundle repeats facts the mission restore already states: drop exact duplicate lines, then fit the rest.
194
+ const seen = new Set(mission.split('\n').map((l) => l.trim()).filter(Boolean));
195
+ const rescueUnique = rescueText.split('\n').filter((l) => !l.trim() || !seen.has(l.trim())).join('\n').replace(/\n{3,}/g, '\n\n').trim();
196
+ const room = COMBINED_RESTORE_CAP - mission.length - 1;
197
+ return (rescueUnique && room > 200 ? `${mission}\n${rescueUnique.slice(0, room)}` : mission).slice(0, COMBINED_RESTORE_CAP);
198
+ } catch { return String(rescue || '').slice(0, COMBINED_RESTORE_CAP); }
199
+ }
@@ -0,0 +1,68 @@
1
+ // Mission prompt journal, Level A (WP1). Contract, for other workers:
2
+ // recordPrompt({projectRoot, sessionKey, text, origin='user'|'system', engine, ownerStop, missionId?, ts?})
3
+ // -> Promise<{ok, prompt, missionId, eventOk}> never throws
4
+ // 1. redactText BEFORE anything is persisted; text capped at 32 KiB (truncated=true);
5
+ // textSha256 is the sha256 of the ORIGINAL text (pre-redaction, pre-cap) so duplicates are detectable
6
+ // without storing secrets.
7
+ // 2. lock-free fsync append to <mid>/journal*.jsonl (promptId claimed with O_EXCL) -- the prompt is on
8
+ // disk even if the lock is busy.
9
+ // 3. then a `prompt` event (under lock, spooled to pending.jsonl on timeout).
10
+ // The journal record is never rewritten; relation/extracted/links live in graph events (see graph.applyPrompt).
11
+ // System prompts (origin:'system') are journaled but callers must not classify them.
12
+ // getPrompt(projectRoot, missionId, promptId) -> record | null
13
+ // listPrompts(projectRoot, missionId, {from, to, origin}={}) -> record[] sorted by numeric prompt order
14
+ import crypto from 'node:crypto';
15
+ import path from 'node:path';
16
+ import { redactText } from './redact.mjs';
17
+ import {
18
+ appendEvent, appendJsonlSync, claimPromptId, ensureMission, missionDir, readJsonl, repairTornTail,
19
+ } from './store.mjs';
20
+
21
+ export const PROMPT_TEXT_CAP = 32 * 1024;
22
+
23
+ const num = (id) => Number(String(id).replace(/\D/g, '')) || 0;
24
+
25
+ export async function recordPrompt(input = {}) {
26
+ try {
27
+ const { projectRoot, sessionKey = 'default', origin = 'user', engine = null, ownerStop = false } = input;
28
+ const original = typeof input.text === 'string' ? input.text : '';
29
+ const mid = input.missionId || ensureMission({ projectRoot, sessionKey })?.missionId;
30
+ if (!mid) return { ok: false, reason: 'no-mission' };
31
+ const { text: redacted, redactions } = redactText(original);
32
+ const buf = Buffer.from(redacted, 'utf8');
33
+ const truncated = buf.length > PROMPT_TEXT_CAP;
34
+ let text = truncated ? buf.subarray(0, PROMPT_TEXT_CAP).toString('utf8').replace(/�+$/, '') : redacted;
35
+ const promptId = claimPromptId(projectRoot, mid);
36
+ const prompt = {
37
+ v: 1, promptId, missionId: mid, seq: num(promptId), ts: input.ts || Date.now(), sessionKey, engine,
38
+ text, textSha256: crypto.createHash('sha256').update(original).digest('hex'), truncated, redactions,
39
+ origin: origin === 'system' ? 'system' : 'user', ownerStop: Boolean(ownerStop),
40
+ };
41
+ const base = path.join(missionDir(projectRoot, mid), 'journal');
42
+ repairTornTail(base);
43
+ if (!appendJsonlSync(base, prompt)) return { ok: false, reason: 'write' };
44
+ const ev = await appendEvent(projectRoot, mid, {
45
+ kind: 'prompt', dedupeKey: promptId, sessionKey, engine, ref: { promptId },
46
+ data: { origin: prompt.origin, textSha256: prompt.textSha256 },
47
+ });
48
+ return { ok: true, prompt, missionId: mid, eventOk: Boolean(ev.ok) };
49
+ } catch (e) { return { ok: false, reason: 'error', error: String(e?.message || e) }; }
50
+ }
51
+
52
+ function all(projectRoot, mid) {
53
+ const seen = new Set();
54
+ return readJsonl(path.join(missionDir(projectRoot, mid), 'journal'))
55
+ .filter((p) => p && p.promptId && !seen.has(p.promptId) && seen.add(p.promptId))
56
+ .sort((a, b) => num(a.promptId) - num(b.promptId));
57
+ }
58
+
59
+ export function getPrompt(projectRoot, missionId, promptId) {
60
+ try { return all(projectRoot, missionId).find((p) => p.promptId === promptId) || null; } catch { return null; }
61
+ }
62
+
63
+ export function listPrompts(projectRoot, missionId, { from, to, origin } = {}) {
64
+ try {
65
+ return all(projectRoot, missionId).filter((p) => (from == null || num(p.promptId) >= num(from))
66
+ && (to == null || num(p.promptId) <= num(to)) && (!origin || p.origin === origin));
67
+ } catch { return []; }
68
+ }
@@ -0,0 +1,64 @@
1
+ // Mission metrics (WP3). Advisory only: nothing here triggers compaction.
2
+ // pressureBand(tokens, window) -> {pct, band, advisory:true} band: normal(<30) consolidate(30-40) prefer-compact(40-50)
3
+ // strong-prefer(50-60) native-fallback(>60); 'unknown' on bad input. Policy bands, not hard thresholds.
4
+ // recordCompaction({projectRoot, missionId, ts?}) -> {ok} stores toolCallsSince previous compaction
5
+ // noteToolCall({projectRoot, missionId}) -> {ok} counter only (no transcript scans)
6
+ // recordInjection(size, {projectRoot, missionId, hash?, deduped?, ts?}) -> {ok}
7
+ // thrash({projectRoot, missionId, now?}) -> boolean >=3 compactions in 10 min OR <5 tool calls between the last two
8
+ // repeatedInjection({projectRoot, missionId}) -> {repeated, count, bytes} same non-deduped hash injected consecutively
9
+ // readMetrics(projectRoot, missionId) -> {compactions[], toolCalls, injections[]}
10
+ import path from 'node:path';
11
+ import { missionDir, readJsonFile, writeJsonAtomicFile } from './store.mjs';
12
+
13
+ export const THRASH_WINDOW_MS = 10 * 60 * 1000;
14
+ export const THRASH_COMPACTIONS = 3;
15
+ export const THRASH_MIN_TOOL_CALLS = 5;
16
+
17
+ export function pressureBand(tokens, window) {
18
+ const t = Number(tokens); const w = Number(window);
19
+ if (!Number.isFinite(t) || !Number.isFinite(w) || w <= 0 || t < 0) return { pct: null, band: 'unknown', advisory: true };
20
+ const pct = Math.round((t / w) * 1000) / 10;
21
+ const band = pct < 30 ? 'normal' : pct < 40 ? 'consolidate' : pct < 50 ? 'prefer-compact' : pct <= 60 ? 'strong-prefer' : 'native-fallback';
22
+ return { pct, band, advisory: true };
23
+ }
24
+
25
+ const file = (projectRoot, mid) => path.join(missionDir(projectRoot, mid), 'metrics.json');
26
+ export function readMetrics(projectRoot, missionId) {
27
+ const m = readJsonFile(file(projectRoot, missionId), null) || {};
28
+ return { compactions: m.compactions || [], toolCalls: m.toolCalls || 0, injections: m.injections || [] };
29
+ }
30
+ function update({ projectRoot, missionId }, fn) {
31
+ try { const m = readMetrics(projectRoot, missionId); fn(m); writeJsonAtomicFile(file(projectRoot, missionId), m); return { ok: true }; } catch { return { ok: false }; }
32
+ }
33
+
34
+ export function noteToolCall(ctx = {}) { return update(ctx, (m) => { m.toolCalls += 1; }); }
35
+ export function recordCompaction(ctx = {}) {
36
+ return update(ctx, (m) => {
37
+ m.compactions.push({ ts: ctx.ts || Date.now(), toolCallsSince: m.toolCalls });
38
+ m.compactions = m.compactions.slice(-50);
39
+ m.toolCalls = 0;
40
+ });
41
+ }
42
+ export function recordInjection(size, ctx = {}) {
43
+ return update(ctx, (m) => {
44
+ m.injections.push({ ts: ctx.ts || Date.now(), size: Number(size) || 0, hash: ctx.hash || null, deduped: Boolean(ctx.deduped) });
45
+ m.injections = m.injections.slice(-50);
46
+ });
47
+ }
48
+ export function thrash({ projectRoot, missionId, now = Date.now() } = {}) {
49
+ try {
50
+ const { compactions } = readMetrics(projectRoot, missionId);
51
+ if (compactions.filter((c) => now - c.ts <= THRASH_WINDOW_MS).length >= THRASH_COMPACTIONS) return true;
52
+ return compactions.length >= 2 && compactions[compactions.length - 1].toolCallsSince < THRASH_MIN_TOOL_CALLS;
53
+ } catch { return false; }
54
+ }
55
+ export function repeatedInjection({ projectRoot, missionId } = {}) {
56
+ try {
57
+ const inj = readMetrics(projectRoot, missionId).injections.filter((i) => !i.deduped && i.hash);
58
+ const last = inj[inj.length - 1];
59
+ if (!last) return { repeated: false, count: 0, bytes: 0 };
60
+ let count = 0;
61
+ for (let i = inj.length - 1; i >= 0 && inj[i].hash === last.hash; i -= 1) count += 1;
62
+ return { repeated: count >= 2, count, bytes: last.size * count };
63
+ } catch { return { repeated: false, count: 0, bytes: 0 }; }
64
+ }
@@ -0,0 +1,132 @@
1
+ // Mission recall, Level D (WP3). Progressive disclosure; all functions fail safe (never throw).
2
+ // buildIndex({projectRoot, missionId, graph?}) -> Promise<index> writes <mid>/terms.json (<= 512 KiB, shrinks snippets/terms to fit)
3
+ // indexes prompts, requirements, decisions, tasks and closed (archived/superseded) items. Never stores unredacted text:
4
+ // prompts come from the redacted journal.
5
+ // recall(q, {projectRoot, missionId, limit=8}) -> Promise<[{id, kind, snippet, score}]> step 1: compact index hits
6
+ // detail(id, {projectRoot, missionId}) -> Promise<object|null> step 2: requirement/task/AC/decision/prompt detail
7
+ // raw(promptId, {projectRoot, missionId}) -> string|null step 3: verbatim (redacted-at-capture) prompt text
8
+ // The index auto-rebuilds when the journal, graph revision or decision count changed since it was written.
9
+ import path from 'node:path';
10
+ import { foldText } from './classify.mjs';
11
+ import { loadGraph } from './graph.mjs';
12
+ import { getPrompt, listPrompts } from './journal.mjs';
13
+ import { missionDir, readJsonFile, readJsonl, writeJsonAtomicFile } from './store.mjs';
14
+ import { readMemoryItems } from './working.mjs';
15
+
16
+ export const MAX_TERMS_BYTES = 512 * 1024;
17
+
18
+ const STOPWORDS = new Set('the a an to of in on for and or with is are be it this that at by from as'.split(' '));
19
+ export function termsOf(text) {
20
+ return [...new Set(foldText(text).replace(/[^a-z0-9_]+/g, ' ').split(' ').filter((w) => w.length > 1 && !STOPWORDS.has(w)))];
21
+ }
22
+ const termsFile = (projectRoot, mid) => path.join(missionDir(projectRoot, mid), 'terms.json');
23
+ const num = (id) => Number(String(id).replace(/\D/g, '')) || 0;
24
+
25
+ async function collect(projectRoot, missionId, graph) {
26
+ const g = graph || await loadGraph({ projectRoot, missionId });
27
+ const docs = {};
28
+ const add = (id, kind, text, extra = {}) => { if (id && text && !docs[id]) docs[id] = { kind, text: String(text), ...extra }; };
29
+ const prompts = listPrompts(projectRoot, missionId);
30
+ for (const p of prompts) add(p.promptId, 'prompt', p.text, { origin: p.origin });
31
+ for (const r of Object.values(g.state.reqs)) add(r.id, 'requirement', r.text, { status: r.status, promptId: r.promptId });
32
+ for (const t of Object.values(g.state.tasks)) add(t.id, 'task', t.title, { status: t.status });
33
+ for (const e of readJsonl(path.join(missionDir(projectRoot, missionId), 'graph-archive'))) {
34
+ const it = e?.item;
35
+ if (!it?.id) continue;
36
+ if (e.kind === 'reqs') add(it.id, 'requirement', it.text, { status: it.status, promptId: it.promptId, closed: true });
37
+ else if (e.kind === 'tasks') add(it.id, 'task', it.title, { status: it.status, closed: true });
38
+ }
39
+ const items = readMemoryItems(projectRoot, missionId);
40
+ for (const d of items.decisions) add(d.id, 'decision', d.text, { status: d.status, promptId: d.promptId });
41
+ return { g, docs, key: { prompts: prompts.length, rev: g.state.rev, decisions: items.decisions.length, ids: Object.keys(docs).length } };
42
+ }
43
+
44
+ function serialize(docs, key, snipLen, termCap) {
45
+ const index = {};
46
+ const out = { v: 1, key, docs: {}, index };
47
+ for (const [id, d] of Object.entries(docs)) {
48
+ const snippet = d.text.replace(/\s+/g, ' ').slice(0, snipLen);
49
+ out.docs[id] = { kind: d.kind, snippet, ...(d.status ? { status: d.status } : {}) };
50
+ for (const t of termsOf(d.text).slice(0, termCap)) (index[t] || (index[t] = [])).push(id);
51
+ }
52
+ return out;
53
+ }
54
+
55
+ export async function buildIndex({ projectRoot, missionId, graph } = {}) {
56
+ try {
57
+ const { docs, key } = await collect(projectRoot, missionId, graph);
58
+ let out; let snip = 160; let cap = 60;
59
+ for (;;) {
60
+ out = serialize(docs, key, snip, cap);
61
+ if (Buffer.byteLength(JSON.stringify(out)) <= MAX_TERMS_BYTES || (snip <= 20 && cap <= 4)) break;
62
+ snip = Math.max(20, Math.floor(snip * 0.7)); cap = Math.max(4, Math.floor(cap * 0.7));
63
+ }
64
+ if (Buffer.byteLength(JSON.stringify(out)) > MAX_TERMS_BYTES) {
65
+ // last resort: drop the oldest non-prompt docs, never prompts
66
+ const ids = Object.keys(docs).filter((i) => docs[i].kind !== 'prompt').sort((a, b) => num(a) - num(b));
67
+ while (ids.length && Buffer.byteLength(JSON.stringify(out)) > MAX_TERMS_BYTES) {
68
+ for (let i = 0; i < Math.max(1, ids.length >> 2); i += 1) delete docs[ids.shift()];
69
+ out = serialize(docs, key, snip, cap);
70
+ }
71
+ }
72
+ writeJsonAtomicFile(termsFile(projectRoot, missionId), out);
73
+ return out;
74
+ } catch { return null; }
75
+ }
76
+
77
+ async function ensureIndex(projectRoot, missionId) {
78
+ const cur = readJsonFile(termsFile(projectRoot, missionId), null);
79
+ if (cur) {
80
+ const prompts = listPrompts(projectRoot, missionId).length;
81
+ const g = await loadGraph({ projectRoot, missionId });
82
+ const dec = readMemoryItems(projectRoot, missionId).decisions.length;
83
+ if (cur.key?.prompts === prompts && cur.key?.rev === g.state.rev && cur.key?.decisions === dec) return cur;
84
+ }
85
+ return buildIndex({ projectRoot, missionId });
86
+ }
87
+
88
+ export async function recall(q, { projectRoot, missionId, limit = 8 } = {}) {
89
+ try {
90
+ const idx = await ensureIndex(projectRoot, missionId);
91
+ const qt = termsOf(q);
92
+ if (!idx || !qt.length) return [];
93
+ const scores = new Map();
94
+ for (const t of qt) for (const id of idx.index[t] || []) scores.set(id, (scores.get(id) || 0) + 1);
95
+ return [...scores].map(([id, hits]) => {
96
+ const d = idx.docs[id];
97
+ return { id, kind: d.kind, snippet: d.snippet, score: Math.round((hits / qt.length) * 100) / 100 };
98
+ }).sort((a, b) => b.score - a.score || num(a.id) - num(b.id)).slice(0, Math.max(1, limit));
99
+ } catch { return []; }
100
+ }
101
+
102
+ export async function detail(id, { projectRoot, missionId } = {}) {
103
+ try {
104
+ const g = await loadGraph({ projectRoot, missionId });
105
+ const arch = readJsonl(path.join(missionDir(projectRoot, missionId), 'graph-archive')).map((e) => e.item).filter(Boolean);
106
+ const find = (kind, map) => map[id] || arch.find((i) => i.id === id && (kind === 'req' ? i.text : i.title));
107
+ if (/^P-/.test(id)) {
108
+ const p = getPrompt(projectRoot, missionId, id);
109
+ if (!p) return null;
110
+ const reqs = Object.values(g.state.reqs).filter((r) => r.promptId === id).map((r) => ({ id: r.id, text: r.text, status: r.status }));
111
+ return { id, kind: 'prompt', origin: p.origin, ts: p.ts, truncated: p.truncated, requirements: reqs, textPreview: p.text.slice(0, 400) };
112
+ }
113
+ if (/^R-/.test(id)) {
114
+ const r = find('req', g.state.reqs);
115
+ if (!r) return null;
116
+ const edges = g.edges().filter((e) => e.from === id || e.to === id).slice(0, 30);
117
+ return { ...r, kind: 'requirement', reqKind: r.kind, tasks: g.tasksForReq(id).map((t) => ({ id: t.id, status: t.status, title: t.title })), edges };
118
+ }
119
+ if (/^T-/.test(id)) {
120
+ const t = find('task', g.state.tasks);
121
+ if (!t) return null;
122
+ return { kind: 'task', ...t, acs: (t.acIds || []).map((a) => g.state.acs[a]).filter(Boolean), blocker: g.state.blockers[id] || null };
123
+ }
124
+ if (/^AC-/.test(id)) { const a = g.state.acs[id] || arch.find((i) => i.id === id); return a ? { kind: 'ac', ...a } : null; }
125
+ const d = readMemoryItems(projectRoot, missionId).decisions.find((x) => x.id === id);
126
+ return d ? { kind: 'decision', ...d } : null;
127
+ } catch { return null; }
128
+ }
129
+
130
+ export function raw(promptId, { projectRoot, missionId } = {}) {
131
+ try { return getPrompt(projectRoot, missionId, promptId)?.text ?? null; } catch { return null; }
132
+ }
@@ -0,0 +1,25 @@
1
+ // Mission redaction. Contract:
2
+ // redactText(text) -> { text, redactions: [{label, count}] } (never throws; non-string -> '')
3
+ // Secret patterns come from sensitive-value-scanner.mjs (TOKEN_PATTERNS) plus a generic
4
+ // `password|secret|token|api_key = value` assignment rule. Values are replaced with
5
+ // `[REDACTED:<label>]`; the redactions list holds labels and counts only, never values.
6
+ import { TOKEN_PATTERNS } from '../sensitive-value-scanner.mjs';
7
+
8
+ const ASSIGN_RE = /\b((?:pass(?:word|wd)?|secret|api[_-]?key|access[_-]?token|auth[_-]?token|token)\s*[:=]\s*)(["']?)([^\s"']{6,})\2/gi;
9
+
10
+ export function redactText(text) {
11
+ try {
12
+ if (typeof text !== 'string' || !text) return { text: '', redactions: [] };
13
+ let out = text;
14
+ const counts = new Map();
15
+ const bump = (label) => counts.set(label, (counts.get(label) || 0) + 1);
16
+ for (const { label, re } of TOKEN_PATTERNS) {
17
+ const rx = new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`);
18
+ out = out.replace(rx, () => { bump(label); return `[REDACTED:${label}]`; });
19
+ }
20
+ out = out.replace(ASSIGN_RE, (_m, pre) => { bump('credential assignment'); return `${pre}[REDACTED:credential assignment]`; });
21
+ return { text: out, redactions: [...counts].map(([label, count]) => ({ label, count })) };
22
+ } catch {
23
+ return { text: '[REDACTION-FAILED]', redactions: [{ label: 'redaction-error', count: 1 }] };
24
+ }
25
+ }
@@ -0,0 +1,107 @@
1
+ // Mission restoration renderer (WP3). Contract:
2
+ // renderRestore({projectRoot, missionId, sessionKey, git:{head,branch,dirty,remoteHash,repoRoot}, maxChars=6000, now?})
3
+ // -> Promise<{text, hash, deduped, mismatches[]}>
4
+ // Authoritative state (graph + journal + decision events) is read live; the latest checkpoint is used only for the HEAD
5
+ // comparison and the objective. Order: identity -> owner STOP/blockers -> active task + AC -> active reqs (<=12, with
6
+ // prompt ids) -> decisions -> pending/failures -> labelled hypotheses/assumptions -> next action -> recall pointers.
7
+ // Identity mismatch -> text starts with `RECONCILE BEFORE MUTATING: ...`.
8
+ // Same hash as active.json sessions[sessionKey].lastInjectHash -> one-line pointer, deduped:true.
9
+ // Hard cap maxChars (tail is cut first, so the highest-priority sections survive). No secrets: journal text is pre-redacted
10
+ // and every rendered line is redacted again.
11
+ import crypto from 'node:crypto';
12
+ import fs from 'node:fs';
13
+ import path from 'node:path';
14
+ import { loadGraph } from './graph.mjs';
15
+ import { listPrompts } from './journal.mjs';
16
+ import { latestCheckpoint, buildBuckets } from './checkpoint.mjs';
17
+ import { redactText } from './redact.mjs';
18
+ import { missionRoot, readActive, writeJsonAtomicFile } from './store.mjs';
19
+ import { activeTaskOf, buildWorkingMemory, readMemoryItems } from './working.mjs';
20
+
21
+ const clip = (s, n) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t; };
22
+ const short = (h) => String(h || '').slice(0, 7);
23
+
24
+ function identityMismatches({ active, missionId, sessionKey, git, cp, projectRoot }) {
25
+ const out = [];
26
+ if (active.activeMissionId && active.activeMissionId !== missionId) out.push(`mission differs (active ${active.activeMissionId}, restoring ${missionId})`);
27
+ const sess = active.sessions?.[sessionKey];
28
+ if (sess?.missionId && sess.missionId !== missionId) out.push(`session ${sessionKey} is bound to ${sess.missionId}`);
29
+ const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(String(p)); } };
30
+ const repo = git.repoRoot || null;
31
+ if (active.repoRoot && repo && real(active.repoRoot) !== real(repo)) out.push('repository root differs from mission repository');
32
+ else if (active.repoRoot && !repo && projectRoot && real(active.repoRoot) !== real(projectRoot)) out.push('project root differs from mission repository');
33
+ if (active.remoteHash && git.remoteHash && active.remoteHash !== git.remoteHash) out.push('git remote differs from mission remote');
34
+ if (cp?.git?.branch && git.branch && cp.git.branch !== git.branch) out.push(`branch changed (${cp.git.branch} -> ${git.branch})`);
35
+ if (cp?.git?.head && git.head && cp.git.head !== git.head) out.push(`HEAD moved since checkpoint (${short(cp.git.head)} -> ${short(git.head)})`);
36
+ return out;
37
+ }
38
+
39
+ export async function renderRestore({ projectRoot, missionId, sessionKey = 'default', git = {}, maxChars = 6000 } = {}) {
40
+ try {
41
+ const g = await loadGraph({ projectRoot, missionId });
42
+ const active = readActive(projectRoot);
43
+ const cp = latestCheckpoint(projectRoot, missionId);
44
+ const prompts = listPrompts(projectRoot, missionId);
45
+ const items = readMemoryItems(projectRoot, missionId);
46
+ const b = buildBuckets(g, items, prompts);
47
+ const working = await buildWorkingMemory({ projectRoot, missionId, graph: g });
48
+ const mism = identityMismatches({ active, missionId, sessionKey, git: git || {}, cp, projectRoot });
49
+ const L = [];
50
+ if (mism.length) L.push(`RECONCILE BEFORE MUTATING: ${mism.join('; ')}. Re-verify state (git status, task ownership) before any write.`);
51
+ L.push(`[mission ${missionId}] objective ${b.objective.promptId || '?'}: ${clip(b.objective.text, 240)}`);
52
+ L.push(`repo ${git.branch || cp?.git?.branch || '?'}@${short(git.head || cp?.git?.head) || '?'}${git.dirty ? ' dirty' : ''} | checkpoint ${cp ? `#${cp.seq} (${cp.trigger})` : 'none'} | graph rev ${g.state.rev}`);
53
+
54
+ const lastUser = [...prompts].reverse().find((p) => p.origin === 'user');
55
+ if (lastUser?.ownerStop || b.stop.blockers.length) {
56
+ L.push('OWNER STOP / BLOCKERS (context refresh does not re-authorize):');
57
+ if (lastUser?.ownerStop) L.push(`- owner STOP in ${lastUser.promptId}: wait for a new owner prompt`);
58
+ for (const bl of b.stop.blockers.slice(0, 8)) L.push(`- ${bl.taskId} blocked [${bl.code}]: ${clip(bl.reason, 120)}`);
59
+ }
60
+
61
+ const task = activeTaskOf(g);
62
+ if (task) {
63
+ L.push(`ACTIVE TASK ${task.id} [${task.status}]: ${clip(task.title, 160)}${task.paths?.length ? ` (paths: ${task.paths.slice(0, 5).join(', ')})` : ''}`);
64
+ for (const ac of working?.ac || []) L.push(`- ${ac.id} ${ac.status}: ${clip(ac.text, 140)}`);
65
+ }
66
+
67
+ const reqs = b.activeReqIds.slice(0, 12).map((id) => g.state.reqs[id]).filter(Boolean);
68
+ if (reqs.length) {
69
+ L.push(`ACTIVE REQUIREMENTS (${b.activeReqIds.length}${b.activeReqIds.length > 12 ? ', showing 12' : ''}):`);
70
+ for (const r of reqs) L.push(`- ${r.id} (${r.promptId}) [${r.status}] ${clip(r.text, 140)}`);
71
+ }
72
+ const sup = Object.values(g.state.reqs).filter((r) => r.status === 'superseded').slice(0, 5);
73
+ for (const r of sup) L.push(`- ${r.id} superseded by ${r.supersededBy} (history kept)`);
74
+
75
+ if (items.decisions.length) {
76
+ L.push('DECISIONS:');
77
+ for (const d of items.decisions.slice(-8)) L.push(`- ${d.id} [${d.status || 'accepted'}] ${clip(d.text, 140)}`);
78
+ }
79
+ const pend = b.pending.filter((t) => t.id !== task?.id).slice(0, 10);
80
+ if (pend.length || b.failures.length) {
81
+ L.push(`PENDING (${b.pending.length} open tasks)${b.failures.length ? ' / FAILURES' : ''}:`);
82
+ for (const t of pend) L.push(`- ${t.id} ${t.status}: ${clip(t.title, 100)}`);
83
+ if (b.pending.length > pend.length + (task ? 1 : 0)) L.push(`- +${b.pending.length - pend.length - (task ? 1 : 0)} more (use recall)`);
84
+ for (const f of b.failures.slice(-5)) L.push(`- FAILURE ${f.id}: ${clip(f.text, 120)}`);
85
+ }
86
+ for (const h of b.hypotheses.slice(-5)) L.push(`HYPOTHESIS (unverified) ${h.id}: ${clip(h.text, 140)}`);
87
+ for (const a of b.assumptions.slice(-5)) L.push(`ASSUMPTION (needs validation) ${a.id}: ${clip(a.text, 140)}`);
88
+ L.push(`NEXT: ${clip(working?.nextAction, 200)}`);
89
+ L.push(`Recall: ukit mission recall "<query>" | detail <R-/T-/D- id> | raw <P- id> (earliest prompt ${prompts[0]?.promptId || 'P-1'} stays recoverable)`);
90
+
91
+ let text = redactText(L.join('\n')).text;
92
+ if (text.length > maxChars) text = `${text.slice(0, Math.max(0, maxChars - 1))}…`;
93
+ const hash = crypto.createHash('sha256').update(text).digest('hex').slice(0, 16);
94
+ const sess = active.sessions?.[sessionKey];
95
+ if (sess?.lastInjectHash === hash) {
96
+ return { text: `[mission ${missionId}] context unchanged since last restore (${hash}); recall: ukit mission recall "<query>"`, hash, deduped: true, mismatches: mism };
97
+ }
98
+ try {
99
+ active.sessions = active.sessions || {};
100
+ active.sessions[sessionKey] = { ...(sess || { missionId }), lastInjectHash: hash, lastInjectAt: Date.now() };
101
+ writeJsonAtomicFile(path.join(missionRoot(projectRoot), 'active.json'), active);
102
+ } catch { /* dedupe is best effort */ }
103
+ return { text, hash, deduped: false, mismatches: mism };
104
+ } catch (e) {
105
+ return { text: `[mission ${missionId}] restore unavailable (${String(e?.message || e).slice(0, 80)}); read .ukit/storage/mission`, hash: null, deduped: false, mismatches: [] };
106
+ }
107
+ }