@ngockhoale/ukit 3.5.3 → 3.5.4

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 (59) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/manifests/documentation.yaml +12 -1
  3. package/manifests/platform.full.yaml +12 -0
  4. package/package.json +27 -1
  5. package/src/cli/commands/doctor.js +41 -0
  6. package/src/cli/commands/indexTools.js +10 -4
  7. package/src/cli/commands/memory.js +77 -6
  8. package/src/core/memory/episodes.js +106 -7
  9. package/src/core/memory/memoryCheck.js +241 -0
  10. package/src/core/memory/memoryCheckRun.js +27 -0
  11. package/src/core/memory/mutateMemory.js +37 -1
  12. package/src/core/memory/observations.js +192 -0
  13. package/src/core/memory/recallEngine.js +120 -7
  14. package/src/core/memory/records.js +23 -0
  15. package/src/core/memory/writeGate.js +137 -0
  16. package/src/core/runtimeConfig.js +11 -1
  17. package/src/index/buildIndex.js +26 -0
  18. package/src/index/paths.js +3 -1
  19. package/src/index/queryIndex.js +225 -10
  20. package/src/index/resolveContext.js +1 -1
  21. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  22. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  23. package/template_project/.claude/hooks/session-episode.sh +9 -4
  24. package/template_project/.claude/settings.json +2 -2
  25. package/template_project/.claude/ukit/index/lib/index-core.mjs +255 -12
  26. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  27. package/template_project/.claude/ukit/index/route-task.mjs +4 -1
  28. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  29. package/template_project/.claude/ukit/runtime/memory-recall.mjs +120 -7
  30. package/template_project/.claude/ukit/runtime/memory-validity.mjs +28 -1
  31. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  32. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  33. package/template_project/ukit/storage/config.json +4 -2
  34. package/src/core/agentRuntime/completionGate.js +0 -179
  35. package/src/core/agentRuntime/context.js +0 -571
  36. package/src/core/agentRuntime/qualityComparison.js +0 -112
  37. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  38. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  39. package/src/core/codeintel/manifest.js +0 -176
  40. package/src/core/experiments/deliberation.js +0 -327
  41. package/src/core/experiments/dynamicWorkflow.js +0 -507
  42. package/src/core/handoffDocValidator.js +0 -154
  43. package/src/core/memory/deltaOverlays.js +0 -493
  44. package/src/core/memory/learningCandidates.js +0 -347
  45. package/src/core/observability/emit/sessionBoot.js +0 -407
  46. package/src/core/observability/evaluation/replay.js +0 -149
  47. package/src/core/observability/evaluation/scorecard.js +0 -465
  48. package/src/core/observability/schema/compatibility.js +0 -180
  49. package/src/core/observability/support/renderer.js +0 -130
  50. package/src/core/reviewPanelAggregate.js +0 -204
  51. package/src/core/taskBudgetValidator.js +0 -251
  52. package/src/core/taskProgressGuard.js +0 -227
  53. package/src/decision/reviewVerdict.js +0 -339
  54. package/src/decision/runtimeFilter.js +0 -150
  55. package/src/decision/runtimeScheduler.js +0 -239
  56. package/src/index/contextPack.js +0 -285
  57. package/src/index/impactContext.js +0 -360
  58. package/src/index/reviewPolicy.js +0 -368
  59. package/src/index/sensitivePath.js +0 -21
@@ -53,7 +53,8 @@ function safeSchemaArtifact(artifact) {
53
53
  return normalized.schemaVersion === INDEX_SCHEMA_VERSION ? normalized : { items: [] };
54
54
  }
55
55
 
56
- export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5 } = {}) {
56
+ // contentLane=false skips the error-string content search (context-resolution paths never pay for it).
57
+ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5, contentLane = true } = {}) {
57
58
  const normalizedQuery = String(query ?? '').trim();
58
59
  if (!normalizedQuery) {
59
60
  return [];
@@ -73,6 +74,7 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
73
74
  rootDir: absoluteRoot,
74
75
  query: normalizedQuery,
75
76
  limit,
77
+ contentLane,
76
78
  });
77
79
  if (QUERY_RESULT_CACHE.has(queryCacheKey)) {
78
80
  return QUERY_RESULT_CACHE.get(queryCacheKey);
@@ -107,8 +109,51 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
107
109
  }
