@ngockhoale/ukit 3.4.85 → 3.5.2

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 (34) hide show
  1. package/CHANGELOG.md +33 -1064
  2. package/bin/ukit +9 -0
  3. package/manifests/documentation.yaml +12 -0
  4. package/manifests/platform.full.yaml +23 -0
  5. package/package.json +1 -1
  6. package/src/cli/commands/install.js +12 -0
  7. package/src/cli/commands/memory.js +30 -3
  8. package/src/core/memory/episodeArchive.js +147 -0
  9. package/src/core/memory/episodes.js +199 -37
  10. package/src/core/memory/memoryHit.js +59 -40
  11. package/src/core/memory/mutateMemory.js +23 -3
  12. package/src/core/memory/recallEngine.js +423 -0
  13. package/src/core/memory/retrieval.js +55 -92
  14. package/src/core/observability/emit/lifecycle.js +30 -0
  15. package/src/core/runtimeConfig.js +7 -0
  16. package/src/index/buildIndex.js +22 -0
  17. package/src/index/impactContext.js +11 -1
  18. package/template_project/.claude/hooks/edit-hint.mjs +119 -0
  19. package/template_project/.claude/hooks/skill-router.sh +82 -51
  20. package/template_project/.claude/settings.json +2 -2
  21. package/template_project/.claude/ukit/index/edit-graph.mjs +274 -0
  22. package/template_project/.claude/ukit/index/lib/index-core.mjs +36 -1
  23. package/template_project/.claude/ukit/index/post-edit-verify.mjs +8 -5
  24. package/template_project/.claude/ukit/index/resolve-context.mjs +17 -0
  25. package/template_project/.claude/ukit/index/route-task.mjs +29 -48
  26. package/template_project/.claude/ukit/runtime/execution-ledger.mjs +45 -0
  27. package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs +62 -5
  28. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +237 -0
  29. package/template_project/.claude/ukit/runtime/memory-recall.mjs +423 -0
  30. package/template_project/.claude/ukit/runtime/reinject-context.mjs +29 -45
  31. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  32. package/template_project/AGENTS.md +1 -1
  33. package/template_project/CLAUDE.md +1 -1
  34. package/template_project/instructions/core.md +1 -1
package/bin/ukit CHANGED
@@ -44,6 +44,15 @@ async function main() {
44
44
  packageVersion,
45
45
  });
46
46
  } finally {
47
+ // emit() only queues in memory; a short-lived CLI never runs
48
+ // startLifecycle, so drain queued telemetry here. Bounded (2s) and
49
+ // never throws; the watchdog above is still armed while it runs.
50
+ try {
51
+ const { flushAllRecorders } = await import('../src/core/observability/emit/lifecycle.js');
52
+ await flushAllRecorders({ deadlineMs: 2000 });
53
+ } catch {
54
+ // telemetry must never change the CLI exit status
55
+ }
47
56
  clearTimeout(watchdog);
48
57
  }
49
58
  }
@@ -1234,6 +1234,18 @@ entries:
1234
1234
  archive_policy: never
1235
1235
  notes: C100 native CI matrix design (macOS/Windows/Linux); maintainer-only, not shipped to user projects
1236
1236
 
1237
+ - id: docs-design-memory-io-inventory
1238
+ path: docs/design/memory-io-inventory.md
1239
+ class: canonical
1240
+ audience: [maintainer]
1241
+ owner: runtime
1242
+ source_of_truth: docs/design/memory-io-inventory.md
1243
+ merge_strategy: none
1244
+ load_policy: on-demand
1245
+ validation: [test:tests/docs/memoryInventory.test.js]
1246
+ archive_policy: never
1247
+ notes: live reader/writer inventory of src/core/memory modules (pinned by tests/docs/memoryInventory.test.js); maintainer-only, not shipped to user projects
1248
+
1237
1249
  - id: docs-release-multi-engine-release-gate
1238
1250
  path: docs/release/MULTI-ENGINE-RELEASE-GATE.md
1239
1251
  class: canonical
@@ -1322,6 +1322,19 @@ items:
1322
1322
  packs:
1323
1323
  - core
1324
1324
 
1325
+ # 3.5.2 WP-C: advisory PostToolUse Edit|Write module step (edit-graph hint).
1326
+ - id: hook-edit-hint-module
1327
+ type: hook
1328
+ sourceTemplate: .claude/hooks/edit-hint.mjs
1329
+ targetPath: .claude/hooks/edit-hint.mjs
1330
+ requires:
1331
+ - ukit-runtime-scripts
1332
+ mergeStrategy: overwrite_with_backup
1333
+ variables: []
1334
+ enabledByDefault: true
1335
+ packs:
1336
+ - core
1337
+
1325
1338
  - id: hook-completion-gate
1326
1339
  type: hook
1327
1340
  sourceTemplate: .claude/hooks/completion-gate.sh
