@ngockhoale/ukit 3.1.9 → 3.3.0

package/src/core/agentRuntime/planCompiler.js

@@ -3,8 +3,9 @@
  *
  * Pure plan compiler: validates a small DAG IR (frozen opcode set: RUN,
  * WAIT_EVENT, BRANCH, COMPLETE, ESCALATE — plus IR v2 wrappers PARALLEL
- * and TIMEOUT) and emits an immutable
- * ValidatedPlan { planVersion, nodes, entryNodes, order }.
+ * and TIMEOUT, gated behind an explicit opt-in per the V-01 flag contract
+ * in compilePlan()) and emits an immutable
+ * ValidatedPlan { planVersion, irVersion, nodes, entryNodes, order }.
  *
  * No I/O, no runtimeConfig reads, no imports of vmEngine. The only
  * dependency is the read-only SIDE_EFFECT_CLASSES table from contract.js.
@@ -14,7 +15,7 @@
 
 import { createHash } from 'node:crypto';
 
-import { SIDE_EFFECT_CLASSES } from './contract.js';
+import { SIDE_EFFECT_CLASSES, IR_VERSIONS, validateNodeQuestion } from './contract.js';
 
 export const PLAN_OPS = Object.freeze([
   'RUN',
@@ -26,6 +27,9 @@ export const PLAN_OPS = Object.freeze([
   'TIMEOUT',
 ]);
 
+/** Ops that require an explicit IR v2 opt-in (V-01 flag gate). */
+const V2_OPS = new Set(['PARALLEL', 'TIMEOUT']);
+
 const OP_SET = new Set(PLAN_OPS);
 const SIDE_EFFECT_SET = new Set(SIDE_EFFECT_CLASSES);
 
@@ -169,8 +173,14 @@ function validateRetryPolicy(retry, nodeId, declaredEffects, errors) {
 /**
  * compilePlan(ir, opts) — SPEC §4.
  *
- * @param {object} ir `{ nodes: [...] }`
- * @param {{maxNodes?:number, allowedOps?:string[]}} [opts]
+ * V-01 gate: IR v2 ops (PARALLEL, TIMEOUT) parse only when the caller opts
+ * in — `ir.planVersion: 'v2'`, `opts.irVersion: 'v2'` (how callers forward a
+ * non-'off' decisionRuntime.vm stage), or an `opts.allowedOps` list that
+ * explicitly names them. v1 plans compile byte-identical under every flag
+ * state; their planVersion hash never gets the 'v2:' prefix.
+ *
+ * @param {object} ir `{ nodes: [...], planVersion?: 'v1'|'v2' }`
+ * @param {{maxNodes?:number, allowedOps?:string[], irVersion?:string}} [opts]
  * @returns {{ok:true, plan:object}|{ok:false, errors:object[]}}
  */
 export function compilePlan(ir, opts = {}) {
@@ -182,6 +192,19 @@ export function compilePlan(ir, opts = {}) {
     ? new Set(opts.allowedOps)
     : OP_SET;
 
+  // V-01 flag gate (see docstring): BOTH channels are validated ('v1' is an
+  // explicit no-op, anything else is a typo that must not widen parsing);
+  // v2 enables when EITHER the artifact or the caller opts in — a stage-off
+  // caller ('v1') can never veto an artifact's own planVersion:'v2'.
+  const declared = [opts.irVersion, ir?.planVersion].filter((v) => v !== undefined);
+  for (const v of declared) {
+    if (!IR_VERSIONS.includes(v)) {
+      err(errors, 'invalid_ir_version', undefined,
+        `IR version ${JSON.stringify(v)} must be one of: ${IR_VERSIONS.join(', ')}`);
+    }
+  }
+  const v2Enabled = declared.includes('v2');
+
   const rawNodes = Array.isArray(ir?.nodes) ? ir.nodes : [];
   if (rawNodes.length === 0) {
     err(errors, 'empty_plan', undefined, 'ir.nodes must be a non-empty array');
@@ -212,6 +235,13 @@ export function compilePlan(ir, opts = {}) {
       err(errors, 'unknown_op', nodeId, `op ${JSON.stringify(op)} not allowed`);
       continue;
     }
+    // Gate BEFORE other per-node checks so a gated op surfaces exactly one
+    // typed error; explicit allowedOps lists are the caller's opt-in.
+    if (V2_OPS.has(op) && !v2Enabled && !Array.isArray(opts.allowedOps)) {
+      err(errors, 'ir_v2_disabled', nodeId,
+        `op ${op} requires IR v2 (ir.planVersion:'v2', opts.irVersion:'v2', or a non-off decisionRuntime.vm stage forwarded by the caller)`);
+      continue;
+    }
 
     const deps = node.deps === undefined ? [] : node.deps;
     if (!Array.isArray(deps) || deps.some((d) => !isNonEmptyString(d))) {
@@ -309,6 +339,10 @@ export function compilePlan(ir, opts = {}) {
     }
 
 
+    if (node.question !== undefined && !validateNodeQuestion(node.question).ok) {
+      err(errors, 'malformed_question', nodeId, 'question block fails validateNodeQuestion');
+    }
+
     const retry = validateRetryPolicy(node.retry, nodeId, declaredEffects, errors);
 
     const compiledNode = {
@@ -316,6 +350,7 @@ export function compilePlan(ir, opts = {}) {
       op,
       deps: [...deps],
       ...(retry ? { retry } : {}),
+      ...(node.question !== undefined ? { question: deepFreeze({ ...node.question }) } : {}),
       ...(node.selector !== undefined ? { selector: deepFreeze({ ...node.selector }) } : {}),
       ...(node.timeoutMs !== undefined ? { timeoutMs: node.timeoutMs } : {}),
       ...(node.spec !== undefined ? { spec: deepFreeze({ ...node.spec }) } : {}),
@@ -385,7 +420,7 @@ export function compilePlan(ir, opts = {}) {
   // v1 plans hash exactly as before; IR v2 usage switches the canonical
   // input to a 'v2:'-prefixed serialization so v2 planVersions can never
   // collide with (or silently change) v1 hashes.
-  const usesV2 = [...compiled.values()].some((n) => n.op === 'PARALLEL' || n.op === 'TIMEOUT');
+  const usesV2 = [...compiled.values()].some((n) => V2_OPS.has(n.op));
 
   if (errors.length > 0) {
     return { ok: false, errors };
@@ -404,6 +439,10 @@ export function compilePlan(ir, opts = {}) {
 
   const plan = Object.freeze({
     planVersion,
+    // IR version is derived from the ops actually used, not the opt-in
+    // label: a 'v2'-declared plan that uses only v1 ops reports 'v1' and
+    // hashes as v1.
+    irVersion: usesV2 ? 'v2' : 'v1',
     nodes: Object.freeze(nodes),
     entryNodes: Object.freeze(entryNodes),
     order: Object.freeze(order),

package/src/core/agentRuntime/planLibrary.js

@@ -4,9 +4,17 @@
  *
  * Loads the IR documents under `src/core/agentRuntime/plans/<planId>.json`,
  * compiles each through `compilePlan`, and returns an immutable catalog:
- * { planId -> { planId, description, irHash, plan } }. `irHash` is a sha256
- * over the canonical IR bytes — changing a plan bumps its version artifact
- * (the compiled `planVersion` is also content-derived inside compilePlan).
+ * { planId -> { ok, planId, description, specText, irHash, planVersion, plan } }.
+ * `irHash` is a sha256 over the raw artifact bytes; `planVersion` is the
+ * content-derived hash inside the compiled ValidatedPlan. Each plan JSON
+ * carries a `specText` field — the human-authored spec the IR was compiled
+ * from — so spec → artifact stays in one file and edits bump `irHash`.
+ *
+ * Release pinning: `PLAN_PINS` records the compiled planVersion of each
+ * shipped plan. Editing a plan's nodes changes its planVersion, so a plan
+ * that drifts from its pin fails load with `plan_version_mismatch` instead
+ * of silently shipping a different workflow. Bump the pin in the same
+ * commit that changes the plan — that re-pin is the release review point.
  *
  * Read-only: no writes, no host calls. Compile errors surface as
  * { ok:false, errors } entries — they never throw so a bad draft plan cannot
@@ -18,10 +26,20 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+
+import { resolveDecisionRuntimeStage } from '../runtimeConfig.js';
 import { compilePlan } from './planCompiler.js';
 
 const PLANS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'plans');
 
+/** planId -> compiled planVersion pinned at ship time. */
+export const PLAN_PINS = Object.freeze({
+  'bugfix-loop': '959c23b0a834b022',
+  'flag-promotion': 'c7af6411d4be570b',
+  'handoff-review-batch': 'bb3194edfc33ea0e',
+  'release-check': 'b59e5be91a205aa2',
+});
+
 export function listPlanIds({ plansDir = PLANS_DIR } = {}) {
   let entries;
   try {
@@ -35,7 +53,7 @@ export function listPlanIds({ plansDir = PLANS_DIR } = {}) {
     .sort();
 }
 
-export function loadPlan(planId, { plansDir = PLANS_DIR } = {}) {
+export function loadPlan(planId, { plansDir = PLANS_DIR, pins = PLAN_PINS, config = null } = {}) {
   if (typeof planId !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(planId)) {
     return { ok: false, errors: [{ code: 'invalid_plan_id', planId }] };
   }
@@ -52,22 +70,40 @@ export function loadPlan(planId, { plansDir = PLANS_DIR } = {}) {
   } catch {
     return { ok: false, errors: [{ code: 'plan_malformed', planId }] };
   }
-  const result = compilePlan(ir);
+  // V-01 flag gate: a non-'off' decisionRuntime.vm stage enables IR v2 op
+  // parsing for every loaded plan; 'off' (or absent config) compiles v1-only
+  // unless the plan artifact itself declares planVersion:'v2'.
+  const irVersion = resolveDecisionRuntimeStage(config, 'vm') === 'off' ? 'v1' : 'v2';
+  const result = compilePlan(ir, { irVersion });
   if (!result.ok) return result;
+  const pinned = pins?.[planId];
+  if (pinned !== undefined && pinned !== result.plan.planVersion) {
+    return {
+      ok: false,
+      errors: [{
+        code: 'plan_version_mismatch',
+        planId,
+        expected: pinned,
+        actual: result.plan.planVersion,
+      }],
+    };
+  }
   const irHash = createHash('sha256').update(raw, 'utf8').digest('hex').slice(0, 16);
   return {
     ok: true,
     planId,
     description: typeof ir?.description === 'string' ? ir.description : null,
+    specText: typeof ir?.specText === 'string' ? ir.specText : null,
     irHash,
+    planVersion: result.plan.planVersion,
     plan: result.plan,
   };
 }
 
-export function loadPlanLibrary({ plansDir = PLANS_DIR } = {}) {
+export function loadPlanLibrary({ plansDir = PLANS_DIR, pins = PLAN_PINS, config = null } = {}) {
   const catalog = {};
   for (const planId of listPlanIds({ plansDir })) {
-    catalog[planId] = loadPlan(planId, { plansDir });
+    catalog[planId] = loadPlan(planId, { plansDir, pins, config });
   }
   return Object.freeze(catalog);
 }

package/src/core/agentRuntime/plans/bugfix-loop.json

@@ -1,6 +1,7 @@
 {
   "planId": "bugfix-loop",
   "description": "Reproduce a failing test, locate the cause via index, patch the smallest surface, re-run the test to green, then summarize the fix. Reference plan for the language-compiled runtime (V4 seed).",
+  "specText": "Given a reported failing test or command: (1) reproduce it and capture the output; (2) query the index on the error/symbol, open the top suspects, and trace backward to the source line; (3) apply the minimal source patch at the located cause; (4) re-run the failing test plus the affected suite slice until green; (5) complete with a root-cause + fix summary. No escalation path — a failure at any step surfaces as a failed node for the caller to handle.",
   "nodes": [
     {
       "id": "reproduce",

package/src/core/agentRuntime/plans/flag-promotion.json

@@ -0,0 +1,138 @@
+{
+  "planId": "flag-promotion",
+  "description": "Stage-promotion gate for decisionRuntime.vm-family flags: replay baseline → sampled shadow runs → quality-floor branch → promote one stage or rollback to off. Reference plan for the language-compiled runtime (V4 seed; mirrors promotion.js).",
+  "specText": "Promote a decision-runtime flag one stage (off → shadow → canary → default): (1) replay the recorded baseline to fix quality floor and wall-time/cost targets; (2) run N sampled shadow runs under the candidate stage; (3) branch on the sampled results — meets the pre-registered floor → update the flag stage and complete as promoted, misses → roll the flag back to off and complete as rolled-back. Rollback keeps deterministic owners authoritative; a failed gate never silently promotes.",
+  "nodes": [
+    {
+      "id": "baseline-replay",
+      "op": "RUN",
+      "deps": [],
+      "timeoutMs": 300000,
+      "retry": {
+        "sideEffectClass": "read_only",
+        "maxAttempts": 2,
+        "backoffMs": 500
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "replay the recorded baseline run; fix the quality floor + wall-time/cost targets",
+        "sideEffects": [
+          "read_only"
+        ],
+        "writes": [],
+        "allowedPaths": []
+      }
+    },
+    {
+      "id": "shadow-run",
+      "op": "RUN",
+      "deps": [
+        "baseline-replay"
+      ],
+      "timeoutMs": 600000,
+      "retry": {
+        "sideEffectClass": "read_only",
+        "maxAttempts": 1,
+        "backoffMs": 0
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "execute N sampled shadow runs under the candidate stage and record outcomes",
+        "sideEffects": [
+          "read_only"
+        ],
+        "writes": [],
+        "allowedPaths": []
+      }
+    },
+    {
+      "id": "gate",
+      "op": "BRANCH",
+      "deps": [
+        "shadow-run"
+      ],
+      "selector": {
+        "eventType": "branch.selected",
+        "field": "verdict"
+      },
+      "branches": {
+        "meets-floor": "promote-flag",
+        "misses-floor": "rollback-flag"
+      }
+    },
+    {
+      "id": "promote-flag",
+      "op": "RUN",
+      "deps": [
+        "gate"
+      ],
+      "timeoutMs": 120000,
+      "retry": {
+        "sideEffectClass": "idempotent_write",
+        "maxAttempts": 2,
+        "backoffMs": 500
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "advance the flag to the next stage in config (off -> shadow -> canary -> default)",
+        "sideEffects": [
+          "idempotent_write"
+        ],
+        "writes": [
+          ".ukit/storage/config.json"
+        ],
+        "allowedPaths": [
+          ".ukit/storage"
+        ]
+      }
+    },
+    {
+      "id": "rollback-flag",
+      "op": "RUN",
+      "deps": [
+        "gate"
+      ],
+      "timeoutMs": 120000,
+      "retry": {
+        "sideEffectClass": "idempotent_write",
+        "maxAttempts": 2,
+        "backoffMs": 500
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "roll the flag back to 'off' — deterministic lane owners stay authoritative",
+        "sideEffects": [
+          "idempotent_write"
+        ],
+        "writes": [
+          ".ukit/storage/config.json"
+        ],
+        "allowedPaths": [
+          ".ukit/storage"
+        ]
+      }
+    },
+    {
+      "id": "promoted",
+      "op": "COMPLETE",
+      "deps": [
+        "promote-flag"
+      ]
+    },
+    {
+      "id": "rolled-back",
+      "op": "COMPLETE",
+      "deps": [
+        "rollback-flag"
+      ]
+    }
+  ]
+}

package/src/core/agentRuntime/plans/handoff-review-batch.json

@@ -1,6 +1,7 @@
 {
   "planId": "handoff-review-batch",
   "description": "Collect pending_review tasks, fan out per-panel-member reviews, aggregate verdicts, and escalate on CHANGES-REQUESTED/CRITICAL. Reference plan for the language-compiled runtime (V4 seed).",
+  "specText": "(1) List pending_review task files under docs/AI_HANDOFF/tasks; (2) wait for the panel's per-member verdict rows (event 'review.verdicts', boundary 'task-review'); (3) aggregate verdicts via review-panel-aggregate.mjs — the lead member's verdict takes precedence; (4) branch on the aggregated verdict: approved → complete; blocked (CHANGES-REQUESTED/CRITICAL) → escalate, the deterministic gate stays authoritative.",
   "nodes": [
     {
       "id": "collect-tasks",

package/src/core/agentRuntime/plans/release-check.json

@@ -1,6 +1,7 @@
 {
   "planId": "release-check",
-  "description": "Version parity gate before ship: bump \u2192 targeted tests + twin parity \u2192 commit/push/tag \u2192 npm publish \u2192 parity verify. Reference plan for the language-compiled runtime (V4 seed).",
+  "description": "Version parity gate before ship: bump → targeted tests + twin parity → commit/push/tag → npm publish → parity verify. Reference plan for the language-compiled runtime (V4 seed).",
+  "specText": "Version-parity ship gate: (1) bump package.json via 'npm version <v> --no-git-tag-version' and sync the baseline-reconciliation version; (2) run the targeted vitest slice plus templateParity and docs render checks; (3) commit → push → tag → GitHub release → npm publish; (4) poll 'npm view dist-tags.latest' until it equals the package.json version; (5) complete. Any parity failure leaves the plan failed — no silent drift.",
   "nodes": [
     {
       "id": "version-bump",

package/src/core/agentRuntime/promotion.js

@@ -1,13 +1,29 @@
 // src/core/agentRuntime/promotion.js
-// Pure caller-wait promotion decision (SPEC §2 G6-FR01/02, §4).
-// selectWaitPolicy(profile, operation, resources) → frozen
-//   { mode: 'foreground'|'handle', reason: string }
-// 'handle' is permitted only when the injected frozen DurationProfile records
-// the operation class as long-running (promoteAfterMs: number) AND
-// resources.pressure is not 'critical'. Every other input resolves
-// 'foreground' with a typed reason — never throws, never returns undefined.
-// Promotion changes caller waiting semantics only: this module performs no
-// I/O, reads no config, and never spawns/signals an OS process.
+// Two pure promotion surfaces, no I/O, no config mutation:
+//
+// 1. Caller-wait promotion (SPEC §2 G6-FR01/02, §4).
+//    selectWaitPolicy(profile, operation, resources) → frozen
+//    { mode: 'foreground'|'handle', reason: string }
+//    'handle' is permitted only when the injected frozen DurationProfile
+//    records the operation class as long-running (promoteAfterMs: number)
+//    AND resources.pressure is not 'critical'. Every other input resolves
+//    'foreground' with a typed reason — never throws, never returns
+//    undefined. Promotion changes caller waiting semantics only.
+//
+// 2. decisionRuntime stage promotion (V-03 / G-V3).
+//    promote(config, evidence) → frozen { stage, promoted, reason }
+//    moves one family flag (default 'vm') through off → shadow → canary →
+//    default only when pre-registered non-inferiority criteria hold on
+//    enough sampled runs (PROMOTION_CRITERIA). 'off' never self-promotes —
+//    entering shadow is an operator act; evidence only advances an active
+//    rollout. Instant rollback: evidence.rollback === true or any sampled
+//    run carrying a forbidden failure resolves 'off', keeping deterministic
+//    owners authoritative (zero VM calls). One noisy run (qualityDelta
+//    below floor, wall/cost ratio above target, malformed row) blocks the
+//    step — it can never flip a default.
+
+import { resolveDecisionRuntimeStage } from '../runtimeConfig.js';
+import { COMPARABLE_RUNS, QUALITY_SCORE_FLOOR } from './evaluation.js';
 
 const PROFILE_VERSION = 1;
 
@@ -51,3 +67,125 @@ export function selectWaitPolicy(profile, operation, resources) {
 
   return policy('handle', `class:${cls}:promoteAfterMs:${promoteAfterMs}`);
 }
+
+// --- V-03: decisionRuntime stage promotion (G-V3) ----------------------------
+
+// Reserved rollout order — mirrors VALID_ROUTE_STAGES in runtimeConfig.js.
+export const PROMOTION_STAGE_ORDER = Object.freeze(['off', 'shadow', 'canary', 'default']);
+
+// Pre-registered non-inferiority criteria (G-V3): frozen before any rollout
+// exists; per-key entries may tighten the shared default, never widen it.
+//   minSampledRuns  — evidence must contain >= N sampled runs to advance
+//   qualityFloor    — every sampled run's qualityDelta >= -qualityFloor
+//   maxWallP95Ratio — every sampled run's wall p95 ratio vs baseline <= this
+//   maxCostRatio    — every sampled run's cost ratio vs baseline <= this
+const DEFAULT_PROMOTION_CRITERIA = Object.freeze({
+  minSampledRuns: COMPARABLE_RUNS,
+  qualityFloor: QUALITY_SCORE_FLOOR,
+  maxWallP95Ratio: 1.0,
+  maxCostRatio: 1.0,
+});
+
+// Criteria registry. Pinned family flags (decisionRuntime.vm first) share the
+// pre-registered default until a tightened entry lands — absent key always
+// resolves the default, so an unknown flag can never promote on looser terms.
+export const PROMOTION_CRITERIA = Object.freeze({
+  default: DEFAULT_PROMOTION_CRITERIA,
+});
+
+export function promotionCriteriaFor(key) {
+  const entry = PROMOTION_CRITERIA[key];
+  return isObj(entry) ? entry : DEFAULT_PROMOTION_CRITERIA;
+}
+
+function isNum(v) {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+function runForbidden(run) {
+  return run.forbidden === true || (isNum(run.forbiddenFailures) && run.forbiddenFailures > 0);
+}
+
+// One sampled run vs the registered non-inferiority contract. A run that
+// cannot produce a required metric never counts as passing — missing data
+// is treated like a failing run, never guessed.
+function runNonInferior(run, criteria) {
+  if (!isNum(run.qualityDelta) || run.qualityDelta < -criteria.qualityFloor) return 'quality:floor';
+  if (!isNum(run.wallP95Ratio) || run.wallP95Ratio > criteria.maxWallP95Ratio) return 'wall:target';
+  if (!isNum(run.costRatio) || run.costRatio > criteria.maxCostRatio) return 'cost:target';
+  return null;
+}
+
+function stageResult(stage, promoted, reason) {
+  return Object.freeze({ stage, promoted, reason });
+}
+
+/**
+ * Pure stage-promotion decision for one decisionRuntime family flag.
+ * @param {object} config   runtime config (stage resolved via
+ *                          resolveDecisionRuntimeStage; malformed → 'off')
+ * @param {object} evidence { key?, rollback?, sampledRuns?, forbiddenFailures?,
+ *                            runs?: [{qualityDelta, wallP95Ratio, costRatio,
+ *                                     forbidden?, forbiddenFailures?}],
+ *                            comparison?: GateComparison,
+ *                            qualityDelta?, wallP95Ratio?, costRatio? }
+ * @returns {{stage:string, promoted:boolean, reason:string}} frozen
+ */
+export function promote(config, evidence = {}) {
+  const ev = isObj(evidence) ? evidence : {};
+  const key = typeof ev.key === 'string' && ev.key !== '' ? ev.key : 'vm';
+  const criteria = promotionCriteriaFor(key);
+  const stage = resolveDecisionRuntimeStage(config, key);
+  const runs = Array.isArray(ev.runs) ? ev.runs : null;
+  const forbiddenRuns = runs == null ? 0 : runs.filter((r) => isObj(r) && runForbidden(r)).length;
+  const forbiddenFailures = isNum(ev.forbiddenFailures) ? ev.forbiddenFailures : forbiddenRuns;
+
+  // Instant rollback: explicit request or any forbidden failure in the
+  // sampled evidence drops the flag to 'off' — deterministic owners become
+  // authoritative again with zero VM involvement.
+  if (ev.rollback === true) return stageResult('off', stage !== 'off', 'rollback:requested');
+  if (forbiddenFailures > 0) return stageResult('off', stage !== 'off', `rollback:forbidden:${forbiddenFailures}`);
+
+  // 'off' never self-promotes — entering shadow is an operator act;
+  // 'default' (or any unresolvable index) is terminal.
+  const index = PROMOTION_STAGE_ORDER.indexOf(stage);
+  if (index <= 0) return stageResult(stage, false, `stage:${stage}`);
+  if (index >= PROMOTION_STAGE_ORDER.length - 1) return stageResult(stage, false, 'stage:terminal');
+  const next = PROMOTION_STAGE_ORDER[index + 1];
+
+  const sampledRuns = isNum(ev.sampledRuns) ? ev.sampledRuns : (runs == null ? 0 : runs.length);
+  if (sampledRuns < criteria.minSampledRuns) {
+    return stageResult(stage, false, `evidence:runs:${sampledRuns}<${criteria.minSampledRuns}`);
+  }
+
+  // Optional aggregate gate verdict (evaluation.computeGateComparison):
+  // non-comparable or failed comparisons hold the stage, never flip it.
+  if (isObj(ev.comparison)) {
+    if (ev.comparison.comparable !== true) return stageResult(stage, false, 'comparison:incomparable');
+    if (ev.comparison.verdict !== 'pass') {
+      return stageResult(stage, false, `comparison:${ev.comparison.verdict ?? 'fail'}`);
+    }
+  }
+
+  if (runs != null) {
+    for (let i = 0; i < runs.length; i += 1) {
+      const run = runs[i];
+      if (!isObj(run)) return stageResult(stage, false, `run:${i}:malformed`);
+      const failing = runNonInferior(run, criteria);
+      if (failing != null) return stageResult(stage, false, `run:${i}:${failing}`);
+    }
+  } else {
+    if (!isNum(ev.qualityDelta) || ev.qualityDelta < -criteria.qualityFloor) {
+      return stageResult(stage, false, 'quality:floor');
+    }
+    if (!isNum(ev.wallP95Ratio) || ev.wallP95Ratio > criteria.maxWallP95Ratio) {
+      return stageResult(stage, false, 'wall:target');
+    }
+    if (!isNum(ev.costRatio) || ev.costRatio > criteria.maxCostRatio) {
+      return stageResult(stage, false, 'cost:target');
+    }
+  }
+
+  return stageResult(next, true, `promote:${stage}->${next}`);
+}
+

package/src/core/agentRuntime/runtimeSupport.js

@@ -28,6 +28,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 
 import { readJournal } from './eventStore.js';
+import { listHostAdapters } from './adapters.js';
 import { sanitizeForSupport } from '../observability/privacy/sanitizeForSupport.js';
 import { REDACTION_VERSION } from '../observability/privacy/allowlist.js';
 
@@ -235,3 +236,20 @@ export async function buildRuntimeSupportRecords(dir, opts = {}) {
     redaction_version: REDACTION_VERSION,
   };
 }
+
+/**
+ * V-02 (AGENT_VM_RUNTIME_PLAN item V2): per-host capability map for the
+ * owned-runner lanes. Pure delegation to `listHostAdapters` — every lane
+ * reports `{supported, reason, completionApi, primitives}` honestly:
+ * 'supported' only with declared live host E2E, 'unsupported-probe'
+ * when primitives exist but live evidence is missing, 'unsupported'
+ * with a typed reason otherwise. No journal reads, no fs writes.
+ *
+ * @param {object} [opts] forwarded to probeHostAdapter (spawnImpl,
+ *   killImpl, probeImpl, platform, liveHostE2E)
+ * @returns {{[host:string]: {supported:string, reason:string|null,
+ *   completionApi:string|null, primitives:object}}}
+ */
+export function buildHostCapabilityMap(opts = {}) {
+  return listHostAdapters(opts);
+}

package/src/core/agentRuntime/supervisor.js

@@ -34,7 +34,12 @@ import {
 import { classifyObservation } from './liveness.js';
 import { createArtifactWriter } from './artifacts.js';
 import { reconcileOwnedOperations } from './recovery.js';
-import { beginToolSpan, endToolSpan } from './adapters.js';
+import {
+  beginToolSpan,
+  endToolSpan,
+  probeHostAdapter,
+  detectHost,
+} from './adapters.js';
 import {
   resolveTelemetry,
   newRunContext,
@@ -86,6 +91,9 @@ function specIsValid(spec) {
   const hasArgv = Array.isArray(spec.argv) && spec.argv.length > 0
     && spec.argv.every((a) => typeof a === 'string' && a !== '');
   if (!hasCommand && !hasArgv) return false;
+  // V-02: optional host lane selector — absent or non-empty string.
+  if (spec.host !== undefined
+    && (typeof spec.host !== 'string' || spec.host === '')) return false;
   return SIDE_EFFECT_CLASSES.includes(spec.sideEffectClass);
 }
 
@@ -105,7 +113,11 @@ function specIsValid(spec) {
  * @param {Function} [opts.fsyncImpl] artifact fsync
  * @param {Function} [opts.appendEventImpl] journal append (test injection)
  * @param {object} [opts.artifactDeps] artifact writer dep overrides
- * @returns {object} Supervisor — SPEC §4 surface.
+ * @param {string} [opts.host] V-02 host lane ('omp'|'claude-code'|'codex') —
+ *   default for specs without `spec.host`; absent spec.host falls back to
+ *   ambient `detectHost()`, then no lane. A lane probed `unsupported`
+ *   refuses `start()` typed, `unsupported-probe` lanes still run (live
+ *   host E2E is an evidence claim, not a launch gate — G-V2).
  */
 export function createSupervisor(opts = {}) {
   const runtimeDir = opts.runtimeDir;
@@ -223,6 +235,17 @@ export function createSupervisor(opts = {}) {
   const spawnImpl = opts.spawnImpl ?? defaultSpawnImpl;
   const killImpl = opts.killImpl ?? defaultKillImpl;
   const probeImpl = opts.probeImpl ?? defaultProbeImpl;
+
+  // V-02 host lane resolution. Precedence per launch: spec.host →
+  // opts.host → ambient detectHost() → no lane (legacy contract,
+  // byte-identical to pre-V2 behaviour). The probe shares this
+  // supervisor's injectable primitives so a test-supplied spawn is what
+  // gets evaluated, never the ambient ones.
+  const configuredHost = typeof opts.host === 'string' && opts.host !== '' ? opts.host : undefined;
+  const hostLaneFor = (spec) => {
+    const name = spec?.host ?? configuredHost ?? detectHost(opts.env);
+    return name ? probeHostAdapter(name, { spawnImpl, killImpl, probeImpl }) : null;
+  };
   const append = opts.appendEventImpl ?? appendEvent;
   const clock = opts.clock && typeof opts.clock.setTimeout === 'function'
     ? opts.clock
@@ -520,6 +543,23 @@ export function createSupervisor(opts = {}) {
         });
         return unsupported('invalid_spec');
       }
+      // V-02 host lane gate: only a probed `unsupported` lane refuses —
+      // typed, zero fs writes (same contract as launch_disabled).
+      // `unsupported-probe` lanes launch: the runner is primitive-level
+      // identical on every engine; live-E2E status is a capability-map
+      // claim, never a launch precondition.
+      const hostLane = hostLaneFor(spec);
+      if (hostLane && hostLane.supported === 'unsupported') {
+        endExecutionSpan(ctx, 'blocked', {
+          operation: spec.operationId,
+          reason_code: 'GATE_BLOCKED',
+        });
+        return {
+          unsupported: true,
+          code: hostLane.reason === 'unknown_host' ? 'host_unknown' : 'host_unsupported',
+          reason: hostLane.reason,
+        };
+      }
       // G6 promotion consult — shadow evaluates+records a receipt; served
       // wait semantics below are always the prior path.
       if (promotionStage() !== 'off') {
@@ -556,6 +596,7 @@ export function createSupervisor(opts = {}) {
       await transition(op, 'starting', {
         attempt: spec.attempt,
         sideEffectClass: spec.sideEffectClass,
+        ...(hostLane ? { host: hostLane.name } : {}),
       });
 
       let proc;
@@ -635,6 +676,7 @@ export function createSupervisor(opts = {}) {
         operationId: op.id,
         pid: proc.pid,
         state: op.state,
+        host: hostLane ? hostLane.name : null,
         get currentState() {
           return op.state;
         },