@ngockhoale/ukit 2.4.2 → 2.4.3

package/templates/.claude/ukit/index/route-task.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import fs from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as indexCore from './lib/index-core.mjs';
 import {
   DEFAULT_RECENT_CACHE_MAX_ENTRIES,
@@ -191,6 +192,583 @@ async function resolveVisionLane({
   };
 }
 
+// --- TASK-030: budgeted, fingerprint-cached router entry (routeTask) -------------------------
+// The router's prompt/tool hot path used to re-pay its heaviest unchanged-input reads on
+// every call: the skill-metadata stats, config parse, index staleness enumeration (one full
+// git enumeration per route) and the finalize pipeline. routeTask() is the bounded library
+// entry: it fingerprints every routing-relevant input with cheap bounded metadata reads,
+// returns the cached route on a hit, and on a miss recomputes under one top-level
+// deadline/signal, degrading to a safe reduced route instead of failing the hook.
+
+export const ROUTE_HOT_CACHE_FILENAME = 'route-hot-cache.json';
+
+function resolveDefaultRouteDeadlineMs() {
+  // Explicit router deadline wins; otherwise derive from the wrapper's own watchdog
+  // (skill-router.sh self-exits at UKIT_HOOK_DEADLINE_MS) and leave it exit headroom.
+  const explicit = Number.parseInt(process.env.UKIT_ROUTE_DEADLINE_MS ?? '', 10);
+  if (Number.isFinite(explicit) && explicit > 0) {
+    return explicit;
+  }
+  const hookDeadline = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS ?? '', 10);
+  if (Number.isFinite(hookDeadline) && hookDeadline > 800) {
+    return hookDeadline - 400;
+  }
+  return 2500;
+}
+
+const DEFAULT_ROUTE_DEADLINE_MS = resolveDefaultRouteDeadlineMs();
+
+// Max I/O ops (stat/readFile/readdir) per bounded scan phase. The fingerprint scan is
+// deterministic and ordered, so truncation at the cap produces a stable key on both the
+// write and the lookup side. 64 comfortably covers the ~54-op scan for the shipped catalog.
+const DEFAULT_ROUTE_IO_BUDGET = 64;
+
+// Bounded slice of the memory directory scanned for fingerprint metadata.
+const ROUTE_MEMORY_SCAN_ENTRY_LIMIT = 16;
+
+function createRouteBudget({ signal = null, deadlineMs = null } = {}) {
+  const startedAt = Date.now();
+  const effectiveDeadlineMs = Number.isFinite(deadlineMs) && deadlineMs > 0
+    ? deadlineMs
+    : DEFAULT_ROUTE_DEADLINE_MS;
+  const deadline = startedAt + effectiveDeadlineMs;
+  return {
+    signal,
+    deadlineMs: effectiveDeadlineMs,
+    startedAt,
+    deadline,
+    ioReads: 0,
+    expired: () => Boolean(signal?.aborted) || Date.now() >= deadline,
+    expiredReason: () => (signal?.aborted ? 'signal:aborted' : 'deadline'),
+    remainingMs: () => Math.max(0, deadline - Date.now()),
+  };
+}
+
+/**
+ * Caller-supplied cache adapters are outside the router's control and cannot be assumed to
+ * settle. Keep their promises observed (so a later rejection is harmless), but never let them
+ * extend the route's one top-level budget. A timeout only abandons the adapter operation; it
+ * cannot cancel arbitrary adapter code, so no value from a late settlement is used.
+ */
+function awaitBoundedRouteCacheOperation(operation, budget, operationName) {
+  if (budget.expired()) {
+    return Promise.resolve({
+      timedOut: true,
+      reason: budget.expiredReason(),
+    });
+  }
+
+  const remainingMs = budget.remainingMs();
+  if (remainingMs <= 0) {
+    return Promise.resolve({ timedOut: true, reason: 'deadline' });
+  }
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer = null;
+
+    const timeoutResult = () => ({
+      timedOut: true,
+      reason: budget.expiredReason() === 'signal:aborted'
+        ? 'signal:aborted'
+        : `deadline:${operationName}`,
+    });
+    const cleanup = () => {
+      if (timer !== null) {
+        clearTimeout(timer);
+      }
+      budget.signal?.removeEventListener?.('abort', onAbort);
+    };
+    const settle = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      const finalResult = result.timedOut || budget.expired()
+        ? (result.timedOut ? result : timeoutResult())
+        : result;
+      cleanup();
+      resolve(finalResult);
+    };
+    const onAbort = () => settle({ timedOut: true, reason: 'signal:aborted' });
+
+    timer = setTimeout(() => settle(timeoutResult()), remainingMs);
+    if (budget.signal) {
+      if (budget.signal.aborted) {
+        onAbort();
+        return;
+      }
+      budget.signal.addEventListener('abort', onAbort, { once: true });
+      if (budget.signal.aborted) {
+        onAbort();
+        return;
+      }
+    }
+
+    // Promise.resolve().then() also turns a synchronous adapter throw into an observed rejection.
+    Promise.resolve()
+      .then(operation)
+      .then(
+        (value) => settle({ value }),
+        (error) => settle({ error }),
+      );
+  });
+}
+
+async function countRouteIo(budget, promise) {
+  budget.ioReads += 1;
+  return promise;
+}
+
+async function statOrNothing(filePath) {
+  try {
+    return await fs.stat(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function statFingerprintTuple(stat) {
+  return {
+    exists: Boolean(stat?.isFile?.()),
+    size: typeof stat?.size === 'number' ? stat.size : null,
+    mtimeMs: typeof stat?.mtimeMs === 'number' ? stat.mtimeMs : null,
+  };
+}
+
+function isIndexDeadlineError(error) {
+  return error?.name === 'IndexDiscoveryTimeoutError';
+}
+
+/**
+ * Content fingerprint over EVERY input that affects routing (TASK-030 acceptance):
+ * prompt/command/target text, adapter/namespace/taskType/vision inputs, the route catalog
+ * composition, per-skill file metadata (stat tuples — config/skill changes force a miss),
+ * escalation config content, index generated-at, project verification metadata and the
+ * bounded memory-snapshot sources. Raw prompt bodies only ever feed the hashed key — they
+ * are never persisted, because the cached entry stores the opaque key plus the compact
+ * route state (prompt fields stripped, see buildRouteHotCacheState).
+ */
+async function buildRouteHotFingerprint({ rootDir, input, budget }) {
+  const absoluteRoot = path.resolve(rootDir);
+  const scanReadsAtStart = budget.ioReads;
+  const scanReads = () => budget.ioReads - scanReadsAtStart;
+  const payload = {
+    version: 1,
+    promptText: String(input.promptText || '').trim(),
+    lastExplicitUserPromptText: String(input.lastExplicitUserPromptText || '').trim(),
+    commandText: String(input.commandText || '').trim(),
+    targetFile: normalizeRelativeFile(absoluteRoot, input.targetFile),
+    taskType: String(input.taskType || '').trim(),
+    adapter: String(input.adapter || 'claude').trim() || 'claude',
+    commandNamespace: String(input.commandNamespace || '.claude').trim() || '.claude',
+    visionFlag: Boolean(input.visionFlag),
+    catalog: {
+      length: ROUTE_CATALOG.length,
+      digest: stableMachineDigest(ROUTE_CATALOG.map((entry) => ({
+        id: entry.id,
+        path: entry.path,
+        order: entry.order,
+        contextMode: entry.contextMode ?? 'indexed',
+      }))),
+    },
+    skills: [],
+    config: null,
+    indexGeneratedAtMs: null,
+    project: null,
+    memory: null,
+  };
+
+  for (const entry of ROUTE_CATALOG) {
+    if (budget.expired()) {
+      return { fingerprint: null, configJson: null, scanReads: scanReads() };
+    }
+    if (scanReads() >= DEFAULT_ROUTE_IO_BUDGET) {
+      payload.ioBudgetExhausted = true;
+      break;
+    }
+    const stat = await countRouteIo(budget, statOrNothing(path.join(absoluteRoot, entry.path)));
+    payload.skills.push({ path: entry.path, ...statFingerprintTuple(stat) });
+  }
+
+  if (!payload.ioBudgetExhausted && !budget.expired()) {
+    const configPath = path.join(absoluteRoot, '.ukit', 'storage', 'config.json');
+    const configStat = await countRouteIo(budget, statOrNothing(configPath));
+    payload.config = configStat
+      ? { ...statFingerprintTuple(configStat), content: await countRouteIo(budget, readJson(configPath, null)) }
+      : null;
+  }
+
+  if (!payload.ioBudgetExhausted && !budget.expired()) {
+    // One bounded read of the index artifact timestamp; a rebuild (route 1) or a source
+    // change that triggers one (staleness check) always changes this value.
+    payload.indexGeneratedAtMs = await countRouteIo(
+      budget,
+      getIndexArtifactGeneratedAt({ rootDir: absoluteRoot }),
+    );
+  }
+
+  if (!payload.ioBudgetExhausted && !budget.expired()) {
+    const projectVerification = await readProjectVerificationFingerprint(absoluteRoot);
+    budget.ioReads += projectVerification.entries.length;
+    payload.project = projectVerification.fingerprint;
+  }
+
+  if (!payload.ioBudgetExhausted && !budget.expired()) {
+    const memoryDirPath = path.join(absoluteRoot, '.ukit', 'storage', 'memory');
+    let dirents = null;
+    try {
+      dirents = await countRouteIo(budget, fs.readdir(memoryDirPath, { withFileTypes: true }));
+    } catch {
+      dirents = null;
+    }
+    const memoryEntries = [];
+    for (const dirent of (dirents ?? []).slice(0, ROUTE_MEMORY_SCAN_ENTRY_LIMIT)) {
+      if (scanReads() >= DEFAULT_ROUTE_IO_BUDGET) {
+        payload.ioBudgetExhausted = true;
+        break;
+      }
+      const stat = await countRouteIo(budget, statOrNothing(path.join(memoryDirPath, dirent.name)));
+      memoryEntries.push({ name: dirent.name, ...statFingerprintTuple(stat) });
+    }
+    const outputHistoryStat = await countRouteIo(
+      budget,
+      statOrNothing(path.join(absoluteRoot, '.ukit', 'storage', 'cache', 'output-history.json')),
+    );
+    payload.memory = { entries: memoryEntries, outputHistory: statFingerprintTuple(outputHistoryStat) };
+  }
+
+  if (budget.expired()) {
+    return { fingerprint: null, configJson: null, scanReads: scanReads() };
+  }
+  return {
+    fingerprint: buildCompactMachineKey('route-hot-v1', payload),
+    configJson: payload.config?.content ?? null,
+    scanReads: scanReads(),
+  };
+}
+
+function createDefaultRouteHotCache({ rootDir }) {
+  const cachePath = path.join(path.resolve(rootDir), '.claude', 'ukit', ROUTE_HOT_CACHE_FILENAME);
+  return {
+    cachePath,
+    async read(requestKey) {
+      try {
+        return await readRecentCacheEntry(cachePath, requestKey, {
+          maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+        });
+      } catch {
+        return null;
+      }
+    },
+    async write(entry) {
+      try {
+        await writeRecentCacheEntry(cachePath, entry, {
+          maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+function buildRouteHotCacheState(sharedState = {}) {
+  const state = { ...sharedState };
+  const routingContext = { ...(state.routingContext ?? {}) };
+  // Cache never stores prompt bodies or command text (TASK-030 acceptance): the opaque
+  // request key already covers them, and routeTask restores lastExplicitUserPromptText
+  // from the current input on a hit so printed output stays compatible with main().
+  delete routingContext.promptText;
+  delete routingContext.lastExplicitUserPromptText;
+  delete routingContext.commandText;
+  delete state.sessionId;
+  state.routingContext = routingContext;
+  return state;
+}
+
+function buildCachedRouteLookupState(cachedEntry, input) {
+  const cachedState = cachedEntry?.state;
+  if (!cachedState?.routeSummary || !Array.isArray(cachedState.activeSkills)) {
+    return null;
+  }
+  const preservedPrompt = String(input.promptText || '').trim()
+    || String(input.lastExplicitUserPromptText || '').trim();
+  return {
+    ...cachedState,
+    routingContext: {
+      ...cachedState.routingContext,
+      ...(preservedPrompt ? { lastExplicitUserPromptText: preservedPrompt } : {}),
+    },
+    ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+    source: 'task-route',
+    ts: Date.now(),
+  };
+}
+
+function buildReducedRouteState({ input, reason }) {
+  // Safe reduced route: pure text-derived routing only — zero skills, no indexed context,
+  // no I/O. Callers can rely on the standard state shape; routeMeta.reduced marks it.
+  const absoluteRoot = path.resolve(input.rootDir ?? process.cwd());
+  const normalizedPrompt = String(input.promptText || '').trim();
+  const normalizedCommand = String(input.commandText || '').trim();
+  const normalizedTarget = normalizeRelativeFile(absoluteRoot, input.targetFile);
+  const intentMode = deriveIntentMode({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+  });
+  const taskType = input.taskType ?? inferTaskType({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    selectedIds: [],
+    targetFile: normalizedTarget,
+  });
+  const executionScores = deriveExecutionScores({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    intentMode,
+    taskType,
+  });
+  const executionCandidates = buildExecutionModeCandidates({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    intentMode,
+    executionScores,
+  });
+  const executionMode = deriveExecutionMode({
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    intentMode,
+    executionScores,
+    executionCandidates,
+    signalText: buildNormalizedRouteSignalText(normalizedPrompt, normalizedCommand),
+  });
+  const routingContext = {
+    adapter: String(input.adapter || 'claude').trim() || 'claude',
+    promptText: normalizedPrompt,
+    lastExplicitUserPromptText: normalizedPrompt || String(input.lastExplicitUserPromptText || '').trim(),
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    contextIntent: deriveContextIntent({
+      promptText: normalizedPrompt,
+      commandText: normalizedCommand,
+      targetFile: normalizedTarget,
+      selectedIds: [],
+    }),
+    taskType,
+    intentMode,
+    executionScores,
+    executionCandidates,
+    executionMode,
+    visionLane: false,
+    visionReason: null,
+    visionModel: null,
+    visionAdvisory: null,
+  };
+  const route = {
+    activeSkills: [],
+    routingContext,
+    routeSummary: buildRouteSummary({ activeSkills: [], routingContext }),
+  };
+  return createSharedRouteState({
+    route,
+    source: 'task-route',
+    requestKey: null,
+    sessionId: input.sessionId ?? null,
+  });
+}
+
+/**
+ * Bounded, fingerprint-cached router entry (TASK-030).
+ * @param {object} input { rootDir, promptText, commandText, targetFile, taskType, adapter,
+ *   commandNamespace, visionFlag, lastExplicitUserPromptText, sessionId }
+ * @param {object} options { signal?: AbortSignal, deadlineMs?: number, cache?: adapter }
+ *   adapter: { read(requestKey) -> entry|null, write(entry) -> boolean, cachePath? }
+ * @returns {object} shared route state + cacheHit + bounded routeMeta diagnostics
+ *   { cacheHit, reduced, reason, deadlineMs, elapsedMs, ioReads, ioBudget, cachePath }
+ */
+export async function routeTask(input = {}, { signal = null, deadlineMs = null, cache = null } = {}) {
+  const absoluteRoot = path.resolve(input.rootDir ?? process.cwd());
+  const budget = createRouteBudget({ signal, deadlineMs });
+  const hotCache = cache ?? createDefaultRouteHotCache({ rootDir: absoluteRoot });
+  const normalizedInput = { ...input, rootDir: absoluteRoot };
+  const baseMeta = {
+    cacheHit: false,
+    reduced: false,
+    reason: null,
+    deadlineMs: budget.deadlineMs,
+    elapsedMs: 0,
+    ioReads: 0,
+    ioBudget: DEFAULT_ROUTE_IO_BUDGET,
+    cachePath: hotCache.cachePath ?? null,
+  };
+  const finish = (state, metaOverrides = {}) => {
+    const routeMeta = {
+      ...baseMeta,
+      ...metaOverrides,
+      elapsedMs: Date.now() - budget.startedAt,
+      ioReads: budget.ioReads,
+    };
+    return { ...state, cacheHit: routeMeta.cacheHit, routeMeta };
+  };
+  const reduce = (reason) => finish(
+    buildReducedRouteState({ input: normalizedInput, reason }),
+    { reduced: true, reason },
+  );
+
+  // Phase 1 — fingerprint + hot-cache lookup (the only I/O on the hit path).
+  if (budget.expired()) {
+    return reduce(budget.expiredReason());
+  }
+  const scan = await buildRouteHotFingerprint({ rootDir: absoluteRoot, input: normalizedInput, budget });
+  if (scan.fingerprint === null) {
+    return reduce(budget.expiredReason());
+  }
+  const cacheRead = await awaitBoundedRouteCacheOperation(
+    () => hotCache.read(scan.fingerprint),
+    budget,
+    'cache-read',
+  );
+  if (cacheRead.timedOut) {
+    return reduce(cacheRead.reason);
+  }
+  const cachedEntry = cacheRead.error ? null : cacheRead.value;
+  const cachedState = buildCachedRouteLookupState(cachedEntry, normalizedInput);
+  if (cachedState) {
+    return finish(cachedState, { cacheHit: true });
+  }
+
+  // Phase 2 — bounded full computation. Mirrors main()'s pipeline minus the shared-state,
+  // audit and helper-cache-seeding writes (main() stays the single writer for those).
+  const escalationConfig = scan.configJson
+    ?? await readJson(path.join(absoluteRoot, '.ukit', 'storage', 'config.json'), null);
+  const preparedRoute = await prepareTaskRoute({
+    rootDir: absoluteRoot,
+    promptText: normalizedInput.promptText,
+    commandText: normalizedInput.commandText,
+    targetFile: normalizedInput.targetFile,
+    taskType: normalizedInput.taskType,
+    adapter: normalizedInput.adapter,
+    lastExplicitUserPromptText: normalizedInput.lastExplicitUserPromptText,
+    commandNamespace: normalizedInput.commandNamespace,
+    visionFlag: normalizedInput.visionFlag,
+  });
+  const useIndexedContext = shouldUseIndexedContext({
+    activeSkills: preparedRoute.activeSkills,
+    targetFile: preparedRoute.routingContext?.targetFile ?? null,
+  });
+  let indexGeneratedAtMs = null;
+  if (useIndexedContext) {
+    if (budget.expired()) {
+      return reduce(budget.expiredReason());
+    }
+    try {
+      indexGeneratedAtMs = await ensureFreshIndex({
+        rootDir: absoluteRoot,
+        logPrefix: 'route',
+        signal: budget.signal,
+        deadlineMs: budget.remainingMs(),
+        discoverySnapshot: null,
+      });
+    } catch (error) {
+      if (isIndexDeadlineError(error) || budget.expired()) {
+        return reduce(budget.expiredReason() === 'signal:aborted' ? 'signal:aborted' : 'deadline:index-refresh');
+      }
+      throw error;
+    }
+  }
+  const projectVerification = useIndexedContext
+    ? await readProjectVerificationFingerprint(absoluteRoot)
+    : null;
+  if (projectVerification) {
+    budget.ioReads += projectVerification.entries.length;
+  }
+  const recentOutputSnapshot = shouldIncludeRecentOutput({
+    activeSkills: preparedRoute.activeSkills,
+    routingContext: preparedRoute?.routingContext ?? {},
+    useIndexedContext,
+  })
+    ? await buildRecentOutputSnapshot({ rootDir: absoluteRoot })
+    : null;
+  if (budget.expired()) {
+    return reduce(budget.expiredReason());
+  }
+  const previousContextSnapshot = shouldIncludePreviousContext({
+    routingContext: preparedRoute?.routingContext ?? {},
+    useIndexedContext,
+  })
+    ? await buildPreviousContextSnapshot({
+        rootDir: absoluteRoot,
+        routingContext: preparedRoute?.routingContext ?? {},
+      })
+    : null;
+  if (budget.expired()) {
+    return reduce(budget.expiredReason());
+  }
+  const requestKey = buildRouteRequestKey({
+    commandNamespace: normalizedInput.commandNamespace,
+    indexGeneratedAtMs,
+    projectFingerprint: projectVerification?.fingerprint ?? null,
+    activeSkills: preparedRoute.activeSkills,
+    routingContext: preparedRoute.routingContext,
+    previousContextSnapshot,
+    recentOutputSnapshot,
+  });
+  const helperCacheSnapshot = await readHelperCacheSnapshot({
+    rootDir: absoluteRoot,
+    indexGeneratedAtMs,
+    projectFingerprint: projectVerification?.fingerprint ?? '',
+    routingContext: preparedRoute.routingContext,
+    useIndexedContext,
+  });
+  const route = await finalizeTaskRoute({
+    rootDir: absoluteRoot,
+    commandNamespace: normalizedInput.commandNamespace,
+    preparedRoute,
+    projectVerification,
+    cachedContextResult: helperCacheSnapshot.contextResult,
+    cachedVerificationPlan: helperCacheSnapshot.verificationPlan,
+    useIndexedContext,
+    previousContextSnapshot,
+    recentOutputSnapshot,
+    previousRouteSummary: null,
+    escalationConfig,
+  });
+  const sharedState = createSharedRouteState({
+    route,
+    source: 'task-route',
+    requestKey,
+    indexGeneratedAtMs,
+    sessionId: normalizedInput.sessionId ?? null,
+  });
+
+  // Phase 3 — store under a POST-route fingerprint so the next identical call (whose own
+  // scan now sees the post-route filesystem state) hits. Never cached: reduced routes.
+  // A cache failure (malformed, unwritable, throwing adapter) must never fail the route.
+  const postScan = await buildRouteHotFingerprint({ rootDir: absoluteRoot, input: normalizedInput, budget });
+  if (postScan.fingerprint !== null && !budget.expired()) {
+    const cacheWrite = await awaitBoundedRouteCacheOperation(
+      () => hotCache.write({
+        requestKey: postScan.fingerprint,
+        updatedAt: Date.now(),
+        state: buildRouteHotCacheState(sharedState),
+      }),
+      budget,
+      'cache-write',
+    );
+    // Cache store failure or timeout is advisory only — the computed route is still returned.
+    // `cacheWrite.error` is intentionally ignored to preserve existing error swallowing.
+  }
+  return finish(sharedState, { cacheHit: false });
+}
+
+export { DEFAULT_ROUTE_DEADLINE_MS, DEFAULT_ROUTE_IO_BUDGET };
+
 async function main() {
   const args = process.argv.slice(2);
   const rootDir = getRootDir(args);
@@ -393,7 +971,14 @@ async function main() {
   printRouteState(sharedState);
 }
 
-async function ensureFreshIndex({ rootDir, logPrefix }) {
+async function ensureFreshIndex({ rootDir, logPrefix, signal = null, deadlineMs = null, discoverySnapshot = null } = {}) {
+  // TASK-030: the stale check and the rebuild are the router's heaviest unchanged-input
+  // reads (one full repository enumeration each), so both accept the caller's top-level
+  // deadline/signal. Omitted (main()'s CLI path) keeps the index-core defaults.
+  const discoveryOptions = {
+    ...(signal ? { signal } : {}),
+    ...(Number.isFinite(deadlineMs) && deadlineMs > 0 ? { deadlineMs } : {}),
+  };
   const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
   const stale = lastRefreshMs === null
     ? true
@@ -403,6 +988,7 @@ async function ensureFreshIndex({ rootDir, logPrefix }) {
           maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS,
           now: Date.now(),
           generatedAtMs: lastRefreshMs,
+          ...discoveryOptions,
         })
       : (Date.now() - lastRefreshMs) > DEFAULT_INDEX_CACHE_MAX_AGE_MS;
 
@@ -410,7 +996,7 @@ async function ensureFreshIndex({ rootDir, logPrefix }) {
     return lastRefreshMs;
   }
 
-  const summary = await buildCodeIndex({ rootDir });
+  const summary = await buildCodeIndex({ rootDir, ...discoveryOptions, discoverySnapshot });
   if (lastRefreshMs !== null) {
     console.log(`[ukit:${logPrefix}] stale index refreshed (last=${new Date(lastRefreshMs).toISOString()})`);
   } else {
@@ -3533,4 +4119,24 @@ function selectInlineSummaryTail(lines = []) {
   return lines[lines.length - 1] ?? '';
 }
 
-await main();
+// TASK-030: run the CLI flow only on a direct `node route-task.mjs` invocation. Library
+// importers (tests, future callers of routeTask) get the exports without main()'s
+// argv-driven side effects.
+function isDirectCliInvocation() {
+  const entry = process.argv?.[1];
+  if (!entry) {
+    return false;
+  }
+  try {
+    if (import.meta.url === pathToFileURL(entry).href) {
+      return true;
+    }
+    return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectCliInvocation()) {
+  await main();
+}