@ngockhoale/ukit 3.1.9 → 3.2.0

package/CHANGELOG.md

@@ -2,10 +2,24 @@
 
 All notable changes to UKit are documented here.
 
+## 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.2.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/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/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();
+}