@ngockhoale/ukit 3.1.9 → 3.3.0

package/CHANGELOG.md

@@ -2,10 +2,37 @@
 
 All notable changes to UKit are documented here.
 
+## 3.3.0 - 2026-09-27
+
+**Zero-config self-improvement: every feature stage ships on, UKit collects and learns from its own data.** Fixes the gap where 2.6.8–3.2.0 built the machinery (flight recorder, memory v2, learning, decision plane) but nothing on the live hook path fed it — measured 1 telemetry record and 0 memory-v2 records after days of use.
+
+- **`ukit self-improve` — the automatic collect → learn → apply pass** (`src/learning/selfImprove.js`, `src/cli/commands/selfImprove.js`). One bounded, rate-limited (10 min), lock-guarded pass that runs after every session: (1) backfills an episode for every idle exec-ledger — engine-agnostic, fixes omp session-id mismatch and Codex having no lifecycle hooks; (2) refreshes diagnostics (failure patterns, feedback, skill accuracy); (3) computes tuning suggestions and **auto-applies** them under `learning.tuning.applyMode: 'auto'` (new default) as clamped one-step moves into `.ukit/storage/learning/tuned.json` with a 24h per-key cooldown; (4) writes repeated failure patterns as pending pattern candidates (promotion still needs `ukit memory approve`); (5) ingests stored hook/ledger telemetry, flushes, refreshes the support view. Never throws; each step isolated.
+- **`self-improve-trigger.mjs`** (`template_project/.claude/ukit/runtime/`): fire-and-forget launcher called from Claude `SessionEnd`/`session-episode.sh`, omp `session_stop` via the bridge, and Codex `route-task.mjs` (its only per-task entry). Detached child, returns in ms, silent no-op on any failure; opt out via `learning.selfImprove.enabled: false` or `UKIT_SELF_IMPROVE=0`.
+- **CLI locator** (`.ukit/storage/cli.json`, `writeCliLocator` in `metadata.js`, written by `ukit install`): absolute node + bin paths so hooks spawning the CLI work on GUI-launched hosts whose PATH lacks nvm/volta. `resolveCliLocator` validates node basename, `bin/ukit` shape and `@ngockhoale/ukit` package identity before trusting it; PATH lookup stays the fallback.
+- **All stage flags default on**: `routing.*` → `default`; `memoryV2.decision` → `default`; `learning.candidates`/`overlays` → `default`; `continuity.resumableRun` → `default`; `decisionRuntime.*` → `shadow` (diagnostics → `default`); `experiments.deliberation`/`dynamicWorkflow` → enabled; `observability.stage` added to code defaults (`default`). `learning.tuning.applyMode` accepts `'auto'`; tuned overlay merges via `inspectRuntimeConfig`. Rollback: per-key `stage: "off"`, `applyMode: 'manual'`, or delete `tuned.json`.
+- **`ukit memory episode` refactored** onto shared `src/core/memory/episodes.js` (`resolveLedger`, `episodeText`, `writeEpisode`, `backfillEpisodes`) — one owner for the record shape between the single-session command and the self-improve backfill.
+- Tests: 28 new (tunedOverlay clamp/merge/cooldown, episodes resolve/write/backfill dedupe, trigger locator validation + spawn contract); stale stage-default pins updated to the 3.3.0 contract.
+
+
+
+## 3.2.0 - 2026-09-26
+
+**Agent VM / Language-Compiled Runtime phase 2 (V-01..V-06)** — IR v2 flag-gated opcodes, decisionRuntime.vm stage-promotion machinery, plan library pins, VM decision nodes via unic-decision, host parity adapters, sanitized support bundle. All new surfaces ship `off`.
+
+- **Host lane adapters for the owned runner (agent-vm-runtime V2).** `adapters.js` gains the frozen `HOST_ADAPTERS` registry plus `detectHost` (env-marker best-effort ambient engine resolution, ambiguous → `null`) and `probeHostAdapter` — honest per-host capability statuses `supported` / `unsupported-probe` / `unsupported` with typed reasons (`unknown_host`, `process_group_kill_unavailable`, `host_spawn_unavailable`, `live_host_e2e_unproven`); `supported` is reachable only via explicit `liveHostE2E` evidence, never inferred from primitive presence (G-V2). `buildHostCapabilityMap` in `runtimeSupport.js` exposes the map per lane; every lane reports `completionApi: 'eventStore-journal'` — no engine exposes a host-owned durable completion API. `createSupervisor` accepts `opts.host` and per-launch `spec.host` (precedence spec → opts → ambient detect → no lane); a lane probed `unsupported` refuses `start()` typed (`host_unknown`/`host_unsupported`, zero fs writes) while `unsupported-probe` lanes still run the identical spawn → journal → terminal contract. Live-E2E gap for claude-code/codex is documented in the task file — never claimed as supported.
+- **Agent VM V-01 — IR v2 flag gate + versioned IR contract.** IR v2 ops (`PARALLEL`, `TIMEOUT`) now parse only behind an explicit opt-in — `ir.planVersion: 'v2'` on the artifact, `opts.irVersion: 'v2'` on `compilePlan`, a caller `allowedOps` list naming them, or a non-`off` `decisionRuntime.vm` stage forwarded by `planLibrary.loadPlan({config})`. Ungated v2 IR fails with `ir_v2_disabled`; unknown version literals fail `invalid_ir_version`. `contract.js` exports `IR_VERSIONS` (`['v1','v2']`) and `ValidatedPlan` carries `irVersion` derived from ops actually used — v1 plans compile byte-identical under every flag state (planVersion unchanged). RETRY lands as the bounded per-node `retry` policy (side-effect-class aware: non-auto-retryable classes can never claim `maxAttempts > 1`; a crashed non-idempotent node stays `recovery_required` and is never re-run blind). New fault coverage: TIMEOUT firing mid-node on deliver → deterministic `escalate` replay-identically; duplicate delivery at the join is idempotent across a crash (single `completed` fold in the wrapper journal); bounded fan-out honors `maxNodes`.
+
+- **V4 plan library: release pinning + spec text.** `planLibrary.loadPlan` now returns `specText` (the human-authored spec each plan was compiled from) and `planVersion`, and enforces `PLAN_PINS` — a shipped plan whose compiled hash drifts from its pin fails with `plan_version_mismatch` instead of silently running a different workflow. Fourth reference plan `flag-promotion` (stage-promotion gate: baseline replay → shadow runs → promote/rollback branch, mirroring `promotion.js`) joins `bugfix-loop`, `handoff-review-batch`, `release-check`. Coverage: artifact-hash stability, vmEngine replay determinism per plan, malformed-artifact rejection, pin drift.
+- **VM decision nodes via `unic-decision` (agent-vm-runtime V5).** `vmEngine` nodes may now carry a bounded `question` block (`{decisionKey?, instruction?, candidates?}`, validated by `validateNodeQuestion` in `contract.js` and carried through `planCompiler`). When `decisionRuntime.vm.stage` is promoted past `off` and no `classifyFn` is injected, unclassifiable events are routed by `createVmClassifyFn` (`src/decision/runtimeDecide.js`) through one bounded `runtime.node_route.v1` / `runtime.node_classify.v1` question — the only two keys a node may ask (registered `rolloutStage: 'off'`, owner `vmEngine`, deterministic escalate fallback). Model answers are data only (`tool_calls` never dispatched); `model_not_found`/timeout/invalid/adapter faults all resolve to the deterministic escalation lane with a `fallbackCode`, never a hard failure — a throwing `classifyFn` now escalates too. Stage `off` (default, absent, or malformed) installs no adapter: zero decision calls, byte-identical behaviour.
+
+- **Agent VM V-06 — per-run support bundle** (`src/core/agentRuntime/diagnostics.js` `exportSupportBundle`, `eventStore.js` `readJournalExcerpt` + `summarizeEvent`, `telemetry.js` `buildTraceExcerpt`, `ukit telemetry export-run <operationId>`): one sanitized bundle per operation lands in the Data Foundation support layout — `Documents/UKit Support/proj-<sha256>/run-<sha256>/` with `journal.jsonl` (bounded code summaries only), `trace.jsonl` (double-gated span excerpt, deterministic pseudonyms), `SUMMARY.md` and a `ukit-support/1` manifest with sha256 checksums, importable via `ukit telemetry import`. Privacy: redaction before persist — secret/path/PII rules + `sanitizeForSupport` on trace records + a final assembled-bytes re-scan that blocks all writes on any residual secret; no raw prompt/diff/path content can appear. `decisionRuntime.diagnostics.stage: 'off'` → `skipped` with zero writes. Missing/corrupt journals still emit bundles with declared `gap` markers; a 256 KiB cap drops excerpt lines deterministically (`coverage.dropped_lines`).
+
 ## 3.1.9 - 2026-09-26
 
 - **Checkpoint locked to `unic-decision` for all classes.** Owner decision: the single `unic-decision` model answers every decision (English, multilingual, unknown) — the provider swaps the backend (Lava/JEV) behind that name, so UKit no longer routes per-language. `checkpoints.{default,english,unknownLanguage}` all resolve to `unic-decision` in code + shipped config; `unic-decision-multilingual` removed from defaults (remains configurable via `decisionPlane.checkpoints` if ever needed). Endpoint config unchanged: `ukit decision` / `gatewayDecision.json` / `UKIT_DECISION_*` env.
 