108
110
  }
109
111
 
112
+ // Content lane: a message-like query with no confident symbol/path hit also searches
113
+ // file contents through the existing bounded fallback search. It only adds a bounded
114
+ // bonus, so it can never displace a confident hit (those skip the lane entirely).
115
+ let bestDirect = 0;
116
+ let contentLaneRan = false;
117
+ let contentCutShort = [];
118
+ for (const entry of directScores.values()) {
119
+ bestDirect = Math.max(bestDirect, entry.score);
120
+ }
121
+ if (contentLane && bestDirect < CONTENT_LANE_CONFIDENT_SCORE && queryDescriptor.tokens.size >= CONTENT_LANE_MIN_TOKENS && looksLikeLiteralMessage(normalizedQuery)) {
122
+ contentLaneRan = true;
123
+ // A literal message sits on one source line: every query token must share the matched
124
+ // line, otherwise this is a scattered token hit, not the message. The scan order and the
125
+ // count/byte caps are functions of the index and file contents only (never of load or of
126
+ // ripgrep being installed); wall-clock is a safety cap that reports 'time-budget'.
127
+ const messageTokens = [...new Set(normalizeIdentifierTokens(queryDescriptor.rawLower))];
128
+ let lineHits = [];
129
+ try {
130
+ const ordered = rankContentLaneFiles({
131
+ files, searchDescriptorsByFile, tokenWeights, queryTokens: queryDescriptor.tokens, includeLikelyTestFiles,
132
+ });
133
+ const scan = await scanContentLane({ absoluteRoot, ordered, tokens: messageTokens, limit: CONTENT_LANE_LIMIT });
134
+ lineHits = scan.hits;
135
+ contentCutShort = scan.truncated;
136
+ } catch {
137
+ contentCutShort = ['error'];
138
+ }
139
+ lineHits.forEach((row, index) => {
140
+ const existing = directScores.get(row.filePath);
141
+ const reason = `content_match:${row.filePath}${row.line ? `:${row.line}` : ''}`;
142
+ if (existing) {
143
+ existing.score += CONTENT_LANE_BONUS;
144
+ existing.reasons = dedupe([...(existing.reasons ?? []), reason]);
145
+ } else {
146
+ directScores.set(row.filePath, {
147
+ filePath: row.filePath,
148
+ score: CONTENT_LANE_ONLY_SCORE - index * 0.1,
149
+ reasons: [reason],
150
+ });
151
+ }
152
+ });
153
+ }
154
+
110
155
  if (directScores.size === 0) {
111
- return Object.freeze([]);
156
+ return withContentLaneStatus(Object.freeze([]), contentLaneRan, contentCutShort);
112
157
  }
113
158
 
114
159
  const {
@@ -151,12 +196,12 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
151
196
  }),
152
197
  });
153
198
 
