@ngockhoale/ukit 3.1.9 → 3.3.0

package/src/decision/client.js

@@ -49,9 +49,9 @@ const DEFAULT_CHECKPOINTS = {
   english: 'unic-decision',
   unknownLanguage: 'unic-decision',
 };
-// Credential-safe alias: every UNIC decision credential binds the bare name
-// first — variants (unic-decision-multilingual, …) may lag. On model_not_found
-// the client falls back here once per batch.
+// Credential-safe alias: every UNIC decision credential binds the bare name.
+// On model_not_found the client falls back here once per batch — the bare
+// name is also the only checkpoint name UKit ever sends.
 const FALLBACK_CHECKPOINT = 'unic-decision';
 
 const DEFAULT_TIMEOUT_MS = 5000;
@@ -360,8 +360,7 @@ export function createDecisionClient({
 
         const status = res?.status ?? (res?.ok === false ? 500 : 200);
         if (res?.ok === false || status < 200 || status >= 300) {
-          // A variant checkpoint without bound credentials (e.g.
-          // unic-decision-multilingual before provider binding) returns a 4xx
+          // A checkpoint without bound credentials returns a 4xx
           // model_not_found body — retry once on the bare `unic-decision`
           // model, the credential-safe alias the owner provisions first.
           if (checkpoint !== FALLBACK_CHECKPOINT) {

package/src/decision/runtimeDecide.js

@@ -83,6 +83,46 @@ export const RUNTIME_DECISIONS = Object.freeze([
       'A runtime event may warrant a retry but no deterministic policy covers it. Decide conservatively.',
     candidates: ['retry', 'no_retry', 'escalate'],
   },
+  // V-05: VM decision nodes — the bounded route/classify questions a
+  // vmEngine classifyFn may ask when the plan IR cannot route an event.
+  // Owner is the deterministic escalation lane: every failure mode resolves
+  // to escalateUnclassified, never a hard failure.
+  {
+    decisionKey: 'runtime.node_route.v1',
+    schemaVersion: 1,
+    family: 'runtime',
+    owner: 'vmEngine',
+    kind: 'choice',
+    description: 'Outcome for a VM node event the plan IR could not route — bounded route/escalate answer only.',
+    candidatePolicy: 'node-outcomes-plus-escalate',
+    hardConstraints: ['data-only-no-tool-dispatch'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'frozen-conservative-fallback',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    instruction:
+      'A VM node event did not match any plan selector. Choose the node outcome, or escalate to the deterministic lane.',
+    candidates: ['completed', 'failed', 'cancelled', 'escalate'],
+  },
+  {
+    decisionKey: 'runtime.node_classify.v1',
+    schemaVersion: 1,
+    family: 'runtime',
+    owner: 'vmEngine',
+    kind: 'choice',
+    description: 'Bounded node-declared classification for an unclassifiable VM event; candidates come from the node question block.',
+    candidatePolicy: 'node-declared-candidates',
+    hardConstraints: ['data-only-no-tool-dispatch'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'frozen-conservative-fallback',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    instruction:
+      'Classify this unclassifiable VM node event into exactly one of the node-declared candidates.',
+    candidates: ['completed', 'failed', 'escalate'],
+  },
 ]);
 
 // Decision→fallback action map (frozen, SPEC §4). Fallbacks are conservative:
@@ -92,6 +132,9 @@ const FALLBACK_ACTIONS = Object.freeze({
   'runtime.stall_action.v1': 'continue_observe',
   'runtime.wake_needed.v1': 'escalate',
   'runtime.safe_retry.v1': 'no_retry',
+  // VM decision nodes fail closed onto the deterministic escalation lane.
+  'runtime.node_route.v1': 'escalate',
+  'runtime.node_classify.v1': 'escalate',
 });
 
 // Batch-level statuses → fallback codes. 'abstained' stays distinct so
@@ -135,22 +178,37 @@ function buildStatePacket(item) {
     decisionKey: item.decisionKey ?? null,
     reason: item.reason ?? null,
     eventType: item.event?.eventType ?? item.eventType ?? null,
+    nodeId: typeof item.nodeId === 'string' ? item.nodeId : null,
+    planInstanceId:
+      typeof item.planInstanceId === 'string' ? item.planInstanceId : null,
   };
 }
 
 function buildQuestion(item, entry) {
+  // A node-declared question block may override the registered instruction/
+  // candidates — it is still a bounded choice against one registered key.
+  const instruction =
+    typeof item.instruction === 'string' && item.instruction.length > 0
+      ? item.instruction
+      : typeof entry.instruction === 'string' && entry.instruction.length > 0
+        ? entry.instruction
+        : `Decide ${entry.decisionKey} for the described runtime event.`;
+  const candidates =
+    Array.isArray(item.candidates) && item.candidates.length > 0
+      ? item.candidates
+      : Array.isArray(entry.candidates)
+        ? entry.candidates
+        : [];
   return {
     decisionKey: entry.decisionKey,
     schemaVersion: entry.schemaVersion ?? 1,
     kind: entry.kind,
-    instruction:
-      typeof entry.instruction === 'string' && entry.instruction.length > 0
-        ? entry.instruction
-        : `Decide ${entry.decisionKey} for the described runtime event.`,
-    candidates: Array.isArray(entry.candidates) ? entry.candidates : [],
+    instruction,
+    candidates,
   };
 }
 
+
 /**
  * @param {{client: {requestBatch: Function}, registry?: object,
  *          confidenceFloor?: number|object, now?: Function}} options
@@ -240,3 +298,123 @@ export function createRuntimeDecider({
 
   return { decide };
 }
+
+// ---------------------------------------------------------------------------
+// V-05 — VM decision nodes (agent-vm-runtime V5): a classifyFn for vmEngine
+// that asks one bounded runtime.node_route.v1 / runtime.node_classify.v1
+// question per unclassifiable event. The model answer is data only — the
+// client's tool_calls envelope is consumed as an answer list, NEVER
+// dispatched. Every failure mode maps to the deterministic escalation lane
+// with a fallbackCode; this adapter never throws.
+
+// Registry keys a VM decision node may ask — anything else resolves to the
+// deterministic escalation lane without touching the gateway.
+export const VM_NODE_DECISION_KEYS = Object.freeze([
+  'runtime.node_route.v1',
+  'runtime.node_classify.v1',
+]);
+const DEFAULT_NODE_DECISION_KEY = VM_NODE_DECISION_KEYS[0];
+
+// Node question-block bounds — keeps a bounded choice small enough to stay
+// inside the state/question budget.
+const MAX_NODE_CANDIDATES = 8;
+const MAX_NODE_QUESTION_TEXT = 240;
+
+function isShortString(value) {
+  return typeof value === 'string'
+    && value.length > 0
+    && value.length <= MAX_NODE_QUESTION_TEXT;
+}
+
+// A node question block is valid only when every declared field is
+// well-formed; a malformed block is rejected wholesale (never partially
+// honored) so a bad plan cannot smuggle an unbounded question.
+function validNodeQuestion(question) {
+  return isPlainObject(question)
+    && (question.decisionKey === undefined || isShortString(question.decisionKey))
+    && (question.instruction === undefined || isShortString(question.instruction))
+    && (question.candidates === undefined
+      || (Array.isArray(question.candidates)
+        && question.candidates.length > 0
+        && question.candidates.length <= MAX_NODE_CANDIDATES
+        && question.candidates.every(isShortString)));
+}
+
+/**
+ * Build a vmEngine-compatible `classifyFn(event, ctx)` backed by the decision
+ * plane. Returns only `{action:'route', outcome}` / `{action:'escalate',
+ * fallbackCode?}` verdicts — model unavailability, timeouts, malformed
+ * answers, and adapter faults all resolve to the deterministic escalation
+ * lane with a `fallbackCode`, and the function NEVER throws.
+ *
+ * @param {{client?: {requestBatch: Function}, decider?: {decide: Function},
+ *          registry?: object, confidenceFloor?: number|object}} options
+ *   `decider` wins over `client` (a custom decider composes its own client).
+ *   Neither present → every call escalates 'unavailable' with zero I/O.
+ */
+export function createVmClassifyFn({
+  client,
+  decider,
+  registry,
+  confidenceFloor,
+} = {}) {
+  const resolvedDecider =
+    decider
+    ?? (client != null
+      ? createRuntimeDecider({ client, registry, confidenceFloor })
+      : null);
+
+  return async function vmClassify(event, ctx = {}) {
+    try {
+      const node = isPlainObject(ctx?.node) ? ctx.node : null;
+      const question = node?.question;
+      if (question !== undefined && !validNodeQuestion(question)) {
+        return { action: 'escalate', fallbackCode: 'malformed-question' };
+      }
+      const decisionKey = question?.decisionKey ?? DEFAULT_NODE_DECISION_KEY;
+      if (!VM_NODE_DECISION_KEYS.includes(decisionKey)) {
+        return { action: 'escalate', fallbackCode: 'unregistered-key' };
+      }
+      if (!resolvedDecider || typeof resolvedDecider.decide !== 'function') {
+        return { action: 'escalate', fallbackCode: 'unavailable' };
+      }
+
+      const decision = await resolvedDecider.decide({
+        action: 'model_decision',
+        decisionKey,
+        reason: `vm_unrouted:${String(event?.eventType ?? 'unknown')}`,
+        event: isPlainObject(event) ? event : null,
+        nodeId: typeof ctx?.nodeId === 'string' ? ctx.nodeId : null,
+        planInstanceId:
+          typeof ctx?.planInstanceId === 'string' ? ctx.planInstanceId : null,
+        ...(isShortString(question?.instruction)
+          ? { instruction: question.instruction }
+          : {}),
+        ...(Array.isArray(question?.candidates)
+          ? { candidates: question.candidates }
+          : {}),
+      });
+
+      if (!isPlainObject(decision)) {
+        return { action: 'escalate', fallbackCode: 'invalid' };
+      }
+      if (decision.decidedBy === 'fallback') {
+        return { action: 'escalate', fallbackCode: decision.code ?? 'invalid' };
+      }
+      const outcome = decision.action ?? decision.value;
+      if (outcome === 'escalate') {
+        return { action: 'escalate', decisionKey };
+      }
+      if (typeof outcome !== 'string' || outcome.length === 0) {
+        return { action: 'escalate', fallbackCode: 'invalid' };
+      }
+      // The engine's transition table still gates the outcome — an undeclared
+      // value fails closed to recovery_required downstream, never silently.
+      return { action: 'route', outcome, decisionKey };
+    } catch {
+      // Any adapter fault (bad ctx shape, throwing decider impl) resolves to
+      // the same deterministic lane — decision nodes never hard-fail the VM.
+      return { action: 'escalate', fallbackCode: 'adapter-error' };
+    }
+  };
+}

package/src/learning/selfImprove.js

@@ -0,0 +1,205 @@
+// selfImprove.js — the automatic collect → learn → apply cycle (3.3.0).
+//
+// One bounded pass that turns what hooks already record into memory,
+// diagnostics, tuning, and the flight recorder — no human command needed.
+// Triggered detached by `.claude/ukit/runtime/self-improve-trigger.mjs` from
+// Claude SessionEnd, omp session_stop, and route-task.mjs (the Codex helper
+// path), and runnable by hand via `ukit self-improve`.
+//
+// Steps (each isolated: one failing step never skips the others):
+//   1. episodes   — backfill an episode record for every idle exec-ledger
+//   2. diagnostics — failure patterns, feedback events, skill accuracy
+//   3. tuning     — compute suggestions; applyMode 'auto' applies them as
+//                   clamped one-step changes in learning/tuned.json, with a
+//                   per-key cooldown so one noisy window cannot ratchet a
+//                   value across its whole range
+//   4. proposals  — repeated failure patterns become PENDING memory
+//                   candidates (rules still need `ukit memory approve`)
+//   5. telemetry  — ingest stored hook/ledger telemetry, flush, refresh the
+//                   support view
+//
+// Guards: `.ukit/storage/learning/self-improve.json` stamp rate-limits the
+// pass (minIntervalMs, default 10 min) and a file lock keeps two triggers from
+// overlapping. Never throws.
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { inspectRuntimeConfig } from '../core/runtimeConfig.js';
+import { withFileLock } from '../core/fileOps.js';
+import { detectProjectContext } from '../context/detectProjectContext.js';
+import { backfillEpisodes } from '../core/memory/episodes.js';
+import { mineFailurePatterns } from '../diagnostics/failurePatterns.js';
+import { collectFeedbackEvents } from '../diagnostics/feedbackEvents.js';
+import { collectSkillAccuracy } from '../diagnostics/skillAccuracy.js';
+import { computeTuningSuggestions } from './tuning.js';
+import { proposeFromPatterns } from './patternProposals.js';
+import {
+  TUNABLE_KEYS,
+  clampTunable,
+  readTunedDocument,
+  resolveApplyMode,
+  writeTunedDocument,
+} from './tunedOverlay.js';
+
+export const STAMP_REL = path.join('.ukit', 'storage', 'learning', 'self-improve.json');
+export const DEFAULT_MIN_INTERVAL_MS = 10 * 60 * 1000;
+// A tuned key moves at most one step per cooldown window.
+export const TUNING_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+const TELEMETRY_DEADLINE_MS = 30_000;
+const FLUSH_DEADLINE_MS = 10_000;
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function writeJsonAtomic(filePath, value) {
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  try {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`);
+    await fs.rename(tmp, filePath);
+  } catch {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+  }
+}
+
+async function step(name, fn) {
+  try {
+    return { name, ...(await fn()) };
+  } catch (error) {
+    return { name, status: 'failed', reason: error?.message ?? String(error) };
+  }
+}
+
+// Applies tuning suggestions to the overlay. Pure over its inputs apart from
+// the overlay write, so it is testable without the rest of the cycle.
+export async function applyTuning(projectRoot, suggestions, { now = Date.now() } = {}) {
+  const doc = (await readTunedDocument(projectRoot))
+    ?? { overrides: {}, lastAppliedAt: {}, history: [] };
+  const applied = [];
+  for (const suggestion of Array.isArray(suggestions) ? suggestions : []) {
+    const key = suggestion?.target;
+    if (!TUNABLE_KEYS[key]) continue;
+    const last = Number(doc.lastAppliedAt[key]);
+    if (Number.isFinite(last) && now - last < TUNING_COOLDOWN_MS) continue;
+    const value = clampTunable(key, suggestion.suggested);
+    if (value === null || doc.overrides[key] === value) continue;
+    const from = doc.overrides[key] ?? suggestion.current ?? null;
+    doc.overrides[key] = value;
+    doc.lastAppliedAt[key] = now;
+    doc.history.push({
+      at: new Date(now).toISOString(),
+      key,
+      from,
+      to: value,
+      reason: suggestion?.evidence?.reason ?? null,
+    });
+    applied.push({ key, from, to: value });
+  }
+  if (applied.length > 0) {
+    doc.history = doc.history.slice(-50);
+    await writeTunedDocument(projectRoot, doc);
+  }
+  return applied;
+}
+
+async function collectTelemetry(projectRoot, config) {
+  const { resolveStage } = await import('../core/observability/emit/config.js');
+  if (resolveStage(config) === 'off') return { status: 'skipped', reason: 'stage_off' };
+  const { getRecorder, segmentsRoot } = await import('../core/observability/emit/lifecycle.js');
+  const { ingestStoredTelemetry } = await import('../core/observability/adapters/ingest.js');
+  const { maybeRefreshSupport } = await import('../core/observability/support/schedule.js');
+  await fs.mkdir(segmentsRoot(projectRoot), { recursive: true });
+  const recorder = getRecorder({ projectRoot, config });
+  const ingest = await ingestStoredTelemetry({ projectRoot, recorder, deadlineMs: TELEMETRY_DEADLINE_MS });
+  const flush = await recorder.flush({ deadlineMs: FLUSH_DEADLINE_MS });
+  const support = await maybeRefreshSupport({ projectRoot, config, recorder });
+  const emitted = Object.values(ingest?.coverage ?? {})
+    .reduce((sum, cov) => sum + (Number(cov?.emitted) || 0), 0);
+  return {
+    status: ingest?.ok === true ? ingest.status : 'failed',
+    emitted,
+    written: flush?.written ?? 0,
+    support: support?.status ?? 'unknown',
+  };
+}
+
+/**
+ * Run one self-improve pass.
+ * @param {string} projectRoot
+ * @param {{ force?: boolean, homeDir?: string, now?: number, minIntervalMs?: number }} [opts]
+ * @returns {Promise<{status: 'ran'|'skipped', reason?: string, steps?: object[]}>}
+ */
+export async function runSelfImprove(projectRoot, {
+  force = false,
+  homeDir = os.homedir(),
+  now = Date.now(),
+  minIntervalMs = DEFAULT_MIN_INTERVAL_MS,
+} = {}) {
+  const root = path.resolve(projectRoot);
+  const stampPath = path.join(root, STAMP_REL);
+  try {
+    const { config, rawConfig } = await inspectRuntimeConfig(root, { homeDir });
+    if (config?.learning?.selfImprove?.enabled === false) {
+      return { status: 'skipped', reason: 'disabled' };
+    }
+    const stamp = await readJson(stampPath);
+    const lastRunAt = Date.parse(stamp?.lastRunAt ?? '');
+    if (!force && Number.isFinite(lastRunAt) && now - lastRunAt < minIntervalMs) {
+      return { status: 'skipped', reason: 'min_interval' };
+    }
+
+    const outcome = await withFileLock(stampPath, async () => {
+      const steps = [];
+      steps.push(await step('episodes', async () => {
+        const res = await backfillEpisodes(root, { config, homeDir, now });
+        return { status: res.reason ? 'skipped' : 'ok', ...res };
+      }));
+      steps.push(await step('diagnostics', async () => {
+        const patterns = await mineFailurePatterns(root);
+        const feedback = await collectFeedbackEvents(root);
+        const skills = await collectSkillAccuracy(root);
+        return {
+          status: 'ok',
+          patterns: Array.isArray(patterns?.patterns) ? patterns.patterns.length : 0,
+          feedbackEvents: Array.isArray(feedback?.events) ? feedback.events.length : 0,
+          skills: Object.keys(skills?.skills ?? {}).length,
+        };
+      }));
+      steps.push(await step('tuning', async () => {
+        const result = await computeTuningSuggestions(root);
+        const mode = resolveApplyMode(rawConfig ?? {});
+        const applied = mode === 'auto' ? await applyTuning(root, result.suggestions, { now }) : [];
+        return { status: 'ok', mode, suggestions: result.suggestions.length, applied };
+      }));
+      steps.push(await step('proposals', async () => {
+        const projectId = (await detectProjectContext(root, { homeDir })).project.name;
+        const minCount = Number(config?.learning?.proposals?.minCount) || undefined;
+        const res = await proposeFromPatterns(root, projectId, { minCount, dryRun: false });
+        return {
+          status: res.error ? 'failed' : 'ok',
+          proposed: res.proposed.filter((p) => p.status === 'proposed').length,
+          reason: res.error,
+        };
+      }));
+      steps.push(await step('telemetry', () => collectTelemetry(root, config)));
+
+      await writeJsonAtomic(stampPath, {
+        lastRunAt: new Date(now).toISOString(),
+        steps,
+      });
+      return steps;
+    }, { maxWaitMs: 500 });
+
+    if (outcome === undefined) return { status: 'skipped', reason: 'locked' };
+    return { status: 'ran', steps: outcome };
+  } catch (error) {
+    return { status: 'skipped', reason: error?.message ?? String(error) };
+  }
+}

package/src/learning/tunedOverlay.js

@@ -0,0 +1,112 @@
+// tunedOverlay.js — auto-applied tuning overlay (learning.tuning.applyMode 'auto').
+//
+// The self-improve cycle writes clamped one-step tuning changes to
+// `.ukit/storage/learning/tuned.json`; runtime config readers merge the
+// overlay over the project config. The file lives outside the install-managed
+// `config.json`, so a reinstall never erases learned values, and deleting the
+// file (or setting applyMode 'manual'|'off') is a complete rollback.
+//
+// Contract:
+//   * Only TUNABLE_KEYS are honored; every value is clamped to its bounds on
+//     read, so a hand-edited or corrupt overlay can never push a key outside
+//     the range the tuner itself is allowed to reach.
+//   * Never throws: missing/corrupt overlay → no overrides.
+//   * Merge point: inspectRuntimeConfig (src/core/runtimeConfig.js) applies
+//     the overlay after the user+project merge, before defaults/validation.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const TUNED_REL = path.join('.ukit', 'storage', 'learning', 'tuned.json');
+export const TUNED_VERSION = 1;
+
+export const TUNABLE_KEYS = Object.freeze({
+  'codeIntel.retriever.weights.exact': { min: 0.1, max: 2.0 },
+  'codeIntel.retriever.weights.symbol': { min: 0.1, max: 2.0 },
+  'codeIntel.retriever.weights.bm25': { min: 0.1, max: 2.0 },
+  'codeIntel.retriever.weights.semantic': { min: 0.1, max: 2.0 },
+  'codeIntel.retriever.weights.vector': { min: 0.1, max: 2.0 },
+  'orchestration.escalation.debugLoopThreshold': { min: 1, max: 5, integer: true },
+});
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function clampTunable(key, value) {
+  const spec = TUNABLE_KEYS[key];
+  if (!spec || typeof value !== 'number' || !Number.isFinite(value)) return null;
+  const clamped = Math.min(spec.max, Math.max(spec.min, value));
+  return spec.integer ? Math.round(clamped) : Math.round(clamped * 100) / 100;
+}
+
+export function sanitizeOverrides(raw) {
+  const out = {};
+  if (!isPlainObject(raw)) return out;
+  for (const [key, value] of Object.entries(raw)) {
+    const clamped = clampTunable(key, value);
+    if (clamped !== null) out[key] = clamped;
+  }
+  return out;
+}
+
+export async function readTunedDocument(projectRoot) {
+  try {
+    const doc = JSON.parse(await fs.readFile(path.join(projectRoot, TUNED_REL), 'utf8'));
+    if (!isPlainObject(doc)) return null;
+    return {
+      version: TUNED_VERSION,
+      overrides: sanitizeOverrides(doc.overrides),
+      lastAppliedAt: isPlainObject(doc.lastAppliedAt) ? doc.lastAppliedAt : {},
+      history: Array.isArray(doc.history) ? doc.history.slice(-50) : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function writeTunedDocument(projectRoot, doc) {
+  const filePath = path.join(projectRoot, TUNED_REL);
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  try {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(tmp, `${JSON.stringify({ ...doc, version: TUNED_VERSION }, null, 2)}\n`);
+    await fs.rename(tmp, filePath);
+    return true;
+  } catch {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    return false;
+  }
+}
+
+// Resolves the effective apply mode from a raw (pre-default) config object:
+// absent → 'auto' (the shipped default).
+export function resolveApplyMode(rawConfig) {
+  const tuning = rawConfig?.learning?.tuning;
+  if (tuning?.enabled === false) return 'off';
+  const mode = tuning?.applyMode;
+  return mode === 'manual' || mode === 'off' || mode === 'auto' ? mode : 'auto';
+}
+
+// Returns a copy of `config` with `overrides` set at their dotted paths.
+export function applyOverrides(config, overrides) {
+  if (!isPlainObject(overrides) || Object.keys(overrides).length === 0) return config;
+  const next = structuredClone(isPlainObject(config) ? config : {});
+  for (const [key, value] of Object.entries(overrides)) {
+    const parts = key.split('.');
+    let node = next;
+    for (const part of parts.slice(0, -1)) {
+      if (!isPlainObject(node[part])) node[part] = {};
+      node = node[part];
+    }
+    node[parts[parts.length - 1]] = value;
+  }
+  return next;
+}
+
+// Merge helper for config readers: overlay applies only in 'auto' mode.
+export async function mergeTunedOverlay(projectRoot, rawConfig) {
+  if (resolveApplyMode(rawConfig) !== 'auto') return rawConfig;
+  const doc = await readTunedDocument(projectRoot);
+  return doc ? applyOverrides(rawConfig, doc.overrides) : rawConfig;
+}

package/template_project/.claude/hooks/session-episode.sh

@@ -112,25 +112,45 @@ try {
 const config = readJson(configPath) || {};
 if (config?.learning?.episodes?.autoWrite !== true) process.exit(0);
 
-const probe = spawnSync("ukit", ["--version"], {
-  shell: true, stdio: "ignore", timeout: 2000,
-});
-if (probe.error || probe.status === null || probe.status === undefined) process.exit(0);
-
 const sessionId = typeof payload.session_id === "string" && payload.session_id.trim()
   ? payload.session_id.trim()
   : null;
 
-spawnSync("ukit", ["memory", "episode"], {
-  shell: true,
-  stdio: "ignore",
-  timeout: 4000,
-  cwd: projectRoot,
-  env: sessionId
-    ? { ...process.env, UKIT_SESSION_ID: sessionId }
-    : process.env,
-});
-' "$UKIT_INPUT_FILE" "$CONFIG_FILE" "$PROJECT_ROOT" 2>/dev/null || true
+(async () => {
+  // 3.3.0: prefer the absolute node + CLI recorded by `ukit install`
+  // (.ukit/storage/cli.json, validated by resolveCliLocator) — GUI-launched
+  // hosts often lack nvm/volta on PATH, which made the bare `ukit` spawn fail
+  // silently. PATH lookup stays the fallback for pre-locator installs.
+  let trigger = null;
+  try {
+    trigger = await import(require("url").pathToFileURL(process.argv[4]).href);
+  } catch {}
+  const located = trigger?.resolveCliLocator?.(projectRoot) ?? null;
+  const cli = located
+    ? { cmd: located.node, pre: [located.bin], shell: false }
+    : { cmd: "ukit", pre: [], shell: true };
+
+  const probe = spawnSync(cli.cmd, [...cli.pre, "--version"], {
+    shell: cli.shell, stdio: "ignore", timeout: 2000,
+  });
+  if (probe.error || probe.status === null || probe.status === undefined) return;
+
+  spawnSync(cli.cmd, [...cli.pre, "memory", "episode"], {
+    shell: cli.shell,
+    stdio: "ignore",
+    timeout: 4000,
+    cwd: projectRoot,
+    env: sessionId
+      ? { ...process.env, UKIT_SESSION_ID: sessionId }
+      : process.env,
+  });
+
+  // Detached self-improve pass (episode backfill for sessions whose stop id
+  // did not match their ledger, diagnostics, auto-tuning, telemetry
+  // collect). Returns in ms; rate-limited inside the trigger.
+  trigger?.triggerSelfImprove?.({ projectRoot });
+})().catch(() => {}).finally(() => process.exit(0));
+' "$UKIT_INPUT_FILE" "$CONFIG_FILE" "$PROJECT_ROOT" "$SCRIPT_DIR/../ukit/runtime/self-improve-trigger.mjs" 2>/dev/null || true
 
 rm -f "$UKIT_INPUT_FILE" 2>/dev/null || true
 exit 0

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

@@ -1722,6 +1722,19 @@ async function main() {
   }
 
   printRouteState(sharedState);
+
+  // 3.3.0: Codex has no hook lifecycle — route-task is the one helper it runs
+  // per task, so it doubles as the self-improve trigger there. Fire-and-forget:
+  // detached child, rate-limited inside the trigger, never throws. Opt out
+  // with UKIT_SELF_IMPROVE=0 (tests/CI) or learning.selfImprove.enabled:false.
+  if (process.env.UKIT_SELF_IMPROVE !== '0') {
+    try {
+      const { triggerSelfImprove } = await import('../runtime/self-improve-trigger.mjs');
+      triggerSelfImprove({ projectRoot: rootDir });
+    } catch {
+      // background work only — a missing/broken trigger never affects routing
+    }
+  }
 }
 
 async function ensureFreshIndex({ rootDir, logPrefix, signal = null, deadlineMs = null, discoverySnapshot = null } = {}) {

package/template_project/.claude/ukit/index/unic-decision.mjs

@@ -718,8 +718,7 @@ export async function requestBatch(batch, {
 
     const status = res?.status ?? (res?.ok === false ? 500 : 200);
     if (res?.ok === false || status < 200 || status >= 300) {
-      // A variant checkpoint without bound credentials (e.g.
-      // unic-decision-multilingual before provider binding) returns a 4xx
+      // A checkpoint without bound credentials returns a 4xx
       // model_not_found body — retry once on the bare `unic-decision` model.
       if (checkpoint !== 'unic-decision') {
         let notFound = status === 404;