+- **Agent VM V-03 — stage-promotion machinery** (`src/core/agentRuntime/promotion.js`, `src/core/runtimeConfig.js`): new `resolveDecisionRuntimeStage(config, key)` resolves `decisionRuntime.<key>.stage` with `decisionPlane` semantics (absent/malformed → `off`); new pure `promote(config, evidence)` advances one family flag `off → shadow → canary → default` only when the frozen `PROMOTION_CRITERIA` hold on ≥ `minSampledRuns` sampled runs (quality delta ≥ `-QUALITY_SCORE_FLOOR`, wall-p95 and cost ratios ≤ baseline), and instant rollback (`evidence.rollback` or any forbidden failure) resolves `off` — deterministic owners authoritative, zero VM calls. `off` never self-promotes and one noisy run never flips a default. All `decisionRuntime.*` stages stay `off`: machinery only, no rollout flip.
+
 ## 3.1.8 - 2026-09-26
 
 - **Agent VM IR v2**: `PARALLEL` (bounded fan-out, `join:'all'`) and `TIMEOUT` (deadline wrapper, `onTimeout: fail|escalate`, 30-minute ceiling) opcodes added to `planCompiler` + `vmEngine`; fault-injection coverage for crash-between-fan-out-and-join, non-idempotent child recovery, duplicate delivery. v2 plans hash under a `v2:`-prefixed serialization; v1 hashes unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.1.9",