@@ -1862,6 +1875,16 @@ items:
1862
1875
  packs:
1863
1876
  - core
1864
1877
 
1878
+ - id: ukit-index-edit-graph-script
1879
+ type: config
1880
+ sourceTemplate: .claude/ukit/index/edit-graph.mjs
1881
+ targetPath: .claude/ukit/index/edit-graph.mjs
1882
+ mergeStrategy: overwrite_with_backup
1883
+ variables: []
1884
+ enabledByDefault: true
1885
+ packs:
1886
+ - core
1887
+
1865
1888
  - id: ukit-index-route-catalog-script
1866
1889
  type: config
1867
1890
  sourceTemplate: .claude/ukit/index/route-catalog.mjs
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ngockhoale/ukit",
3
- "version": "3.4.85",
3
+ "version": "3.5.2",
4
4
  "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -6,6 +6,7 @@ import { resolveDecisionApiKey, resolveDecisionBaseUrl } from '../../core/gatewa
6
6
  import { buildCodeIndex, buildDerivedIndexArtifacts } from '../../index/buildIndex.js';
7
7
  import { installIndexRefreshHooks } from '../../index/gitHooks.js';
8
8
  import fs from 'node:fs/promises';
9
+ import { archiveLegacyEpisodes } from '../../core/memory/episodeArchive.js';
9
10
  import { pathExists, removeFileOrLinkOnly } from '../../core/fileOps.js';
10
11
  import { readInstallMetadata, removeTrackedPathsFromMetadata } from '../../core/metadata.js';
11
12
  import { provisionSupportDir } from '../../core/observability/support/provision.js';
@@ -446,6 +447,17 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
446
447
  );
447
448
  }
448
449
 
450
+ // 3.5.1: archive pre-existing content-free episodes (backup first, never
451
+ // deleted, idempotent). Advisory — never fails install; not run from hooks.
452
+ try {
453
+ const archived = await archiveLegacyEpisodes(projectRoot);
454
+ if (archived.archived > 0) {
455
+ console.log(`[UKit] Memory: archived ${archived.archived} content-free episode(s) -> ${path.relative(projectRoot, archived.archivePath)} (backup: ${archived.backupDir})`);
456
+ }
457
+ } catch (error) {
458
+ console.log(`[UKit] Memory episode archive skipped: ${error?.message ?? String(error)}`);
459
+ }
460
+
449
461
  console.log('[UKit] Install completed.');
450
462
  console.log('[UKit] Team rule: remember only `ukit install`.');