154
- return freezeQueryResults(
199
+ return withContentLaneStatus(freezeQueryResults(
155
200
  [...finalScores.values()]
156
201
  .map((entry) => ({ ...entry, score: finalizeScore(entry) }))
157
202
  .sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath))
158
203
  .slice(0, limit),
159
- );
204
+ ), contentLaneRan, contentCutShort);
160
205
  })().catch((error) => {
161
206
  QUERY_RESULT_CACHE.delete(queryCacheKey);
162
207
  throw error;
@@ -185,7 +230,11 @@ function isFunctionLikeSignature(signature) {
185
230
  // Reads symbols.json through the existing readArtifact cache (no new file reads, no new
186
231
  // cache). Never throws: an absent file, a missing artifact, or a stale schema all resolve
187
232
  // to [] so callers can render an outline block unconditionally.
188
- export async function getFileOutline({ rootDir = process.cwd(), filePath, limit = 12 } = {}) {
233
+ const OUTLINE_WINDOW = 12; // matches OUTLINE_SYMBOLS_LIMIT in the CLI printers
234
+
235
+ // `focus`: symbol names the query matched (see queryMatchedSymbolNames); they are pinned into
236
+ // the first OUTLINE_WINDOW rows even when unexported, so the printed outline shows the hit.
237
+ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit = 12, focus = null } = {}) {
189
238
  if (!filePath) {
190
239
  return Object.freeze([]);
191
240
  }
@@ -211,9 +260,26 @@ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit
211
260
  seenNames.add(item.name);
212
261
  deduped.push(item);
213
262
  }
263
+ // The first OUTLINE_WINDOW rows (what the CLI prints) hold exported/top-level symbols
264
+ // first; unexported functions and class methods only take the remaining slots. Each
265
+ // part stays in line order, and rows beyond the window follow in line order.
266
+ const window = Number.isFinite(limit) ? limit : OUTLINE_WINDOW;
267
+ let kept = deduped;
268
+ if (deduped.length > window) {
269
+ const pinned = new Set(focus ?? []);
270
+ const isPinned = (item) => pinned.has(item.name);
271
+ const ranked = [
272
+ ...deduped.filter(isPinned),
273
+ ...deduped.filter((item) => !isPinned(item) && !isLocalOutlineRow(item)),
274
+ ...deduped.filter((item) => !isPinned(item) && isLocalOutlineRow(item)),
275
+ ];
276
+ const head = ranked.slice(0, window).sort((a, b) => a.line - b.line);
277
+ const inHead = new Set(head);
278
+ kept = [...head, ...deduped.filter((item) => !inHead.has(item))];
279
+ }
214
280
 
215
281
  return Object.freeze(
216
- deduped.slice(0, limit).map((item) => Object.freeze({
282
+ kept.slice(0, limit).map((item) => Object.freeze({
217
283
  line: item.line,
218
284
  name: item.name,
219
285
  type: item.type,
@@ -343,10 +409,22 @@ const PATH_EXACT_SCORE = 60;
343
409
  const PATH_SUFFIX_SCORE = 48;
344
410
  const PATH_BASENAME_SCORE = 40;
345
411
  const SYMBOL_EXACT_SCORE = 40;
412
+ const LOCAL_SYMBOL_FACTOR = 0.85; // unexported symbols (local function/class, method, unexported type) rank below an exported symbol of the same name
346
413
  const SYMBOL_DECAY = 0.35; // k-th best symbol of a file adds score * SYMBOL_DECAY^k
347
414
  const SYMBOL_REASON_LIMIT = 3;
348
415
  const MIN_SUBSTRING_TOKEN_LENGTH = 3;
349
416
  const BOOST_LIFT_RATIO = 0.2; // import/hotspot/archetype boosts may add at most this share of a direct score (+1)
417
+ const CONTENT_LANE_CONFIDENT_SCORE = 30; // a best direct score at/above this (exact symbol or path hit) skips the content lane
418
+ const CONTENT_LANE_MIN_TOKENS = 3; // shorter queries are names, not messages
419
+ const CONTENT_LANE_LIMIT = 40; // candidates only share tokens somewhere in the file; the same-line check below keeps the real ones
420
+ const CONTENT_LANE_CODE_EXT = /\.(?:m?js|cjs|jsx?|tsx?|vue|sql|sh)$/i; // docs/data files quote queries verbatim (baselines, logs); only source carries error strings
421
+ const CONTENT_LANE_BONUS = 14; // added to a file that already has a direct score
422
+ const CONTENT_LANE_ONLY_SCORE = 13; // base for a file found only by content; below CONTENT_LANE_CONFIDENT_SCORE by design
423
+ const CONTENT_LANE_MAX_FILES = 1500; // files read per query, in priority order (primary bound)
424
+ const CONTENT_LANE_MAX_BYTES = 24 * 1024 * 1024; // characters read per query (primary bound)
425
+ const CONTENT_LANE_MAX_FILE_BYTES = 512 * 1024; // larger files are generated/data, never scanned
426
+ const CONTENT_LANE_BATCH = 24;
427
+ const CONTENT_LANE_SAFETY_MS = 5000; // safety cap only: hitting it reports 'time-budget', normal runs never do
350
428
  const BOOST_ONLY_RATIO = 0.3; // files with no direct match stay below this share of the best direct score
351
429
 
352
430
  // Rarity weight per token in (0,1]: a token present in nearly every file is worth
@@ -377,10 +455,10 @@ function buildTokenWeights(searchDescriptorsByFile) {
377
455
  // hiding the mirror: root installed copies < template_project < everything else.
378
456
  function mirrorPrior(filePath) {
379
457
  if (/^\.(?:claude|codex|omp)\//.test(filePath)) {
380
- return 0.88;
458
+ return 0.8;
381
459
  }
382
460
  if (filePath.startsWith('template_project/')) {
383
- return 0.94;
461
+ return 0.85;
384
462
  }
385
463
  return 1;
386
464
  }
@@ -448,7 +526,7 @@ function scoreDirectFileMatch({ queryDescriptor, rawQuery = '', filePath, search
448
526
  queryDescriptor.compact.length >= 4
449
527
  && symbolDescriptor.descriptor.compact === queryDescriptor.compact
450
528
  ) {
451
- symbolHits.push({ score: SYMBOL_EXACT_SCORE, reasons: [`symbol_exact:${symbolDescriptor.name}`] });
529
+ symbolHits.push({ score: SYMBOL_EXACT_SCORE * (symbolDescriptor.local ? LOCAL_SYMBOL_FACTOR : 1), reasons: [`symbol_exact:${symbolDescriptor.name}`] });
452
530
  continue;
453
531
  }
454
532
 
@@ -488,7 +566,7 @@ function scoreDirectFileMatch({ queryDescriptor, rawQuery = '', filePath, search
488
566
  }
489
567
 
490
568
  if (symbolScore > 0) {
491
- symbolHits.push({ score: symbolScore, reasons: symbolReasons });
569
+ symbolHits.push({ score: symbolScore * (symbolDescriptor.local ? LOCAL_SYMBOL_FACTOR : 1), reasons: symbolReasons });
492
570
  }
493
571
  }
494
572
 
@@ -953,11 +1031,124 @@ function buildFileSearchDescriptors(files, symbolMap) {
953
1031
  return descriptors;
954
1032
  }
955
1033
 
1034
+ // Rows whose declaration is not exported. 'callable' keeps its pre-3.5.4 weight.
1035
+ // Outline-only: a 'callable' const without `export` is also unexported.
1036
+ function isLocalOutlineRow(item) {
1037
+ return isLocalSymbolRow(item) || (item?.type === 'callable' && !/^\s*export\b/.test(item?.signature ?? ''));
1038
+ }
1039
+
1040
+ function isLocalSymbolRow(symbol) {
1041
+ const type = symbol?.type;
1042
+ if (type === 'local-function' || type === 'local-class' || type === 'method') {
1043
+ return true;
1044
+ }
1045
+ return type === 'type' && !/^\s*export\b/.test(symbol?.signature ?? '');
1046
+ }
1047
+
1048
+ // Single identifiers, questions and non-ASCII (Vietnamese) prose are descriptions of behaviour, not strings
1049
+ // that appear in source, so they never pay for a content search.
1050
+ function looksLikeLiteralMessage(query) {
1051
+ return /^[\x20-\x7e]+$/.test(query)
1052
+ && query.split(/\s+/).length >= CONTENT_LANE_MIN_TOKENS // identifiers and short phrases are symbol queries, never a message
1053
+ && !/^(?:how|where|what|why|which|when|who|does|do|is|are|can|find|show|list)\b/i.test(query);
1054
+ }
1055
+
1056
+ // Stable verify order: index evidence first (rarity-weighted overlap of the query tokens with
1057
+ // each file's path and symbol tokens), originals before mirrors, then path order.
1058
+ function rankContentLaneFiles({ files, searchDescriptorsByFile, tokenWeights, queryTokens, includeLikelyTestFiles }) {
1059
+ const rows = [];
1060
+ for (const file of safeItems(files)) {
1061
+ const filePath = file?.filePath;
1062
+ if (typeof filePath !== 'string' || !CONTENT_LANE_CODE_EXT.test(filePath)) {
1063
+ continue;
1064
+ }
1065
+ if (isLikelyTestFilePath(filePath) && !includeLikelyTestFiles) {
1066
+ continue;
1067
+ }
1068
+ let overlap = 0;
1069
+ const descriptor = searchDescriptorsByFile.get(filePath);
1070
+ if (descriptor) {
1071
+ const seen = new Set(descriptor.path.tokens);
1072
+ for (const symbol of descriptor.symbols) {
1073
+ for (const token of symbol.descriptor.tokens) {
1074
+ seen.add(token);
1075
+ }
1076
+ }
1077
+ for (const token of queryTokens) {
1078
+ if (seen.has(token)) {
1079
+ overlap += tokenWeights?.get(token) ?? 1;
1080
+ }
1081
+ }
1082
+ }
1083
+ rows.push({ filePath, overlap, mirror: mirrorPrior(filePath) < 1 ? 1 : 0, size: Number.isFinite(Number(file.size)) && Number(file.size) >= 0 ? Number(file.size) : null });
1084
+ }
1085
+ rows.sort((a, b) => (b.overlap - a.overlap) || (a.mirror - b.mirror) || (a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0));
1086
+ return rows;
1087
+ }
1088
+
1089
+ // Reads files in priority order (batched for speed, consumed in order) until the hit limit or a
1090
+ // count/byte cap. Caps are checked at batch boundaries on counts and byte totals only, so the
1091
+ // same tree yields the same hits regardless of machine load.
1092
+ async function scanContentLane({ absoluteRoot, ordered, tokens, limit }) {
1093
+ const hits = [];
1094
+ const truncated = new Set();
1095
+ if (tokens.length === 0) {
1096
+ return { hits, truncated: [] };
1097
+ }
1098
+ let scanned = 0;
1099
+ let bytes = 0;
1100
+ const deadline = Date.now() + CONTENT_LANE_SAFETY_MS;
1101
+ for (let start = 0; start < ordered.length && hits.length < limit; start += CONTENT_LANE_BATCH) {
1102
+ if (scanned >= CONTENT_LANE_MAX_FILES) { truncated.add('max-files'); break; }
1103
+ if (bytes >= CONTENT_LANE_MAX_BYTES) { truncated.add('max-bytes'); break; }
1104
+ if (Date.now() > deadline) { truncated.add('time-budget'); break; }
1105
+ const batch = ordered.slice(start, start + Math.min(CONTENT_LANE_BATCH, CONTENT_LANE_MAX_FILES - scanned));
1106
+ // Size comes from the index entry, else a stat; an oversized file is skipped before any read.
1107
+ const texts = await Promise.all(batch.map(async (row) => {
1108
+ try {
1109
+ const absolute = path.join(absoluteRoot, row.filePath);
1110
+ const size = row.size ?? (await fs.stat(absolute)).size;
1111
+ if (size > CONTENT_LANE_MAX_FILE_BYTES) {
1112
+ return { text: '', size: 0 };
1113
+ }
1114
+ const text = await fs.readFile(absolute, 'utf8');
1115
+ return { text, size: Buffer.byteLength(text, 'utf8') };
1116
+ } catch {
1117
+ return { text: '', size: 0 };
1118
+ }
1119
+ }));
1120
+ for (const [index, { text, size }] of texts.entries()) {
1121
+ scanned += 1;
1122
+ bytes += size;
1123
+ if (text.length === 0 || size > CONTENT_LANE_MAX_FILE_BYTES) {
1124
+ continue;
1125
+ }
1126
+ const lower = text.toLowerCase();
1127
+ if (!tokens.every((token) => lower.includes(token))) {
1128
+ continue;
1129
+ }
1130
+ const lines = lower.split('\n');
1131
+ const lineIndex = lines.findIndex((line) => tokens.every((token) => line.includes(token)));
1132
+ if (lineIndex >= 0) {
1133
+ hits.push({ filePath: batch[index].filePath, line: lineIndex + 1 });
1134
+ if (hits.length >= limit) {
1135
+ break;
1136
+ }
1137
+ }
1138
+ }
1139
+ }
1140
+ if (scanned >= CONTENT_LANE_MAX_FILES && scanned < ordered.length && hits.length < limit) {
1141
+ truncated.add('max-files');
1142
+ }
1143
+ return { hits, truncated: [...truncated] };
1144
+ }
1145
+
956
1146
  function createFileSearchDescriptor({ filePath, symbols }) {
957
1147
  return {
958
1148
  path: buildTextSearchDescriptor(filePath),
959
1149
  symbols: symbols.map((symbol) => ({
960
1150
  name: symbol.name,
1151
+ local: isLocalSymbolRow(symbol),
961
1152
  descriptor: buildTextSearchDescriptor(symbol.name),
962
1153
  })),
963
1154
  };
@@ -1227,6 +1418,30 @@ export function clearIndexArtifactCache(rootDir = null) {
1227
1418
  }
1228
1419
  }
1229
1420
 
1421
+ // Names of the symbols a query result matched, parsed from its `symbol_exact:` /
1422
+ // `symbol_token:` reasons; feed to getFileOutline({ focus }).
1423
+ export function queryMatchedSymbolNames(result) {
1424
+ const names = [];
1425
+ for (const reason of result?.reasons ?? []) {
1426
+ const match = /^symbol_(?:exact|compact|contains):([^:]+)$/.exec(reason) ?? /^symbol_token:([^:]+):/.exec(reason);
1427
+ if (match) {
1428
+ names.push(match[1]);
1429
+ }
1430
+ }
1431
+ return names;
1432
+ }
1433
+
1434
+ // Non-enumerable (array equality and JSON stay unchanged), like boundedSourceSearch rows.truncated:
1435
+ // `contentLane` is true when the content search ran; `contentLaneTruncated` lists why it was cut
1436
+ // short ('verify-cap', 'time-budget', 'max-files', ...) so a partial scan never reads as "no match".
1437
+ function withContentLaneStatus(results, ran, truncated) {
1438
+ // results arrive frozen, so copy before attaching the status and freeze again.
1439
+ const out = [...results];
1440
+ Object.defineProperty(out, 'contentLane', { value: ran, enumerable: false });
1441
+ Object.defineProperty(out, 'contentLaneTruncated', { value: Object.freeze([...truncated]), enumerable: false });
1442
+ return Object.freeze(out);
1443
+ }
1444
+
1230
1445
  function freezeQueryResults(results) {
1231
1446
  return Object.freeze(
1232
1447
  results.map((item) => Object.freeze({
@@ -83,7 +83,7 @@ export async function resolveContext({
83
83
  }
84
84
 
85
85
  if (queryWasUsed) {
86
- const queryResults = await queryCodeIndex({ rootDir, query: intent, limit: budget.maxFiles });
86
+ const queryResults = await queryCodeIndex({ rootDir, query: intent, limit: budget.maxFiles, contentLane: false });
87
87
  for (const qr of queryResults) {
88
88
  addExplainedFile(result, 'primaryTargets', qr.filePath, buildQueryReason(qr));
89
89
  }
@@ -37,6 +37,34 @@ async function prune(dir, keep) {
37
37
  } catch { /* retention is best-effort */ }
38
38
  }
39
39
 
40
+ function emit(text, p, env) {
41
+ if (!text) return NONE;
42
+ const omp = p.ukit_harness === 'omp' || env.UKIT_HARNESS === 'omp';
43
+ const stdout = omp
44
+ ? `${text}\n`
45
+ : `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } })}\n`;
46
+ return { code: 0, stdout, stderr: '' };
47
+ }
48
+
49
+ // null: not a memory source (fall through to the graph hint); '' clean; else one advisory line.
50
+ async function memoryAdvisory(projectRoot, rel, config, signal) {
51
+ try {
52
+ const recall = await import('../ukit/runtime/memory-recall.mjs');
53
+ const entries = recall.normalizeMemorySources(config ?? {});
54
+ // Sync pre-check: no directory listing for edits that are not a memory source.
55
+ if (!recall.matchesMemorySource(entries, rel)) return null;
56
+ const sources = await recall.expandMemorySources(projectRoot, entries);
57
+ if (!sources.includes(rel)) return null;
58
+ const check = await import('../ukit/runtime/memory-check.mjs');
59
+ const res = await check.checkMemorySources(projectRoot, {
60
+ sources, engine: { tokenize: recall.tokenize, parseMarkdownBullets: recall.parseMarkdownBullets }, files: [rel],
61
+ });
62
+ return signal.aborted ? '' : check.formatCheckLine(res);
63
+ } catch {
64
+ return '';
65
+ }
66
+ }
67
+
40
68
  async function hint(ctx, signal, commit) {
41
69
  const { payload: p = {}, projectRoot, env = {} } = ctx;
42
70
  if (env.UKIT_EDIT_HINTS === '0' || process.env.UKIT_EDIT_HINTS === '0') return NONE;
@@ -55,9 +83,42 @@ async function hint(ctx, signal, commit) {
55
83
  const task = typeof route?.taskInstanceId === 'string' && route.taskInstanceId ? route.taskInstanceId : session;
56
84
  const stateFile = path.join(projectRoot, '.ukit/storage/cache/edit-hints', `${session}.${safe(p.agent_id, 'main')}.json`);
57
85
  const prev = await readJson(stateFile);
86
+ const strs = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
58
87
  const st = prev && prev.task === task && Array.isArray(prev.seen)
59
- ? { task, seen: prev.seen.filter((x) => typeof x === 'string'), shownMem: Array.isArray(prev.shownMem) ? prev.shownMem.filter((x) => typeof x === 'string') : [] }
60
- : { task, seen: [], shownMem: [] };
88
+ ? { task, seen: strs(prev.seen), shownMem: strs(prev.shownMem), advised: strs(prev.advised) }
89
+ : { task, seen: [], shownMem: [], advised: [] };
90
+ const persist = async () => {
91
+ st.seen = st.seen.slice(-MAX_SEEN);
92
+ st.shownMem = st.shownMem.slice(-MAX_SEEN);
93
+ st.advised = st.advised.slice(-MAX_SEEN);
94
+ let body = JSON.stringify(st);
95
+ while (body.length > MAX_BYTES && st.seen.length > 1) {
96
+ st.seen.shift();
97
+ st.shownMem.shift();
98
+ st.advised.shift();
99
+ body = JSON.stringify(st);
100
+ }
101
+ try {
102
+ await fsp.mkdir(path.dirname(stateFile), { recursive: true });
103
+ const tmp = `${stateFile}.${process.pid}.tmp`;
104
+ await fsp.writeFile(tmp, body);
105
+ await fsp.rename(tmp, stateFile);
106
+ } catch { /* state is best-effort */ }
107
+ void prune(path.dirname(stateFile), path.basename(stateFile));
108
+ };
109
+ // 3.5.4: an edited memory source gets the checker's advisory line instead of a graph hint,
110
+ // once per task per finding (the line names file:line and the code), so a project that
111
+ // stays over the cap is not nagged on every edit.
112
+ if (/^docs\/.+\.md$/i.test(rel)) {
113
+ const advisory = await memoryAdvisory(projectRoot, rel, config, signal);
114
+ if (advisory !== null) {
115
+ if (!advisory || st.advised.includes(advisory) || signal.aborted) return NONE;
116
+ commit.on = true;
117
+ st.advised.push(advisory);
118
+ await persist();
119
+ return emit(advisory, p, env);
120
+ }
121
+ }
61
122
  if (st.seen.includes(rel)) return NONE;
62
123
 
63
124
  const lanes = await import('../ukit/runtime/memory-lanes.mjs');
@@ -74,21 +135,7 @@ async function hint(ctx, signal, commit) {
74
135
  commit.on = true;
75
136
  st.seen.push(rel);
76
137
  st.shownMem.push(...(out?.memoryIds || []));
77
- st.seen = st.seen.slice(-MAX_SEEN);
78
- st.shownMem = st.shownMem.slice(-MAX_SEEN);
79
- let body = JSON.stringify(st);
80
- while (body.length > MAX_BYTES && st.seen.length > 1) {
81
- st.seen.shift();
82
- st.shownMem.shift();
83
- body = JSON.stringify(st);
84
- }
85
- try {
86
- await fsp.mkdir(path.dirname(stateFile), { recursive: true });
87
- const tmp = `${stateFile}.${process.pid}.tmp`;
88
- await fsp.writeFile(tmp, body);
89
- await fsp.rename(tmp, stateFile);
90
- } catch { /* state is best-effort */ }
91
- void prune(path.dirname(stateFile), path.basename(stateFile));
138
+ await persist();
92
139
 
93
140
  const text = typeof out?.text === 'string' ? out.text.trim() : '';
94
141
  if (!text) return NONE;
@@ -0,0 +1,35 @@
1
+ // session-episode-start.mjs - SessionStart in-proc chain step (3.5.4).
2
+ //
3
+ // Episodes must not depend on SessionEnd alone: a long-lived session (or a crash) never
4
+ // reaches it. On every SessionStart source (startup, resume, clear, compact) this step
5
+ // launches ONE detached, throttled worker that records the finished tasks of earlier
6
+ // ledgers and of the still-open session (`ukit memory episode --start`) - same
7
+ // writeEpisode/backfill code and dedupe keys as SessionEnd, so a later SessionEnd is a
8
+ // no-op for what is already written.
9
+ //
10
+ // Advisory end-to-end: always { code: 0 }, no output, async fs only, bounded by the chain
11
+ // deadline. The CLI resolution (and the stale-CLI refusal) happens inside the detached
12
+ // worker, never here.
13
+
14
+ import { fileURLToPath, pathToFileURL } from 'node:url';
15
+ import path from 'node:path';
16
+
17
+ const OK = { code: 0, stdout: '', stderr: '' };
18
+
19
+ export async function runHook(ctx = {}) {
20
+ try {
21
+ const payload = ctx && typeof ctx.payload === 'object' && ctx.payload ? ctx.payload : {};
22
+ const root = typeof ctx.projectRoot === 'string' && ctx.projectRoot
23
+ ? ctx.projectRoot
24
+ : (typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.env.CLAUDE_PROJECT_DIR);
25
+ if (!root) return OK;
26
+ const here = path.dirname(fileURLToPath(import.meta.url));
27
+ const trigger = await import(pathToFileURL(path.join(here, '..', 'ukit', 'runtime', 'self-improve-trigger.mjs')).href);
28
+ const budget = Number(ctx.deadlineMs) > 0 ? Number(ctx.deadlineMs) : 2000;
29
+ await Promise.race([
30
+ trigger.triggerEpisodeStart({ projectRoot: root }),
31
+ new Promise((resolve) => { setTimeout(resolve, Math.max(100, budget - 200)).unref?.(); }),
32
+ ]);
33
+ } catch { /* advisory */ }
34
+ return OK;
35
+ }
@@ -161,16 +161,21 @@ function runBounded(cmd, args, { timeout, cwd, env, shell } = {}) {
161
161
  try {
162
162
  trigger = await import(require("url").pathToFileURL(process.argv[4]).href);
163
163
  } catch {}
164
- const located = trigger?.resolveCliLocator?.(projectRoot) ?? null;
165
- const cli = located
166
- ? { cmd: located.node, pre: [located.bin], shell: false }
164
+ // 3.5.4: one shared resolver. cli.json wins; a PATH `ukit` older than the project
165
+ // runtime is refused (it writes the wrong record shape) and the reason is left in
166
+ // .ukit/storage/learning/episode-cli.json for `ukit doctor`. The PATH version probe is
167
+ // cached by binary path + mtime and async, inside this armed step.
168
+ const cli = trigger?.resolveEpisodeCli
169
+ ? await trigger.resolveEpisodeCli(projectRoot)
167
170
  : { cmd: "ukit", pre: [], shell: true };
171
+ if (cli.reason) return;
168
172
 
169
- const probe = await runBounded(cli.cmd, [...cli.pre, "--version"], { timeout: 2000 });
173
+ const probe = await runBounded(cli.cmd, [...cli.pre, "--version"], { timeout: 2000, shell: cli.shell });
170
174
  if (!probe.ok) return;
171
175
 
172
176
  await runBounded(cli.cmd, [...cli.pre, "memory", "episode"], {
173
177
  timeout: 4000,
178
+ shell: cli.shell,
174
179
  cwd: projectRoot,
175
180
  env: sessionId
176
181
  ? { ...process.env, UKIT_SESSION_ID: sessionId }
@@ -234,8 +234,8 @@
234
234
  "hooks": [
235
235
  {
236
236
  "type": "command",
237
- "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/project-important.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-resume.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/observability-emit.mjs\":8",
238
- "timeout": 60
237
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/project-important.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-resume.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/observability-emit.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-episode-start.mjs\":8",
238
+ "timeout": 70
239
239
  }
240
240
  ]
241
241
  }