+  "version": "3.3.0",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/cli/commands/memory.js

@@ -29,7 +29,7 @@ import { buildRuntimePaths } from '../../core/runtimePaths.js';
 import { buildUserPaths } from '../../core/userPaths.js';
 import { pathExists } from '../../core/fileOps.js';
 import { detectProjectContext } from '../../context/detectProjectContext.js';
-import { listLedgerFiles, LEDGER_DIR_REL } from '../../diagnostics/ledgerFiles.js';
+import { episodeText, resolveLedger, writeEpisode } from '../../core/memory/episodes.js';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -520,53 +520,8 @@ async function runMemoryPromote(projectRoot, homeDir, args) {
 }
 
 // ---- `ukit memory episode` — session episode from exec-ledger (SPEC §7b) ----
-
-// Mirrors execution-ledger.mjs safeSegment — src/ cannot import the runtime
-// module, so the segment rule is duplicated deliberately.
-function safeSegment(value) {
-  return String(value || 'default')
-    .trim()
-    .replace(/[^a-zA-Z0-9._-]/g, '_')
-    .slice(0, 96) || 'default';
-}
-
-async function readJsonIfExists(filePath) {
-  try {
-    return JSON.parse(await fs.readFile(filePath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-// Resolution order: --session <id> → UKIT_SESSION_ID env → most-recent ledger.
-async function resolveLedger(projectRoot, sessionFlag) {
-  const dir = path.join(projectRoot, LEDGER_DIR_REL);
-  const candidate = sessionFlag ?? process.env.UKIT_SESSION_ID;
-  if (candidate) {
-    const file = `${safeSegment(candidate)}.json`;
-    const ledger = await readJsonIfExists(path.join(dir, file));
-    return ledger ? { ledger, ledgerKey: file } : { ledger: null, ledgerKey: file };
-  }
-  const [name] = await listLedgerFiles(dir, 1);
-  if (!name) return { ledger: null, ledgerKey: null };
-  const ledger = await readJsonIfExists(path.join(dir, name));
-  return ledger ? { ledger, ledgerKey: name } : { ledger: null, ledgerKey: name };
-}
-
-function episodeText(ledger, sessionId) {
-  const write = ledger.writeSucceeded === true ? 'writeOk' : 'writeFail';
-  const verify = ledger.verificationAttempted !== true
-    ? 'not-run'
-    : ledger.verificationSucceeded === true ? 'ok' : 'fail';
-  const receipts = Array.isArray(ledger.receipts) ? ledger.receipts : [];
-  const lastReceipt = receipts.length > 0 ? receipts[receipts.length - 1] : null;
-  const lastCommand = lastReceipt
-    ? String(lastReceipt?.command ?? '').split('\n')[0].trim() || 'n/a'
-    : 'n/a';
-  const text = `Session ${sessionId}: ${write}, verify=${verify}, `
-    + `${receipts.length} receipts, last command ${lastCommand}`;
-  return text.slice(0, 300);
-}
+// Record shape + dedupe live in core/memory/episodes.js (shared with the
+// self-improve backfill).
 
 async function runMemoryEpisode(projectRoot, homeDir, args) {
   const dryRun = args.includes('--dry-run');
@@ -578,62 +533,31 @@ async function runMemoryEpisode(projectRoot, homeDir, args) {
     return;
   }
 
-  const { ledger, ledgerKey } = await resolveLedger(projectRoot, sessionFlag);
+  const { ledger, ledgerKey } = await resolveLedger(projectRoot, sessionFlag ?? process.env.UKIT_SESSION_ID);
   if (!ledger) {
     console.log('[UKit] episode: nothing to record');
     return;
   }
 
-  const sessionId = ledger.sessionId ?? ledger.sessionKey
-    ?? (ledgerKey ? ledgerKey.replace(/\.json$/, '') : 'unknown');
-  const text = episodeText(ledger, sessionId);
-
   if (dryRun) {
-    console.log(`[UKit] episode (dry-run): ${text}`);
-    return;
-  }
-
-  const existing = await loadRecords(projectRoot, { homeDir });
-  if (existing.some((r) => r.meta?.ledgerKey === ledgerKey)) {
-    console.log('[UKit] episode: already recorded');
+    const sessionId = ledger.sessionId ?? ledger.sessionKey ?? ledgerKey.replace(/\.json$/, '');
+    console.log(`[UKit] episode (dry-run): ${episodeText(ledger, sessionId)}`);
     return;
   }
 
-  const ttlDays = Number(config?.memoryV2?.episodeTtlDays) || 90;
-  const projectId = (await detectProjectContext(projectRoot, { homeDir })).project.name;
-  // FR-023: the add goes through mutateMemory with the ledger key as the
-  // idempotency key — a hook-invoked rerun is a journal 'duplicate' even if
-  // the meta.ledgerKey fast-path above is bypassed.
-  const res = await mutateMemory(
-    { kind: 'project', projectRoot, homeDir },
-    {
-      op: 'add',
-      idempotencyKey: ledgerKey,
-      payload: {
-        type: 'episode',
-        scope: 'session',
-        text,
-        provenance: 'exec-ledger',
-        confidence: 0.6,
-        createdBy: 'episode-hook',
-        projectId,
-        validUntil: Date.now() + ttlDays * 24 * 60 * 60 * 1000,
-        meta: { sessionId, ledgerKey },
-      },
-    },
-  );
+  const res = await writeEpisode(projectRoot, { ledger, ledgerKey, config, homeDir });
   if (res.status === 'duplicate') {
     console.log('[UKit] episode: already recorded');
     return;
   }
   if (res.status === 'rejected') {
-    printGuardRejection(res);
+    printGuardRejection(res.result);
     return;
   }
-  if (res.status !== 'ok') {
-    throw new Error(`episode write failed: ${res.status}${res.reason ? ` — ${res.reason}` : ''}`);
+  if (res.status !== 'recorded') {
+    throw new Error(`episode write failed: ${res.reason}`);
   }
-  console.log(`[UKit] episode: recorded ${res.record.id} for session ${sessionId}`);
+  console.log(`[UKit] episode: recorded ${res.id} for session ${res.sessionId}`);
 }
 
 // ---- `ukit memory backup|restore|doctor` — operator lane (SPEC §9, FR-011) ----

package/src/cli/commands/selfImprove.js

@@ -0,0 +1,55 @@
+// `ukit self-improve` — run the automatic collect → learn → apply pass now.
+// Hooks trigger it detached (self-improve-trigger.mjs); this is the manual
+// and the trigger's own entry point. `--if-due` honors the rate-limit stamp
+// (what triggers pass); without it the pass is forced.
+
+import { runSelfImprove } from '../../learning/selfImprove.js';
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+const KNOWN_FLAGS = new Set(['--if-due', '--json', '--quiet']);
+
+function printUsage() {
+  console.log('Usage: ukit self-improve [--if-due] [--json] [--quiet]');
+  console.log('');
+  console.log('Runs one self-improve pass: episode backfill, diagnostics, auto-tuning,');
+  console.log('pattern proposals, telemetry collect. Hooks run it automatically.');
+  console.log('');
+  console.log('  --if-due   Skip when the last pass ran < 10 minutes ago (hook mode)');
+  console.log('  --json     JSON output');
+  console.log('  --quiet    No output (hook mode)');
+}
+
+function describeStep(stepResult) {
+  const { name, status, ...rest } = stepResult;
+  const details = Object.entries(rest)
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([key, value]) => `${key}=${Array.isArray(value) ? value.length : value}`)
+    .join(' ');
+  return `  ${name}: ${status}${details ? ` ${details}` : ''}`;
+}
+
+export async function runSelfImproveCommand({ projectRoot, argv = [] }) {
+  if (argv.some((flag) => HELP_FLAGS.has(flag))) {
+    printUsage();
+    return;
+  }
+  const unknown = argv.filter((flag) => !KNOWN_FLAGS.has(flag));
+  if (unknown.length > 0) {
+    console.error(`[UKit] Unknown self-improve argument(s): ${unknown.join(', ')}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+  const result = await runSelfImprove(projectRoot, { force: !argv.includes('--if-due') });
+  if (argv.includes('--quiet')) return;
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.status !== 'ran') {
+    console.log(`[UKit] self-improve: skipped (${result.reason})`);
+    return;
+  }
+  console.log('[UKit] self-improve: ran');
+  for (const stepResult of result.steps) console.log(describeStep(stepResult));
+}

package/src/cli/commands/telemetry.js

@@ -42,7 +42,7 @@ import { validateSupportBundle } from '../../core/observability/support/import.j
 import { runEvaluation } from '../../core/observability/evaluation/runner.js';
 
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
-const SUBCOMMANDS = new Set(['collect', 'status', 'digest', 'export-support', 'import', 'evaluate']);
+const SUBCOMMANDS = new Set(['collect', 'status', 'digest', 'export-support', 'export-run', 'import', 'evaluate']);
 const JSON_SUBCOMMANDS = new Set(['status', 'digest', 'evaluate']);
 
 // The automatic support refresh's canary gate lives in schedule.js via
@@ -62,6 +62,7 @@ function printUsage() {
   console.log('  status           Show stage, segments, counters, support lag, crashes');
   console.log('  digest           Rebuild the trace index; print anomalies + digest markdown');
   console.log('  export-support   Write the sanitized UKit Support bundle now');
+  console.log('  export-run <op>  Write a sanitized per-run support bundle (V-06)');
   console.log('  import <path>    Validate a received support bundle (zip or directory)');
   console.log('  evaluate         Run the AI evaluator lane (needs observability.evaluator config)');
   console.log('');
@@ -370,6 +371,45 @@ async function exportSupportCommand({ projectRoot, config }) {
   process.exitCode = 2;
 }
 
+// --- export-run (V-06) -------------------------------------------------------
+
+/**
+ * `export-run <operationId>` — stage-gated per-operation support bundle.
+ * Unlike export-support this is NOT lifted past the stage gate: the
+ * bundle lives under decisionRuntime.diagnostics, and 'off' means zero
+ * writes by contract (SPEC G7-FR04).
+ */
+async function exportRunCommand({ projectRoot, config, operationId }) {
+  const { exportSupportBundle } = await import('../../core/agentRuntime/diagnostics.js');
+  const runtimeDir = path.join(projectRoot, '.ukit', 'storage', 'agent-runtime');
+  let res;
+  try {
+    res = await exportSupportBundle(runtimeDir, operationId, {
+      config,
+      projectKey: projectRoot,
+      traceRoot: segmentsRoot(projectRoot),
+    });
+  } catch {
+    res = { status: 'degraded', reason: 'bundle_error', bytes: 0 };
+  }
+  if (res.status === 'written') {
+    // Pseudonymous location only — the absolute path is user-private.
+    const proj = path.basename(path.dirname(res.dir));
+    const run = path.basename(res.dir);
+    console.log(
+      `export-run: written bytes=${res.bytes ?? 0} ` +
+        `dir=${SUPPORT_DIR_NAME}/${proj}/${run}`,
+    );
+    return;
+  }
+  console.log(
+    `export-run: ${res.status}` +
+      (res.reason ? ` reason=${res.reason}` : '') +
+      ` bytes=${res.bytes ?? 0}`,
+  );
+  process.exitCode = 2;
+}
+
 async function importCommand({ bundlePath }) {
   const res = await validateSupportBundle({ path: bundlePath });
   if (!res.ok) {
@@ -434,7 +474,7 @@ export async function runTelemetry({ projectRoot, packageRoot, argv = [] }) {
   const flags = rest.filter((a) => a.startsWith('-'));
   const allowed = JSON_SUBCOMMANDS.has(sub) ? new Set(['--json']) : new Set();
   const unknownFlags = flags.filter((f) => !allowed.has(f));
-  const maxPositional = sub === 'import' ? 1 : 0;
+  const maxPositional = (sub === 'import' || sub === 'export-run') ? 1 : 0;
 
   if (unknownFlags.length > 0) {
     console.error(`[UKit] Unknown telemetry flag(s): ${unknownFlags.join(', ')}`);
@@ -442,7 +482,8 @@ export async function runTelemetry({ projectRoot, packageRoot, argv = [] }) {
     process.exitCode = 1;
     return;
   }
-  if (positional.length > maxPositional || (sub === 'import' && positional.length === 0)) {
+  const wantsOperand = sub === 'import' || sub === 'export-run';
+  if (positional.length > maxPositional || (wantsOperand && positional.length === 0)) {
     printUsage();
     process.exitCode = 1;
     return;
@@ -455,6 +496,7 @@ export async function runTelemetry({ projectRoot, packageRoot, argv = [] }) {
   if (sub === 'status') return statusCommand({ projectRoot, config, json });
   if (sub === 'digest') return digestCommand({ projectRoot, json });
   if (sub === 'export-support') return exportSupportCommand({ projectRoot, config });
+  if (sub === 'export-run') return exportRunCommand({ projectRoot, config, operationId: positional[0] });
   if (sub === 'evaluate') return evaluateCommand({ projectRoot, config, json });
   return importCommand({ bundlePath: positional[0] });
 }

package/src/cli/index.js

@@ -12,6 +12,7 @@ import { runTelemetry } from './commands/telemetry.js';
 import { runFeedback } from './commands/feedback.js';
 import { runPlaybook } from './commands/playbook.js';
 import { runDecision } from './commands/decision.js';
+import { runSelfImproveCommand } from './commands/selfImprove.js';
 const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
 
 export async function runCli({ argv, packageRoot, projectRoot, packageVersion }) {
@@ -89,6 +90,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'self-improve') {
+    await runSelfImproveCommand({ projectRoot, argv: commandArgv });
+    return;
+  }
+
   if (command === 'update') {
     await runUpdate({ packageVersion, argv: commandArgv });
     return;
@@ -131,6 +137,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  metrics            Telemetry roll-up (route outcomes, failure patterns, memory)');
     console.log('  telemetry          Flight recorder (collect/status/digest/export-support/import/evaluate)');
     console.log('  feedback           Record or list wrong-route feedback labels');
+    console.log('  self-improve       Run the automatic learn/tune/collect pass now (hooks run it)');
     console.log('  update             Upgrade the global UKit CLI to the latest version');
     console.log('  version            Show UKit version');
     console.log('');

package/src/core/agentRuntime/adapters.js

@@ -27,12 +27,22 @@
  * recorder via telemetry.js — synchronous, never-throw, stage-gated
  * inside emit(). `now` and `artifactStore` are injectable for tests.
  *
+ * Host lane adapters (V-02, AGENT_VM_RUNTIME_PLAN item V2) live at the
+ * end of this module: HOST_ADAPTERS is the frozen capability registry
+ * for the owned-runner host lanes (omp / claude-code / codex),
+ * detectHost best-effort resolves the ambient engine session from env
+ * markers, and probeHostAdapter evaluates one lane against the current
+ * environment + injectable primitives — honest statuses only
+ * ('supported' | 'unsupported-probe' | 'unsupported'), never a faked
+ * supported.
+ *
  * `artifactStore` protocol (injected): `put(buffer)` →
  * `Promise<string | { path: string }>`; the returned ref is recorded on
  * `event.artifactRefs` and in the result `artifactRefs` list.
  */
 
 import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
 
 import {
   validateSemanticEvent,
@@ -333,3 +343,170 @@ export async function adaptOutput({
   }
   return { events: [event], artifactRefs, parseStatus };
 }
+
+// --- V-02: host lane adapters (AGENT_VM_RUNTIME_PLAN item V2) ---------
+// The owned runner (supervisor.js) is primitive-level identical on every
+// engine: Node child_process spawn, detached process-group kill, and
+// kill(pid, 0) liveness — UKit-owned children only; no engine's own
+// process lifecycle is hijacked. The lanes below describe that contract
+// per host honestly: no engine exposes a host-owned durable completion
+// API, so completionApi is UKit's own durable journal on every lane.
+//
+// Status ladder (G-V2 — never fake a completion signal):
+//   'supported'         — primitives present AND live host E2E evidence
+//                         was explicitly declared (opts.liveHostE2E).
+//                         Absent live evidence a probe never upgrades.
+//   'unsupported-probe' — the lane contract is available at the
+//                         primitive level but live host E2E has NOT
+//                         been proven in this environment. The owned
+//                         runner may launch; capability reports stay
+//                         honest about the evidence gap.
+//   'unsupported'       — a required primitive is absent (win32 process-
+//                         group kill, no spawnImpl, …) or the host is
+//                         unknown. Never runnable.
+
+export const HOST_NAMES = Object.freeze(['omp', 'claude-code', 'codex']);
+
+export const HOST_SUPPORTED = 'supported';
+export const HOST_UNSUPPORTED_PROBE = 'unsupported-probe';
+export const HOST_UNSUPPORTED = 'unsupported';
+
+// No engine exposes a host-owned durable completion API today; every
+// lane's durable completion channel is the eventStore journal.
+export const OWNED_COMPLETION_API = 'eventStore-journal';
+
+// Frozen per-lane descriptor — static contract only; environment truth
+// comes from probeHostAdapter, never from this table.
+export const HOST_ADAPTERS = Object.freeze({
+  'omp': Object.freeze({
+    name: 'omp',
+    completionApi: OWNED_COMPLETION_API,
+    ownedProcessGroups: true,
+  }),
+  'claude-code': Object.freeze({
+    name: 'claude-code',
+    completionApi: OWNED_COMPLETION_API,
+    ownedProcessGroups: true,
+  }),
+  'codex': Object.freeze({
+    name: 'codex',
+    completionApi: OWNED_COMPLETION_API,
+    ownedProcessGroups: true,
+  }),
+});
+
+// Documented session env markers for ambient engine detection. Explicit
+// identity always wins: UKIT_HOST, then UKIT_AGENT_ID, then the marker
+// sets — a hit in >1 marker set is ambiguous and resolves null (never a
+// guessed lane).
+const HOST_ENV_MARKERS = {
+  'omp': ['OMP_HOME', 'OMP_SESSION_ID', 'ORCA_OMP_SOURCE_AGENT_DIR'],
+  'claude-code': ['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT'],
+  'codex': ['CODEX_SANDBOX', 'CODEX_CI', 'ORCA_CODEX_HOME'],
+};
+
+/**
+ * Best-effort ambient host resolution.
+ * @param {object} [env] default process.env
+ * @returns {string|null} a HOST_NAMES member, or null when absent/ambiguous.
+ */
+export function detectHost(env = process.env) {
+  const source = env && typeof env === 'object' ? env : {};
+  const explicit = source.UKIT_HOST ?? source.UKIT_AGENT_ID;
+  if (typeof explicit === 'string' && HOST_ADAPTERS[explicit]) return explicit;
+  const hits = HOST_NAMES.filter(
+    (name) => HOST_ENV_MARKERS[name].some((key) => source[key] != null),
+  );
+  return hits.length === 1 ? hits[0] : null;
+}
+
+/**
+ * Evaluate one host lane against the current environment.
+ *
+ * @param {string} name lane name (HOST_NAMES member or arbitrary string)
+ * @param {object} [opts]
+ * @param {boolean} [opts.liveHostE2E] declare live host E2E evidence —
+ *   the ONLY path to 'supported'. Never derived from primitive presence.
+ * @param {Function} [opts.spawnImpl] required primitive (default Node spawn)
+ * @param {Function} [opts.killImpl] required primitive (default process.kill)
+ * @param {Function} [opts.probeImpl] required liveness primitive (default sig-0)
+ * @param {string} [opts.platform] default process.platform
+ * @returns {{name:string|null, supported:string, reason:string|null,
+ *   completionApi:string|null, primitives:object}}
+ */
+export function probeHostAdapter(name, opts = {}) {
+  const descriptor = HOST_ADAPTERS[name];
+  if (!descriptor) {
+    return {
+      name: null,
+      supported: HOST_UNSUPPORTED,
+      reason: 'unknown_host',
+      completionApi: null,
+      primitives: {},
+    };
+  }
+  const platform = typeof opts.platform === 'string' ? opts.platform : process.platform;
+  // `undefined` picks the Node defaults; any other non-function value is a
+  // caller-supplied (possibly deliberately absent) primitive — probes must
+  // evaluate what was given, never silently fall back.
+  const spawnImpl = opts.spawnImpl === undefined
+    ? (argv, spawnOpts) => spawn(argv[0], argv.slice(1), spawnOpts)
+    : opts.spawnImpl;
+  const killImpl = opts.killImpl === undefined
+    ? (signal, target) => process.kill(target, signal)
+    : opts.killImpl;
+  const probeImpl = opts.probeImpl === undefined
+    ? (pid) => {
+      try { process.kill(pid, 0); return true; } catch { return false; }
+    }
+    : opts.probeImpl;
+  const primitives = {
+    spawn: typeof spawnImpl === 'function',
+    processGroupKill: platform !== 'win32' && typeof killImpl === 'function',
+    livenessProbe: typeof probeImpl === 'function',
+  };
+  if (platform === 'win32') {
+    return {
+      name,
+      supported: HOST_UNSUPPORTED,
+      reason: 'process_group_kill_unavailable',
+      completionApi: descriptor.completionApi,
+      primitives,
+    };
+  }
+  if (!primitives.spawn || !primitives.livenessProbe || !primitives.processGroupKill) {
+    return {
+      name,
+      supported: HOST_UNSUPPORTED,
+      reason: 'host_spawn_unavailable',
+      completionApi: descriptor.completionApi,
+      primitives,
+    };
+  }
+  if (opts.liveHostE2E === true) {
+    return {
+      name,
+      supported: HOST_SUPPORTED,
+      reason: null,
+      completionApi: descriptor.completionApi,
+      primitives,
+    };
+  }
+  return {
+    name,
+    supported: HOST_UNSUPPORTED_PROBE,
+    reason: 'live_host_e2e_unproven',
+    completionApi: descriptor.completionApi,
+    primitives,
+  };
+}
+
+/**
+ * Probe every registered lane. Returns `{hostName: probe}` — one entry
+ * per HOST_NAMES member, in registry order.
+ */
+export function listHostAdapters(opts = {}) {
+  const out = {};
+  for (const name of HOST_NAMES) out[name] = probeHostAdapter(name, opts);
+  return out;
+}

package/src/core/agentRuntime/contract.js

@@ -52,6 +52,17 @@ export const SIDE_EFFECT_CLASSES = Object.freeze([
   'destructive',
 ]);
 
+// ---------------------------------------------------------------------------
+// V-01 — IR versioning (plan-language level, independent of CONTRACT_VERSION).
+
+/**
+ * Frozen IR versions understood by planCompiler. 'v1' is the original opcode
+ * set (RUN, WAIT_EVENT, BRANCH, COMPLETE, ESCALATE); 'v2' adds the wrapper
+ * ops PARALLEL and TIMEOUT. A plan opts into v2 via `ir.planVersion: 'v2'`
+ * or an enabled caller channel — v1 IR never parses v2 ops by default.
+ */
+export const IR_VERSIONS = Object.freeze(['v1', 'v2']);
+
 /** Classes that MAY auto-retry under bounded attempts + backoff (SPEC §5). */
 const AUTO_RETRYABLE = new Set(['pure', 'read_only', 'idempotent_write']);
 
@@ -245,3 +256,69 @@ export function validateRetry(sideEffectClass, attempt, policy = {}) {
 
   return ok();
 }
+
+// ---------------------------------------------------------------------------
+// V-05 — VM decision-node question block + classify verdict shapes.
+
+/** Verdict actions a classifyFn may return (agent-vm-runtime V5). */
+export const CLASSIFY_ACTIONS = Object.freeze(['route', 'escalate']);
+
+/**
+ * Validate a classifyFn verdict — the bounded decision-node answer shape:
+ * `{action:'route', outcome:string}` routes the event into the node's
+ * deterministic transition table (which still gates the outcome); any other
+ * valid verdict escalates onto the deterministic lane.
+ *
+ * @param {object} verdict
+ * @returns {{ok:true}|{ok:false, code:string}}
+ */
+export function validateClassifyVerdict(verdict) {
+  if (verdict === null || typeof verdict !== 'object' || Array.isArray(verdict)) {
+    return reject('malformed_verdict');
+  }
+  if (verdict.action === 'escalate') {
+    return ok();
+  }
+  if (verdict.action === 'route' && typeof verdict.outcome === 'string' && verdict.outcome.length > 0) {
+    return ok();
+  }
+  return reject('malformed_verdict');
+}
+
+/**
+ * Validate a VM node's optional `question` block — the bounded
+ * classify/select question the decision plane may answer when the plan IR
+ * cannot route an event. Absent is valid (nodes need not ask); a malformed
+ * block is rejected wholesale, never partially honored.
+ *
+ * @param {object} question `{decisionKey?, instruction?, candidates?}` —
+ *   each declared field must be a non-empty bounded string / string list.
+ * @param {object} [bounds] `{maxText?, maxCandidates?}`
+ * @returns {{ok:true}|{ok:false, code:string}}
+ */
+export function validateNodeQuestion(question, bounds = {}) {
+  if (question === undefined) {
+    return ok();
+  }
+  if (question === null || typeof question !== 'object' || Array.isArray(question)) {
+    return reject('malformed_question');
+  }
+  const maxText = Number.isInteger(bounds.maxText) && bounds.maxText > 0 ? bounds.maxText : 240;
+  const maxCandidates = Number.isInteger(bounds.maxCandidates) && bounds.maxCandidates > 0 ? bounds.maxCandidates : 8;
+  const bounded = (v) => typeof v === 'string' && v.length > 0 && v.length <= maxText;
+  if (question.decisionKey !== undefined && !bounded(question.decisionKey)) {
+    return reject('malformed_question');
+  }
+  if (question.instruction !== undefined && !bounded(question.instruction)) {
+    return reject('malformed_question');
+  }
+  if (question.candidates !== undefined) {
+    if (!Array.isArray(question.candidates)
+      || question.candidates.length === 0
+      || question.candidates.length > maxCandidates
+      || !question.candidates.every(bounded)) {
+      return reject('malformed_question');
+    }
+  }
+  return ok();
+}