451
463
  console.log(
@@ -29,7 +29,8 @@ import { buildRuntimePaths } from '../../core/runtimePaths.js';
29
29
  import { buildUserPaths } from '../../core/userPaths.js';
30
30
  import { pathExists } from '../../core/fileOps.js';
31
31
  import { detectProjectContext } from '../../context/detectProjectContext.js';
32
- import { episodeText, resolveLedger, writeEpisode } from '../../core/memory/episodes.js';
32
+ import { episodeText, readRouteState, resolveLedger, writeEpisode } from '../../core/memory/episodes.js';
33
+ import { archiveLegacyEpisodes, purgeArchivedEpisode, restoreArchivedEpisodes } from '../../core/memory/episodeArchive.js';
33
34
  import fs from 'node:fs/promises';
34
35
  import os from 'node:os';
35
36
  import path from 'node:path';
@@ -561,11 +562,17 @@ async function runMemoryEpisode(projectRoot, homeDir, args) {
561
562
 
562
563
  if (dryRun) {
563
564
  const sessionId = ledger.sessionId ?? ledger.sessionKey ?? ledgerKey.replace(/\.json$/, '');
564
- console.log(`[UKit] episode (dry-run): ${episodeText(ledger, sessionId)}`);
565
+ const routeState = await readRouteState(projectRoot, ledger.sessionKey ?? sessionId);
566
+ const text = episodeText(ledger, sessionId, { routeState, projectRoot });
567
+ console.log(text ? `[UKit] episode (dry-run): ${text}` : '[UKit] episode (dry-run): no successful write — nothing to record');
565
568
  return;
566
569
  }
567
570
 
568
571
  const res = await writeEpisode(projectRoot, { ledger, ledgerKey, config, homeDir });
572
+ if (res.status === 'empty') {
573
+ console.log('[UKit] episode: no successful write — nothing to record');
574
+ return;
575
+ }
569
576
  if (res.status === 'duplicate') {
570
577
  console.log('[UKit] episode: already recorded');
571
578
  return;
@@ -929,6 +936,17 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
929
936
  return;
930
937
  }
931
938
 
939
+ if (subcommand === 'archive-episodes') {
940
+ if (rest.includes('--restore')) {
941
+ const r = await restoreArchivedEpisodes(projectRoot, { homeDir });
942
+ console.log(`[UKit] archive-episodes --restore: status=${r.status} restored=${r.restored} archived-file=${r.archived}`);
943
+ return;
944
+ }
945
+ const r = await archiveLegacyEpisodes(projectRoot, { dryRun: rest.includes('--dry-run'), homeDir });
946
+ console.log(`[UKit] archive-episodes: status=${r.status} archived=${r.archived} remaining=${r.remaining}${r.backupDir ? ` backup=${r.backupDir}` : ''}${r.reason ? ` reason=${r.reason}` : ''}`);
947
+ return;
948
+ }
949
+
932
950
  if (subcommand === 'forget') {
933
951
  const memoryId = rest.join(' ').trim();
934
952
  if (!memoryId) {
@@ -955,6 +973,14 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
955
973
  { kind: 'project', projectRoot, homeDir },
956
974
  { op: 'purge', payload: { id: memoryId } },
957
975
  );
976
+ // An archived episode is not in the live store; its copy must go too. A
977
+ // refused purge (disabled lane, corrupt store) leaves the archive alone.
978
+ const purgedFromArchive = (res.status === 'ok' || res.status === 'not-found')
979
+ && await purgeArchivedEpisode(projectRoot, memoryId);
980
+ if (res.status === 'not-found' && purgedFromArchive) {
981
+ console.log(`[UKit] Purged ${memoryId} from the episode archive.`);
982
+ return;
983
+ }
958
984
  const handled = handleMutationResult(res, {
959
985
  notFoundMessage: `Memory record not found: ${memoryId}`,
960
986
  });
@@ -981,7 +1007,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
981
1007
 
982
1008
  export function printMemoryHelp() {
983
1009
  console.log('UKit Memory Commands');
984
- console.log('Usage: ukit memory <list|search|expand|recall|forget|purge|export|propose|approve|reject|learn|promote|episode|hygiene|backup|restore|doctor> [args]');
1010
+ console.log('Usage: ukit memory <list|search|expand|recall|forget|purge|export|propose|approve|reject|learn|promote|episode|archive-episodes|hygiene|backup|restore|doctor> [args]');
985
1011
  console.log('');
986
1012
  console.log('Subcommands:');
987
1013
  console.log(' list List memory items in shared .ukit/storage/memory');
@@ -998,6 +1024,7 @@ export function printMemoryHelp() {
998
1024
  console.log(' learn [--apply] [--min <n>] [--project <id>] Propose pending candidates from mined failure patterns (dry-run by default)');
999
1025
  console.log(' promote [--dry-run] Render approved rules/procedures into the ## ukit-learned block in docs/MEMORY.md');
1000
1026
  console.log(' episode [--dry-run] [--session <id>] Write a session episode record from the exec-ledger');
1027
+ console.log(' archive-episodes [--dry-run|--restore] Move content-free legacy episodes to episodes-archive.json (backup first; --restore re-adds them)');
1001
1028
  console.log(' hygiene [--project <id>] Run decision-conflict resolution + session archiving now');
1002
1029
  console.log(' backup [--out <dir>] [--user] Snapshot v2 store(s) + sha256 manifest into a backup dir');
1003
1030
  console.log(' restore <dir> [--dry-run] [--user] Restore store(s) from a backup dir (plan only with --dry-run)');
@@ -0,0 +1,147 @@
1
+ // episodeArchive.js — move pre-3.5.1 content-free episodes out of the live
2
+ // store into <memoryV2Dir>/episodes-archive.json (never deleted).
3
+ //
4
+ // Detection is by the old template shape (LEGACY_EPISODE_TEXT_RE on
5
+ // type 'episode'), never by age. Run explicitly from `ukit install` and
6
+ // `ukit memory archive-episodes` — never from a hook.
7
+ //
8
+ // Invariants (blueprint ukit-memory PLAN §M02):
9
+ // - one backup (storeBackup.createBackup) before the first live-store write;
10
+ // - the removal goes through mutateMemory op 'relocate' (the single guarded
11
+ // write entry), under the store's file lock, so the generation bumps
12
+ // exactly once and tombstones are carried over untouched (no tombstone is
13
+ // added: an archived stub stays restorable);
14
+ // - the archive file is written (merged by id) BEFORE the live store drops
15
+ // the records, so a crash between the two leaves a superset, and a rerun
16
+ // simply finishes the removal;
17
+ // - second run finds no template-shaped episode left → no write, no backup.
18
+ // Restore goes through mutateMemory op 'restore': redaction, fingerprint
19
+ // dedupe and tombstone precedence apply, and purged ids never come back.
20
+
21
+ import fs from 'node:fs/promises';
22
+ import path from 'node:path';
23
+
24
+ import { readJsonIfExists, writeJson } from '../fileOps.js';
25
+ import { buildRuntimePaths } from '../runtimePaths.js';
26
+ import { readRecordStore } from './recordStore.js';
27
+ import { mutateMemory } from './mutateMemory.js';
28
+ import { createBackup } from './storeBackup.js';
29
+ import { LEGACY_EPISODE_TEXT_RE } from './episodes.js';
30
+
31
+ export const ARCHIVE_FILE = 'episodes-archive.json';
32
+ const ARCHIVE_VERSION = 1;
33
+
34
+ export function isLegacyEpisodeStub(record) {
35
+ return Boolean(record) && record.type === 'episode'
36
+ && typeof record.text === 'string' && LEGACY_EPISODE_TEXT_RE.test(record.text);
37
+ }
38
+
39
+ function archivePathFor(projectRoot) {
40
+ return path.join(buildRuntimePaths(projectRoot).memoryV2Dir, ARCHIVE_FILE);
41
+ }
42
+
43
+ async function readArchive(archivePath) {
44
+ const doc = await readJsonIfExists(archivePath).catch(() => null);
45
+ return Array.isArray(doc?.records) ? doc.records : [];
46
+ }
47
+
48
+ /**
49
+ * archiveLegacyEpisodes(projectRoot, {dryRun}) →
50
+ * {status:'ok'|'noop'|'dry-run'|'skipped', archived, remaining, backupDir?, archivePath?, reason?}
51
+ */
52
+ export async function archiveLegacyEpisodes(projectRoot, { dryRun = false, homeDir } = {}) {
53
+ const paths = buildRuntimePaths(projectRoot);
54
+ const recordsPath = paths.memoryV2RecordsPath;
55
+ const archivePath = archivePathFor(projectRoot);
56
+
57
+ const snapshot = await readRecordStore(recordsPath);
58
+ if (snapshot.state !== 'ok') {
59
+ return { status: 'skipped', archived: 0, remaining: snapshot.records.length, reason: `store-${snapshot.state}` };
60
+ }
61
+ const stubs = snapshot.records.filter(isLegacyEpisodeStub);
62
+ if (stubs.length === 0) {
63
+ return { status: 'noop', archived: 0, remaining: snapshot.records.length, archivePath };
64
+ }
65
+ if (dryRun) {
66
+ return { status: 'dry-run', archived: stubs.length, remaining: snapshot.records.length - stubs.length, archivePath };
67
+ }
68
+
69
+ // The backup is taken inside the sink: it only runs once the write lane has
70
+ // accepted the op and there are records to move, so a refused or empty run
71
+ // never creates one. The store file is not rewritten until the sink returns,
72
+ // so the backup still holds every record about to move; createBackup takes
73
+ // no store lock, so calling it under mutateMemory's lock cannot deadlock.
74
+ let backupDir;
75
+ const result = await mutateMemory(
76
+ { kind: 'project', projectRoot, homeDir },
77
+ { op: 'relocate', payload: { ids: stubs.map((r) => r.id) } },
78
+ {
79
+ sink: async (toArchive) => {
80
+ ({ backupDir } = await createBackup({ projectRoot }));
81
+ const existing = await readArchive(archivePath);
82
+ const ids = new Set(existing.map((r) => r?.id));
83
+ const merged = [...existing, ...toArchive.filter((r) => !ids.has(r.id))];
84
+ await writeJson(archivePath, {
85
+ version: ARCHIVE_VERSION,
86
+ updatedAt: new Date().toISOString(),
87
+ records: merged,
88
+ }, { fsync: true });
89
+ await fs.chmod(archivePath, 0o600).catch(() => {});
90
+ },
91
+ },
92
+ );
93
+ if (result.status !== 'ok' || !(result.relocated > 0)) {
94
+ // Nothing left the live store (writer stage off, memoryV2 disabled, or a
95
+ // concurrent run got there first); the sink never ran, so no backup exists.
96
+ if (result.status !== 'ok') {
97
+ return {
98
+ status: 'skipped', archived: 0, remaining: snapshot.records.length, reason: result.reason ?? result.status,
99
+ };
100
+ }
101
+ return { status: 'noop', archived: 0, remaining: result.remaining, archivePath };
102
+ }
103
+
104
+ return {
105
+ status: 'ok',
106
+ archived: result.relocated,
107
+ remaining: result.remaining,
108
+ backupDir,
109
+ archivePath,
110
+ };
111
+ }
112
+
113
+ /**
114
+ * purgeArchivedEpisode(projectRoot, id) → boolean (true when a copy was removed)
115
+ * `ukit memory purge <id>` must also remove the archived copy: an archived stub
116
+ * is no longer in the live store, so the store purge alone would leave its text
117
+ * on disk.
118
+ */
119
+ export async function purgeArchivedEpisode(projectRoot, id) {
120
+ const archivePath = archivePathFor(projectRoot);
121
+ const existing = await readArchive(archivePath);
122
+ const kept = existing.filter((r) => r?.id !== id);
123
+ if (kept.length === existing.length) return false;
124
+ await writeJson(archivePath, {
125
+ version: ARCHIVE_VERSION,
126
+ updatedAt: new Date().toISOString(),
127
+ records: kept,
128
+ }, { fsync: true });
129
+ await fs.chmod(archivePath, 0o600).catch(() => {});
130
+ return true;
131
+ }
132
+
133
+ /**
134
+ * restoreArchivedEpisodes(projectRoot, {homeDir}) → {status, restored, archived}
135
+ * Re-adds archived stubs via op 'restore' (dedupe + tombstone precedence).
136
+ * The archive file is kept; running the archive again moves them back out.
137
+ */
138
+ export async function restoreArchivedEpisodes(projectRoot, { homeDir } = {}) {
139
+ const archived = await readArchive(archivePathFor(projectRoot));
140
+ if (archived.length === 0) return { status: 'noop', restored: 0, archived: 0 };
141
+ const res = await mutateMemory(
142
+ { kind: 'project', projectRoot, homeDir },
143
+ { op: 'restore', payload: { records: archived } },
144
+ );
145
+ if (res.status !== 'ok') return { status: res.status, restored: 0, archived: archived.length, reason: res.reason };
146
+ return { status: 'ok', restored: res.added ?? 0, archived: archived.length };
147
+ }
@@ -14,6 +14,7 @@ import path from 'node:path';
14
14
 
15
15
  import { loadRecords } from './storeV2.js';
16
16
  import { mutateMemory } from './mutateMemory.js';
17
+ import { redactWritePayload } from './writeGuard.js';
17
18
  import { detectProjectContext } from '../../context/detectProjectContext.js';
18
19
  import { listLedgerFiles, LEDGER_DIR_REL } from '../../diagnostics/ledgerFiles.js';
19
20
 
@@ -49,19 +50,103 @@ export async function resolveLedger(projectRoot, sessionId) {
49
50
  return { ledger: await readJsonIfExists(path.join(dir, name)), ledgerKey: name };
50
51
  }
51
52
 
52
- export function episodeText(ledger, sessionId) {
53
- const write = ledger.writeSucceeded === true ? 'writeOk' : 'writeFail';
54
- const verify = ledger.verificationAttempted !== true
55
- ? 'not-run'
56
- : ledger.verificationSucceeded === true ? 'ok' : 'fail';
57
- const receipts = Array.isArray(ledger.receipts) ? ledger.receipts : [];
58
- const lastReceipt = receipts.length > 0 ? receipts[receipts.length - 1] : null;
59
- const lastCommand = lastReceipt
60
- ? String(lastReceipt?.command ?? '').split('\n')[0].trim() || 'n/a'
61
- : 'n/a';
62
- const text = `Session ${sessionId}: ${write}, verify=${verify}, `
63
- + `${receipts.length} receipts, last command ${lastCommand}`;
64
- return text.slice(0, 300);
53
+ // Template shape of the pre-3.5.1 content-free episode text. The archive
54
+ // migration (episodeArchive.js) detects stubs by this shape, not by age.
55
+ export const LEGACY_EPISODE_TEXT_RE = /^Session .+: (?:writeOk|writeFail), verify=(?:ok|fail|not-run), \d+ receipts, last command /;
56
+
57
+ const PROMPT_MAX = 240;
58
+ const FILES_MAX = 6;
59
+ const LINE_MAX = 160;
60
+
61
+ const oneLine = (value, max) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
62
+
63
+ export async function readRouteState(projectRoot, sessionKey) {
64
+ if (!sessionKey) return null;
65
+ return readJsonIfExists(path.join(
66
+ projectRoot, '.ukit', 'storage', 'cache', 'route-state', `${safeSegment(sessionKey)}.json`,
67
+ ));
68
+ }
69
+
70
+ // Project-relative path of a written file, or null when it falls outside the
71
+ // project (keeps home-directory paths out of the store).
72
+ function relativeWritten(projectRoot, file) {
73
+ if (typeof file !== 'string' || !file.trim()) return null;
74
+ const abs = path.isAbsolute(file) ? file : path.join(projectRoot, file);
75
+ const rel = path.relative(projectRoot, abs);
76
+ if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
77
+ return rel.split(path.sep).join('/');
78
+ }
79
+
80
+ // Strips a leading `cd <root>;|&&` and rewrites remaining occurrences of the
81
+ // absolute project root to `.`, so no machine path lands in the record.
82
+ export function normalizeCommand(command, projectRoot) {
83
+ let text = String(command ?? '').trim();
84
+ const root = projectRoot ? String(projectRoot).replace(/[\\/]+$/, '') : '';
85
+ if (root) {
86
+ const esc = root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
87
+ text = text.replace(new RegExp(`^cd\\s+(?:"${esc}"|'${esc}'|${esc})\\s*(?:;|&&)\\s*`), '');
88
+ text = text.split(root).join('.');
89
+ }
90
+ return text;
91
+ }
92
+
93
+ /**
94
+ * buildEpisode(ledger, {routeState, projectRoot}) → {text, files, verify,
95
+ * command, unfinished, hasTask} | null. Null = no successful write → no
96
+ * episode. The task text is bounded data from the explicit user prompt,
97
+ * attached only when route-state and ledger agree on taskInstanceId.
98
+ * Transcript content is never read.
99
+ */
100
+ export function buildEpisode(ledger, { routeState = null, projectRoot = '' } = {}) {
101
+ if (!ledger || typeof ledger !== 'object') return null;
102
+ const receipts = (Array.isArray(ledger.receipts) ? ledger.receipts : []).filter((r) => r && typeof r === 'object');
103
+ const writes = receipts.filter((r) => r.kind === 'write' && r.success === true);
104
+ if (ledger.writeSucceeded !== true && writes.length === 0) return null;
105
+
106
+ const files = [];
107
+ for (const r of writes) {
108
+ const rel = relativeWritten(projectRoot, r.file);
109
+ if (rel && !files.includes(rel)) files.push(rel);
110
+ }
111
+ const verifications = receipts.filter((r) => r.kind === 'verification');
112
+ const lastVerification = verifications.length > 0 ? verifications[verifications.length - 1] : null;
113
+ const command = oneLine(normalizeCommand(lastVerification?.command, projectRoot), LINE_MAX) || null;
114
+ let verify = 'not-run';
115
+ if (ledger.verificationAttempted === true || lastVerification) {
116
+ verify = ledger.verificationSucceeded === true ? 'ok' : 'fail';
117
+ }
118
+ const unfinished = [];
119
+ if (verify === 'not-run') unfinished.push('edits written but not verified');
120
+ if (verify === 'fail') unfinished.push('last verification failed');
121
+ if (ledger.blocker) {
122
+ const b = typeof ledger.blocker === 'string' ? ledger.blocker : (ledger.blocker.reason ?? ledger.blocker.code);
123
+ unfinished.push(`blocker: ${oneLine(b, 80) || 'recorded'}`);
124
+ }
125
+
126
+ // A prompt captured on the task itself (ledger.taskPrompt, set when the task's ledger
127
+ // was created) is authoritative. Route-state only holds the LATEST prompt, so it is a
128
+ // fallback that must prove the same taskInstanceId on both sides.
129
+ const provenMatch = routeState && ledger.taskInstanceId && routeState.taskInstanceId
130
+ && routeState.taskInstanceId === ledger.taskInstanceId;
131
+ const legacyMatch = routeState && !ledger.taskInstanceId && !routeState.taskInstanceId;
132
+ const task = oneLine(
133
+ ledger.taskPrompt
134
+ ?? (provenMatch || legacyMatch ? routeState?.routingContext?.lastExplicitUserPromptText : ''),
135
+ PROMPT_MAX,
136
+ );
137
+
138
+ const parts = [];
139
+ if (task) parts.push(`Task: ${task}`);
140
+ const shown = files.slice(0, FILES_MAX);
141
+ parts.push(`Wrote: ${shown.length > 0 ? shown.join(', ') : `${writes.length} file(s)`}${files.length > FILES_MAX ? ` (+${files.length - FILES_MAX} more)` : ''}`);
142
+ parts.push(`Verify: ${verify}${command ? ` via ${command}` : ''}`);
143
+ if (unfinished.length > 0) parts.push(`Unfinished: ${unfinished.join('; ')}`);
144
+ return { text: parts.join('. ').slice(0, 900), files, verify, command, unfinished, hasTask: Boolean(task) };
145
+ }
146
+
147
+ export function episodeText(ledger, sessionId, opts = {}) {
148
+ void sessionId;
149
+ return buildEpisode(ledger, opts)?.text ?? null;
65
150
  }
66
151
 
67
152
  function ledgerSessionId(ledger, ledgerKey) {
@@ -69,12 +154,53 @@ function ledgerSessionId(ledger, ledgerKey) {
69
154
  ?? (ledgerKey ? ledgerKey.replace(/\.json$/, '') : 'unknown');
70
155
  }
71
156
 
72
- // Writes one episode for `ledger`. Returns
157
+ // Dedupe identity of one task's episode: session ledger key + taskInstanceId
158
+ // (the session key alone when the ledger has no task id).
159
+ export function taskKeyOf(ledgerKey, taskInstanceId) {
160
+ return taskInstanceId ? `${ledgerKey}#${taskInstanceId}` : ledgerKey;
161
+ }
162
+
163
+ // Keys already recorded. Legacy records (ledgerKey only, no task id) keep the
164
+ // bare ledgerKey so they still dedupe a task-less ledger.
165
+ export function recordedEpisodeKeys(records) {
166
+ const keys = new Set();
167
+ for (const r of records) {
168
+ const m = r?.meta;
169
+ if (!m) continue;
170
+ if (m.taskKey) keys.add(m.taskKey);
171
+ else if (m.ledgerKey) keys.add(taskKeyOf(m.ledgerKey, m.taskInstanceId));
172
+ }
173
+ return keys;
174
+ }
175
+
176
+ export const SPOOL_SUFFIX = '.episodes';
177
+
178
+ async function readSpool(projectRoot, ledgerKey) {
179
+ const list = await readJsonIfExists(path.join(projectRoot, LEDGER_DIR_REL, `${ledgerKey}${SPOOL_SUFFIX}`));
180
+ return Array.isArray(list) ? list.filter((e) => e && typeof e === 'object' && e.taskInstanceId) : [];
181
+ }
182
+
183
+ // Writes the episodes for one ledger file: one per spooled outgoing task, then the
184
+ // ledger's current task. Returns the status of the CURRENT task's episode
73
185
  // { status: 'recorded', id, sessionId } | { status: 'duplicate' }
74
- // | { status: 'rejected', result } | { status: 'failed', reason }.
75
- // `existingKeys` (Set of ledgerKeys already recorded) skips the store read
76
- // when the caller batches.
77
- export async function writeEpisode(projectRoot, {
186
+ // | { status: 'empty' } (no successful write → no episode)
187
+ // | { status: 'rejected', result } | { status: 'failed', reason }
188
+ // plus `spooled` = number of spooled tasks newly recorded.
189
+ // `existingKeys` (Set from recordedEpisodeKeys) skips the store read when batching.
190
+ export async function writeEpisode(projectRoot, opts = {}) {
191
+ const { ledger, ledgerKey, existingKeys } = opts;
192
+ const keys = existingKeys ?? recordedEpisodeKeys(await loadRecords(projectRoot, { homeDir: opts.homeDir }));
193
+ let spooled = 0;
194
+ for (const entry of await readSpool(projectRoot, ledgerKey)) {
195
+ if (entry.taskInstanceId === ledger?.taskInstanceId) continue;
196
+ const res = await writeTaskEpisode(projectRoot, { ...opts, ledger: entry, existingKeys: keys });
197
+ if (res.status === 'recorded') spooled += 1;
198
+ }
199
+ const res = await writeTaskEpisode(projectRoot, { ...opts, existingKeys: keys });
200
+ return { ...res, spooled };
201
+ }
202
+
203
+ async function writeTaskEpisode(projectRoot, {
78
204
  ledger,
79
205
  ledgerKey,
80
206
  config,
@@ -83,11 +209,31 @@ export async function writeEpisode(projectRoot, {
83
209
  existingKeys,
84
210
  } = {}) {
85
211
  const sessionId = ledgerSessionId(ledger, ledgerKey);
86
- const keys = existingKeys ?? new Set(
87
- (await loadRecords(projectRoot, { homeDir })).map((r) => r.meta?.ledgerKey).filter(Boolean),
88
- );
89
- if (keys.has(ledgerKey)) return { status: 'duplicate' };
212
+ const taskKey = taskKeyOf(ledgerKey, ledger?.taskInstanceId);
213
+ const keys = existingKeys;
214
+ if (keys.has(taskKey)) return { status: 'duplicate' };
90
215
 
216
+ // A spool entry carries its own prompt; only the live ledger falls back to route-state.
217
+ const routeState = ledger?.taskPrompt !== undefined
218
+ ? null
219
+ : await readRouteState(projectRoot, ledger?.sessionKey ?? ledger?.sessionId ?? sessionId);
220
+ const built = buildEpisode(ledger, { routeState, projectRoot });
221
+ if (!built) return { status: 'empty' };
222
+ const observedAt = Date.now();
223
+ const ev = (kind, locator) => ({
224
+ kind, locator: String(locator).slice(0, 512), observed_at: observedAt, fingerprint: null, trust_tier: 'verified',
225
+ });
226
+ // Prompt text can carry pasted secrets: redact with the shared write guard
227
+ // before the add (mutateMemory's reject-mode guard then sees clean text).
228
+ const { payload: guarded } = redactWritePayload({
229
+ text: built.text,
230
+ evidence: [
231
+ ...built.files.slice(0, 6).map((f) => ev('file', f)),
232
+ ...(built.command ? [ev('command', built.command)] : []),
233
+ ev('ledger', ledgerKey),
234
+ ],
235
+ meta: { sessionId, ledgerKey, taskKey, taskInstanceId: ledger.taskInstanceId ?? null, verify: built.verify },
236
+ }, { config });
91
237
  const ttlDays = Number(config?.memoryV2?.episodeTtlDays) || 90;
92
238
  const resolvedProjectId = projectId
93
239
  ?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
@@ -97,17 +243,18 @@ export async function writeEpisode(projectRoot, {
97
243
  { kind: 'project', projectRoot, homeDir },
98
244
  {
99
245
  op: 'add',
100
- idempotencyKey: ledgerKey,
246
+ idempotencyKey: taskKey,
101
247
  payload: {
102
248
  type: 'episode',
103
249
  scope: 'session',
104
- text: episodeText(ledger, sessionId),
250
+ text: guarded.text,
251
+ evidence: guarded.evidence,
105
252
  provenance: 'exec-ledger',
106
253
  confidence: 0.6,
107
254
  createdBy: 'episode-hook',
108
255
  projectId: resolvedProjectId,
109
256
  validUntil: Date.now() + ttlDays * DAY_MS,
110
- meta: { sessionId, ledgerKey },
257
+ meta: guarded.meta,
111
258
  },
112
259
  },
113
260
  );
@@ -116,7 +263,7 @@ export async function writeEpisode(projectRoot, {
116
263
  if (res.status !== 'ok') {
117
264
  return { status: 'failed', reason: `${res.status}${res.reason ? ` — ${res.reason}` : ''}` };
118
265
  }
119
- keys.add(ledgerKey);
266
+ keys.add(taskKey);
120
267
  return { status: 'recorded', id: res.record.id, sessionId };
121
268
  }
122
269
 
@@ -137,30 +284,45 @@ export async function backfillEpisodes(projectRoot, {
137
284
  }
138
285
  const dir = path.join(projectRoot, LEDGER_DIR_REL);
139
286
  const names = await listLedgerFiles(dir, limit);
140
- if (names.length === 0) return summary;
141
- const existingKeys = new Set(
142
- (await loadRecords(projectRoot, { homeDir })).map((r) => r.meta?.ledgerKey).filter(Boolean),
143
- );
287
+ const existingKeys = recordedEpisodeKeys(await loadRecords(projectRoot, { homeDir }));
144
288
  const projectId = (await detectProjectContext(projectRoot, { homeDir })).project.name;
145
289
  for (const name of names) {
146
290
  summary.scanned += 1;
147
- if (existingKeys.has(name)) { summary.skipped += 1; continue; }
148
291
  let stat;
149
292
  try { stat = await fs.stat(path.join(dir, name)); } catch { summary.skipped += 1; continue; }
150
293
  if (now - stat.mtimeMs < idleMs) { summary.skipped += 1; continue; }
151
294
  const ledger = await readJsonIfExists(path.join(dir, name));
152
- const receipts = Array.isArray(ledger?.receipts) ? ledger.receipts.length : 0;
153
- if (!ledger || (receipts === 0 && ledger.writeSucceeded !== true)) {
154
- summary.skipped += 1;
155
- continue;
156
- }
295
+ if (!ledger) { summary.skipped += 1; continue; }
157
296
  const res = await writeEpisode(projectRoot, {
158
297
  ledger, ledgerKey: name, config, homeDir, projectId, existingKeys,
159
298
  });
299
+ summary.recorded += res.spooled ?? 0;
160
300
  if (res.status === 'recorded') summary.recorded += 1;
161
- else if (res.status === 'duplicate') summary.skipped += 1;
301
+ else if (res.status === 'duplicate' || res.status === 'empty') summary.skipped += 1;
162
302
  else summary.failed += 1;
163
303
  }
304
+ // Orphan spools: the ledger file was evicted by the dir sweep but its spool
305
+ // survived. Same dedupe keys, same idle rule (on the spool's mtime).
306
+ let dirNames = [];
307
+ try { dirNames = await fs.readdir(dir); } catch { /* none */ }
308
+ const present = new Set(dirNames);
309
+ for (const spoolName of dirNames) {
310
+ if (!spoolName.endsWith(`.json${SPOOL_SUFFIX}`)) continue;
311
+ const ledgerKey = spoolName.slice(0, -SPOOL_SUFFIX.length);
312
+ if (present.has(ledgerKey)) continue;
313
+ summary.scanned += 1;
314
+ let stat;
315
+ try { stat = await fs.stat(path.join(dir, spoolName)); } catch { summary.skipped += 1; continue; }
316
+ if (now - stat.mtimeMs < idleMs) { summary.skipped += 1; continue; }
317
+ for (const entry of await readSpool(projectRoot, ledgerKey)) {
318
+ const res = await writeTaskEpisode(projectRoot, {
319
+ ledger: entry, ledgerKey, config, homeDir, projectId, existingKeys,
320
+ });
321
+ if (res.status === 'recorded') summary.recorded += 1;
322
+ else if (res.status === 'duplicate' || res.status === 'empty') summary.skipped += 1;
323
+ else summary.failed += 1;
324
+ }
325
+ }
164
326
  } catch (error) {
165
327
  return { ...summary, reason: error?.message ?? String(error) };
166
328
  }