@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
@@ -143,7 +143,9 @@ const DISCOVERED_EXTENSIONS = new Set([...TRACKED_EXTENSIONS, ...STYLE_EXTENSION
143
143
  // SQL 'column' rows with parent/schema, and calls.json gains per-object SQL
144
144
  // reference records — a v8 cached artifact must not be reused for unchanged
145
145
  // files or the new extractions silently vanish.
146
- export const INDEX_SCHEMA_VERSION = 9;
146
+ // v10: symbols.json gains unexported function/class ('local-function', 'local-class'),
147
+ // function-expression consts, class 'method' rows and TS interface/enum/type ('type') rows.
148
+ export const INDEX_SCHEMA_VERSION = 10;
147
149
  export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
148
150
  // Parse-phase read/extract concurrency — deliberately tighter than the
149
151
  // discovery stat pool because parsing holds file content in memory.
@@ -1247,7 +1249,11 @@ function isFunctionLikeSignature(signature) {
1247
1249
  // Reads symbols.json through the existing readArtifact cache (no new file reads, no new
1248
1250
  // cache). Never throws: an absent file, a missing artifact, or a stale schema all resolve
1249
1251
  // to [] so callers can render an outline block unconditionally.
1250
- export async function getFileOutline({ rootDir = process.cwd(), filePath, limit = 12 } = {}) {
1252
+ const OUTLINE_WINDOW = 12; // matches OUTLINE_SYMBOLS_LIMIT in the CLI printers
1253
+
1254
+ // `focus`: symbol names the query matched (see queryMatchedSymbolNames); they are pinned into
1255
+ // the first OUTLINE_WINDOW rows even when unexported, so the printed outline shows the hit.
1256
+ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit = 12, focus = null } = {}) {
1251
1257
  if (!filePath) {
1252
1258
  return Object.freeze([]);
1253
1259
  }
@@ -1273,9 +1279,26 @@ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit
1273
1279
  seenNames.add(item.name);
1274
1280
  deduped.push(item);
1275
1281
  }
1282
+ // The first OUTLINE_WINDOW rows (what the CLI prints) hold exported/top-level symbols
1283
+ // first; unexported functions and class methods only take the remaining slots. Each
1284
+ // part stays in line order, and rows beyond the window follow in line order.
1285
+ const window = Number.isFinite(limit) ? limit : OUTLINE_WINDOW;
1286
+ let kept = deduped;
1287
+ if (deduped.length > window) {
1288
+ const pinned = new Set(focus ?? []);
1289
+ const isPinned = (item) => pinned.has(item.name);
1290
+ const ranked = [
1291
+ ...deduped.filter(isPinned),
1292
+ ...deduped.filter((item) => !isPinned(item) && !isLocalOutlineRow(item)),
1293
+ ...deduped.filter((item) => !isPinned(item) && isLocalOutlineRow(item)),
1294
+ ];
1295
+ const head = ranked.slice(0, window).sort((a, b) => a.line - b.line);
1296
+ const inHead = new Set(head);
1297
+ kept = [...head, ...deduped.filter((item) => !inHead.has(item))];
1298
+ }
1276
1299
 
1277
1300
  return Object.freeze(
1278
- deduped.slice(0, limit).map((item) => Object.freeze({
1301
+ kept.slice(0, limit).map((item) => Object.freeze({
1279
1302
  line: item.line,
1280
1303
  name: item.name,
1281
1304
  type: item.type,
@@ -1284,7 +1307,8 @@ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit
1284
1307
  );
1285
1308
  }
1286
1309
 
1287
- export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5 } = {}) {
1310
+ // contentLane=false skips the error-string content search (context-resolution paths never pay for it).
1311
+ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5, contentLane = true } = {}) {
1288
1312
  const normalizedQuery = String(query ?? '').trim();
1289
1313
  if (!normalizedQuery) return [];
1290
1314
  if (limit <= 0) return Object.freeze([]);
@@ -1296,6 +1320,7 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
1296
1320
  rootDir: absoluteRoot,
1297
1321
  query: normalizedQuery,
1298
1322
  limit,
1323
+ contentLane,
1299
1324
  });
1300
1325
  if (QUERY_RESULT_CACHE.has(queryCacheKey)) {
1301
1326
  return QUERY_RESULT_CACHE.get(queryCacheKey);
@@ -1323,7 +1348,50 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
1323
1348
  }
1324
1349
  }
1325
1350
 
1326
- if (directScores.size === 0) return Object.freeze([]);
1351
+ // Content lane: a message-like query with no confident symbol/path hit also searches
1352
+ // file contents through the existing bounded fallback search. It only adds a bounded
1353
+ // bonus, so it can never displace a confident hit (those skip the lane entirely).
1354
+ let bestDirect = 0;
1355
+ let contentLaneRan = false;
1356
+ let contentCutShort = [];
1357
+ for (const entry of directScores.values()) {
1358
+ bestDirect = Math.max(bestDirect, entry.score);
1359
+ }
1360
+ if (contentLane && bestDirect < CONTENT_LANE_CONFIDENT_SCORE && queryDescriptor.tokens.size >= CONTENT_LANE_MIN_TOKENS && looksLikeLiteralMessage(normalizedQuery)) {
1361
+ contentLaneRan = true;
1362
+ // A literal message sits on one source line: every query token must share the matched
1363
+ // line, otherwise this is a scattered token hit, not the message. The scan order and the
1364
+ // count/byte caps are functions of the index and file contents only (never of load or of
1365
+ // ripgrep being installed); wall-clock is a safety cap that reports 'time-budget'.
1366
+ const messageTokens = [...new Set(normalizeIdentifierTokens(queryDescriptor.rawLower))];
1367
+ let lineHits = [];
1368
+ try {
1369
+ const ordered = rankContentLaneFiles({
1370
+ files, searchDescriptorsByFile, tokenWeights, queryTokens: queryDescriptor.tokens, includeLikelyTestFiles,
1371
+ });
1372
+ const scan = await scanContentLane({ absoluteRoot, ordered, tokens: messageTokens, limit: CONTENT_LANE_LIMIT });
1373
+ lineHits = scan.hits;
1374
+ contentCutShort = scan.truncated;
1375
+ } catch {
1376
+ contentCutShort = ['error'];
1377
+ }
1378
+ lineHits.forEach((row, index) => {
1379
+ const existing = directScores.get(row.filePath);
1380
+ const reason = `content_match:${row.filePath}${row.line ? `:${row.line}` : ''}`;
1381
+ if (existing) {
1382
+ existing.score += CONTENT_LANE_BONUS;
1383
+ existing.reasons = dedupe([...(existing.reasons ?? []), reason]);
1384
+ } else {
1385
+ directScores.set(row.filePath, {
1386
+ filePath: row.filePath,
1387
+ score: CONTENT_LANE_ONLY_SCORE - index * 0.1,
1388
+ reasons: [reason],
1389
+ });
1390
+ }
1391
+ });
1392
+ }
1393
+
1394
+ if (directScores.size === 0) return withContentLaneStatus(Object.freeze([]), contentLaneRan, contentCutShort);
1327
1395
 
1328
1396
  const {
1329
1397
  hotspotScores,
@@ -1361,9 +1429,9 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
1361
1429
  directScores,
1362
1430
  scores: applyHotspotBoosts({ scores: relatedScores, hotspotScores }),
1363
1431
  });
1364
- return freezeQueryResults(
1432
+ return withContentLaneStatus(freezeQueryResults(
1365
1433
  [...boosted.values()].map((entry) => ({ ...entry, score: finalizeScore(entry) })).sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath)).slice(0, limit),
1366
- );
1434
+ ), contentLaneRan, contentCutShort);
1367
1435
  })().catch((error) => {
1368
1436
  QUERY_RESULT_CACHE.delete(queryCacheKey);
1369
1437
  throw error;
@@ -1442,6 +1510,30 @@ export function clearIndexArtifactCache(rootDir = null) {
1442
1510
  RELATED_TEST_LOOKUP_CACHE.delete(absoluteRoot);
1443
1511
  }
1444
1512
 
1513
+ // Names of the symbols a query result matched, parsed from its `symbol_exact:` /
1514
+ // `symbol_token:` reasons; feed to getFileOutline({ focus }).
1515
+ export function queryMatchedSymbolNames(result) {
1516
+ const names = [];
1517
+ for (const reason of result?.reasons ?? []) {
1518
+ const match = /^symbol_(?:exact|compact|contains):([^:]+)$/.exec(reason) ?? /^symbol_token:([^:]+):/.exec(reason);
1519
+ if (match) {
1520
+ names.push(match[1]);
1521
+ }
1522
+ }
1523
+ return names;
1524
+ }
1525
+
1526
+ // Non-enumerable (array equality and JSON stay unchanged), like boundedSourceSearch rows.truncated:
1527
+ // `contentLane` is true when the content search ran; `contentLaneTruncated` lists why it was cut
1528
+ // short ('verify-cap', 'time-budget', 'max-files', ...) so a partial scan never reads as "no match".
1529
+ function withContentLaneStatus(results, ran, truncated) {
1530
+ // results arrive frozen, so copy before attaching the status and freeze again.
1531
+ const out = [...results];
1532
+ Object.defineProperty(out, 'contentLane', { value: ran, enumerable: false });
1533
+ Object.defineProperty(out, 'contentLaneTruncated', { value: Object.freeze([...truncated]), enumerable: false });
1534
+ return Object.freeze(out);
1535
+ }
1536
+
1445
1537
  function freezeQueryResults(results) {
1446
1538
  return Object.freeze(
1447
1539
  results.map((item) => Object.freeze({
@@ -1586,7 +1678,7 @@ export async function resolveContext({
1586
1678
  }
1587
1679
 
1588
1680
  if (queryWasUsed) {
1589
- const queryResults = await queryCodeIndex({ rootDir, query: intent, limit: budget.maxFiles });
1681
+ const queryResults = await queryCodeIndex({ rootDir, query: intent, limit: budget.maxFiles, contentLane: false });
1590
1682
  for (const qr of queryResults) {
1591
1683
  addExplainedFile(result, 'primaryTargets', qr.filePath, buildQueryReason(qr));
1592
1684
  }
@@ -2772,6 +2864,8 @@ function computeSignature(content, lineStartIndex) {
2772
2864
  return `${collapsed.slice(0, 199)}…`;
2773
2865
  }
2774
2866
 
2867
+ const CLASS_METHOD_SKIP = new Set(['if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'with', 'constructor', 'super']);
2868
+
2775
2869
  export function extractSymbols(filePath, content) {
2776
2870
  const out = [];
2777
2871
  const lineStarts = computeLineStarts(content);
@@ -2833,6 +2927,30 @@ export function extractSymbols(filePath, content) {
2833
2927
  addMatches(/defineComponent\(\s*\{[\s\S]*?name\s*:\s*['"]([^'"]+)['"]/g, 'component-name');
2834
2928
  addMatches(/export\s+default\s*\{[\s\S]*?name\s*:\s*['"]([^'"]+)['"]/g, 'component-name');
2835
2929
 
2930
+ // Unexported declarations (3.5.4). Line-anchored, so `export function` / `export class`
2931
+ // (indexed above as exported) never double-count. Local types rank below exported ones.
2932
+ addMatches(/^[ \t]*(?:async\s+)?function\s*\*?\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*[(<]/gm, 'local-function');
2933
+ addMatches(/^[ \t]*(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s+)?function\b/gm, 'callable');
2934
+ addMatches(/^[ \t]*(?:abstract\s+)?class\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm, 'local-class');
2935
+ if (/\.(?:ts|tsx|mts|cts|vue)$/.test(filePath)) {
2936
+ addMatches(/^[ \t]*(?:export\s+)?(?:declare\s+)?(?:const\s+)?(?:interface|enum)\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm, 'type');
2937
+ addMatches(/^[ \t]*(?:export\s+)?(?:declare\s+)?type\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*(?:<[^=\n]*>)?\s*=/gm, 'type');
2938
+ }
2939
+ // Class methods: indented `name(args) {` lines inside a balanced class body.
2940
+ for (const classMatch of content.matchAll(/(?:^|[^\w$.])class\s+[A-Za-z_$][A-Za-z0-9_$]*(?:\s+extends\s+[\w$.]+(?:\([^)]*\))?)?\s*\{/g)) {
2941
+ const bodyStart = classMatch.index + classMatch[0].length;
2942
+ const classBody = sliceBalancedBlock(content, bodyStart);
2943
+ if (!classBody) {
2944
+ continue;
2945
+ }
2946
+ for (const methodMatch of classBody.matchAll(/^[ \t]+(?:(?:static|async|get|set)\s+)*\*?\s*(#?[A-Za-z_$][A-Za-z0-9_$]*)\s*\([^()]*\)\s*\{/gm)) {
2947
+ if (CLASS_METHOD_SKIP.has(methodMatch[1])) {
2948
+ continue;
2949
+ }
2950
+ addSymbol(methodMatch[1], 'method', bodyStart + methodMatch.index + methodMatch[0].indexOf(methodMatch[1]));
2951
+ }
2952
+ }
2953
+
2836
2954
  // Global-registered frontend functions: reachable from anywhere without an
2837
2955
  // import edge, so impact analysis must treat them as verified dependencies.
2838
2956
  addMatches(/\b(?:window|globalThis|global)\s*\.\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*=/g, 'global');
@@ -3405,10 +3523,22 @@ const PATH_EXACT_SCORE = 60;
3405
3523
  const PATH_SUFFIX_SCORE = 48;
3406
3524
  const PATH_BASENAME_SCORE = 40;
3407
3525
  const SYMBOL_EXACT_SCORE = 40;
3526
+ const LOCAL_SYMBOL_FACTOR = 0.85; // unexported symbols (local function/class, method, unexported type) rank below an exported symbol of the same name
3408
3527
  const SYMBOL_DECAY = 0.35; // k-th best symbol of a file adds score * SYMBOL_DECAY^k
3409
3528
  const SYMBOL_REASON_LIMIT = 3;
3410
3529
  const MIN_SUBSTRING_TOKEN_LENGTH = 3;
3411
3530
  const BOOST_LIFT_RATIO = 0.2; // import/hotspot/archetype boosts may add at most this share of a direct score (+1)
3531
+ const CONTENT_LANE_CONFIDENT_SCORE = 30; // a best direct score at/above this (exact symbol or path hit) skips the content lane
3532
+ const CONTENT_LANE_MIN_TOKENS = 3; // shorter queries are names, not messages
3533
+ const CONTENT_LANE_LIMIT = 40; // candidates only share tokens somewhere in the file; the same-line check below keeps the real ones
3534
+ 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
3535
+ const CONTENT_LANE_BONUS = 14; // added to a file that already has a direct score
3536
+ const CONTENT_LANE_ONLY_SCORE = 13; // base for a file found only by content; below CONTENT_LANE_CONFIDENT_SCORE by design
3537
+ const CONTENT_LANE_MAX_FILES = 1500; // files read per query, in priority order (primary bound)
3538
+ const CONTENT_LANE_MAX_BYTES = 24 * 1024 * 1024; // characters read per query (primary bound)
3539
+ const CONTENT_LANE_MAX_FILE_BYTES = 512 * 1024; // larger files are generated/data, never scanned
3540
+ const CONTENT_LANE_BATCH = 24;
3541
+ const CONTENT_LANE_SAFETY_MS = 5000; // safety cap only: hitting it reports 'time-budget', normal runs never do
3412
3542
  const BOOST_ONLY_RATIO = 0.3; // files with no direct match stay below this share of the best direct score
3413
3543
 
3414
3544
  // Rarity weight per token in (0,1]: a token present in nearly every file is worth
@@ -3439,10 +3569,10 @@ function buildTokenWeights(searchDescriptorsByFile) {
3439
3569
  // hiding the mirror: root installed copies < template_project < everything else.
3440
3570
  function mirrorPrior(filePath) {
3441
3571
  if (/^\.(?:claude|codex|omp)\//.test(filePath)) {
3442
- return 0.88;
3572
+ return 0.8;
3443
3573
  }
3444
3574
  if (filePath.startsWith('template_project/')) {
3445
- return 0.94;
3575
+ return 0.85;
3446
3576
  }
3447
3577
  return 1;
3448
3578
  }
@@ -3510,7 +3640,7 @@ function scoreDirectFileMatch({ queryDescriptor, rawQuery = '', filePath, search
3510
3640
  queryDescriptor.compact.length >= 4
3511
3641
  && symbolDescriptor.descriptor.compact === queryDescriptor.compact
3512
3642
  ) {
3513
- symbolHits.push({ score: SYMBOL_EXACT_SCORE, reasons: [`symbol_exact:${symbolDescriptor.name}`] });
3643
+ symbolHits.push({ score: SYMBOL_EXACT_SCORE * (symbolDescriptor.local ? LOCAL_SYMBOL_FACTOR : 1), reasons: [`symbol_exact:${symbolDescriptor.name}`] });
3514
3644
  continue;
3515
3645
  }
3516
3646
 
@@ -3550,7 +3680,7 @@ function scoreDirectFileMatch({ queryDescriptor, rawQuery = '', filePath, search
3550
3680
  }
3551
3681
 
3552
3682
  if (symbolScore > 0) {
3553
- symbolHits.push({ score: symbolScore, reasons: symbolReasons });
3683
+ symbolHits.push({ score: symbolScore * (symbolDescriptor.local ? LOCAL_SYMBOL_FACTOR : 1), reasons: symbolReasons });
3554
3684
  }
3555
3685
  }
3556
3686
 
@@ -4069,11 +4199,124 @@ function buildFileSearchDescriptors(files, symbolMap) {
4069
4199
  return descriptors;
4070
4200
  }
4071
4201
 
4202
+ // Rows whose declaration is not exported. 'callable' keeps its pre-3.5.4 weight.
4203
+ // Outline-only: a 'callable' const without `export` is also unexported.
4204
+ function isLocalOutlineRow(item) {
4205
+ return isLocalSymbolRow(item) || (item?.type === 'callable' && !/^\s*export\b/.test(item?.signature ?? ''));
4206
+ }
4207
+
4208
+ function isLocalSymbolRow(symbol) {
4209
+ const type = symbol?.type;
4210
+ if (type === 'local-function' || type === 'local-class' || type === 'method') {
4211
+ return true;
4212
+ }
4213
+ return type === 'type' && !/^\s*export\b/.test(symbol?.signature ?? '');
4214
+ }
4215
+
4216
+ // Single identifiers, questions and non-ASCII (Vietnamese) prose are descriptions of behaviour, not strings
4217
+ // that appear in source, so they never pay for a content search.
4218
+ function looksLikeLiteralMessage(query) {
4219
+ return /^[\x20-\x7e]+$/.test(query)
4220
+ && query.split(/\s+/).length >= CONTENT_LANE_MIN_TOKENS // identifiers and short phrases are symbol queries, never a message
4221
+ && !/^(?:how|where|what|why|which|when|who|does|do|is|are|can|find|show|list)\b/i.test(query);
4222
+ }
4223
+
4224
+ // Stable verify order: index evidence first (rarity-weighted overlap of the query tokens with
4225
+ // each file's path and symbol tokens), originals before mirrors, then path order.
4226
+ function rankContentLaneFiles({ files, searchDescriptorsByFile, tokenWeights, queryTokens, includeLikelyTestFiles }) {
4227
+ const rows = [];
4228
+ for (const file of safeItems(files)) {
4229
+ const filePath = file?.filePath;
4230
+ if (typeof filePath !== 'string' || !CONTENT_LANE_CODE_EXT.test(filePath)) {
4231
+ continue;
4232
+ }
4233
+ if (isLikelyTestFilePath(filePath) && !includeLikelyTestFiles) {
4234
+ continue;
4235
+ }
4236
+ let overlap = 0;
4237
+ const descriptor = searchDescriptorsByFile.get(filePath);
4238
+ if (descriptor) {
4239
+ const seen = new Set(descriptor.path.tokens);
4240
+ for (const symbol of descriptor.symbols) {
4241
+ for (const token of symbol.descriptor.tokens) {
4242
+ seen.add(token);
4243
+ }
4244
+ }
4245
+ for (const token of queryTokens) {
4246
+ if (seen.has(token)) {
4247
+ overlap += tokenWeights?.get(token) ?? 1;
4248
+ }
4249
+ }
4250
+ }
4251
+ rows.push({ filePath, overlap, mirror: mirrorPrior(filePath) < 1 ? 1 : 0, size: Number.isFinite(Number(file.size)) && Number(file.size) >= 0 ? Number(file.size) : null });
4252
+ }
4253
+ rows.sort((a, b) => (b.overlap - a.overlap) || (a.mirror - b.mirror) || (a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0));
4254
+ return rows;
4255
+ }
4256
+
4257
+ // Reads files in priority order (batched for speed, consumed in order) until the hit limit or a
4258
+ // count/byte cap. Caps are checked at batch boundaries on counts and byte totals only, so the
4259
+ // same tree yields the same hits regardless of machine load.
4260
+ async function scanContentLane({ absoluteRoot, ordered, tokens, limit }) {
4261
+ const hits = [];
4262
+ const truncated = new Set();
4263
+ if (tokens.length === 0) {
4264
+ return { hits, truncated: [] };
4265
+ }
4266
+ let scanned = 0;
4267
+ let bytes = 0;
4268
+ const deadline = Date.now() + CONTENT_LANE_SAFETY_MS;
4269
+ for (let start = 0; start < ordered.length && hits.length < limit; start += CONTENT_LANE_BATCH) {
4270
+ if (scanned >= CONTENT_LANE_MAX_FILES) { truncated.add('max-files'); break; }
4271
+ if (bytes >= CONTENT_LANE_MAX_BYTES) { truncated.add('max-bytes'); break; }
4272
+ if (Date.now() > deadline) { truncated.add('time-budget'); break; }
4273
+ const batch = ordered.slice(start, start + Math.min(CONTENT_LANE_BATCH, CONTENT_LANE_MAX_FILES - scanned));
4274
+ // Size comes from the index entry, else a stat; an oversized file is skipped before any read.
4275
+ const texts = await Promise.all(batch.map(async (row) => {
4276
+ try {
4277
+ const absolute = path.join(absoluteRoot, row.filePath);
4278
+ const size = row.size ?? (await fs.stat(absolute)).size;
4279
+ if (size > CONTENT_LANE_MAX_FILE_BYTES) {
4280
+ return { text: '', size: 0 };
4281
+ }
4282
+ const text = await fs.readFile(absolute, 'utf8');
4283
+ return { text, size: Buffer.byteLength(text, 'utf8') };
4284
+ } catch {
4285
+ return { text: '', size: 0 };
4286
+ }
4287
+ }));
4288
+ for (const [index, { text, size }] of texts.entries()) {
4289
+ scanned += 1;
4290
+ bytes += size;
4291
+ if (text.length === 0 || size > CONTENT_LANE_MAX_FILE_BYTES) {
4292
+ continue;
4293
+ }
4294
+ const lower = text.toLowerCase();
4295
+ if (!tokens.every((token) => lower.includes(token))) {
4296
+ continue;
4297
+ }
4298
+ const lines = lower.split('\n');
4299
+ const lineIndex = lines.findIndex((line) => tokens.every((token) => line.includes(token)));
4300
+ if (lineIndex >= 0) {
4301
+ hits.push({ filePath: batch[index].filePath, line: lineIndex + 1 });
4302
+ if (hits.length >= limit) {
4303
+ break;
4304
+ }
4305
+ }
4306
+ }
4307
+ }
4308
+ if (scanned >= CONTENT_LANE_MAX_FILES && scanned < ordered.length && hits.length < limit) {
4309
+ truncated.add('max-files');
4310
+ }
4311
+ return { hits, truncated: [...truncated] };
4312
+ }
4313
+
4072
4314
  function createFileSearchDescriptor({ filePath, symbols }) {
4073
4315
  return {
4074
4316
  path: buildTextSearchDescriptor(filePath),
4075
4317
  symbols: symbols.map((symbol) => ({
4076
4318
  name: symbol.name,
4319
+ local: isLocalSymbolRow(symbol),
4077
4320
  descriptor: buildTextSearchDescriptor(symbol.name),
4078
4321
  })),
4079
4322
  };
@@ -53,12 +53,15 @@ if (!query && !symbolQuery) {
53
53
  query,
54
54
  limit: effectiveLimit,
55
55
  });
56
+ // The status rides on the array as a non-enumerable prop, so the cache stores it explicitly.
57
+ const contentLaneTruncated = cached ? (cached.contentLaneTruncated ?? []) : [...(results.contentLaneTruncated ?? [])];
56
58
 
57
59
  if (!cached) {
58
60
  await writeRecentCacheEntry(cachePath, {
59
61
  requestKey,
60
62
  updatedAt: Date.now(),
61
63
  result: results,
64
+ contentLaneTruncated,
62
65
  }, {
63
66
  maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
64
67
  });
@@ -71,6 +74,7 @@ if (!query && !symbolQuery) {
71
74
 
72
75
  if (existingResults.length === 0) {
73
76
  console.log('[ukit:index:query] no matches');
77
+ printContentLaneNotice(contentLaneTruncated);
74
78
  } else {
75
79
  console.log(`[ukit:index:query] top ${existingResults.length} matches for: ${query}`);
76
80
  for (const [idx, item] of existingResults.entries()) {
@@ -82,9 +86,10 @@ if (!query && !symbolQuery) {
82
86
  console.log(` reasons: ${item.reasons.join(', ')}`);
83
87
  }
84
88
  if (showOutline && idx < OUTLINE_TOP_FILES_LIMIT) {
85
- await printOutlineForFile(rootDir, item.filePath);
89
+ await printOutlineForFile(rootDir, item.filePath, indexCore.queryMatchedSymbolNames?.(item) ?? null);
86
90
  }
87
91
  }
92
+ printContentLaneNotice(contentLaneTruncated);
88
93
  }
89
94
  }
90
95
 
@@ -98,6 +103,12 @@ catch (error) {
98
103
  }
99
104
  }
100
105
 
106
+ function printContentLaneNotice(truncated) {
107
+ if (Array.isArray(truncated) && truncated.length > 0) {
108
+ console.log(`content-lane: truncated (${truncated.join(',')}) — results may be incomplete`);
109
+ }
110
+ }
111
+
101
112
  async function runSymbolMode(symbolQuery) {
102
113
  try {
103
114
  await ensureFreshIndex({ rootDir, logPrefix: 'index:query' });
@@ -177,11 +188,11 @@ async function fileExists(absolutePath) {
177
188
  }
178
189
  }
179
190
 
180
- async function printOutlineForFile(root, filePath) {
191
+ async function printOutlineForFile(root, filePath, focus = null) {
181
192
  if (typeof getFileOutline !== 'function') {
182
193
  return;
183
194
  }
184
- const outline = await getFileOutline({ rootDir: root, filePath, limit: Infinity });
195
+ const outline = await getFileOutline({ rootDir: root, filePath, limit: Infinity, focus });
185
196
  if (outline.length === 0) {
186
197
  return;
187
198
  }
@@ -1737,8 +1737,11 @@ async function main() {
1737
1737
  // with UKIT_SELF_IMPROVE=0 (tests/CI) or learning.selfImprove.enabled:false.
1738
1738
  if (process.env.UKIT_SELF_IMPROVE !== '0') {
1739
1739
  try {
1740
- const { triggerSelfImprove } = await import('../runtime/self-improve-trigger.mjs');
1740
+ const { triggerSelfImprove, triggerEpisodeStart } = await import('../runtime/self-improve-trigger.mjs');
1741
1741
  triggerSelfImprove({ projectRoot: rootDir });
1742
+ // Codex has no SessionStart/SessionEnd: the routed prompt is its only lifecycle point.
1743
+ // Same 10 min marker as the other engines, so later prompts pay one async read.
1744
+ await triggerEpisodeStart({ projectRoot: rootDir });
1742
1745
  } catch {
1743
1746
  // background work only — a missing/broken trigger never affects routing
1744
1747
  }