@ngockhoale/ukit 3.1.6 → 3.1.8

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to UKit are documented here.
 
+## 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.
+- **Install seeds `.ukit/storage/observability/`** — the segment writer's safe `resolveRoot` rejects a missing parent, so the first emit on a fresh install previously failed with ENOENT. `ukit install` now creates the directory (advisory, never fails).
+
+## 3.1.7 - 2026-09-26
+
+- **Observability + memory recording enabled by default on install.** Shipped `config.json` now sets `observability.stage: 'default'` (recorder + analytics + projector + evaluation — the full Data Foundation pipeline) and `learning.episodes.autoWrite: true` + `learning.candidates.stage: 'shadow'` (ukit-memory records evidence without auto-applying anything). Privacy gates (`sanitizeObserved`, `sanitizeForSupport` default-deny) are unchanged. Code defaults in `runtimeConfig.js` updated to match. New: `planLibrary.js` + 3 versioned reference plans (`bugfix-loop`, `handoff-review-batch`, `release-check`) as the V4 artifact seed for the Agent VM phase-2 plan.
+
 ## 3.1.6 - 2026-09-26
 
 - **Decision endpoint URL normalization**: a `UKIT_DECISION_BASE_URL` that already ends in `/v1` (OpenAI convention) no longer produces `…/v1/v1/chat/completions`; the client strips a trailing `/v1` before joining. Applied to `src/decision/client.js` and mirrored in `unic-decision.mjs`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.1.6",
+  "version": "3.1.8",
   "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/install.js

@@ -296,6 +296,13 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
       reason: error?.message ?? 'provision_failed',
     };
   }
+
+  // Observability storage root: the segment writer's resolveRoot refuses a
+  // missing parent, so seed <project>/.ukit/storage/observability/ at install
+  // (advisory — never fails install). The recorder creates segments inside.
+  try {
+    await fs.mkdir(path.join(projectRoot, '.ukit', 'storage', 'observability'), { recursive: true });
+  } catch { /* advisory — never fail install */ }
   const { create, update, unchanged, skip } = result.summary;
 
   console.log(`[UKit] Project: ${result.projectContext.project.name}`);

package/src/core/agentRuntime/planCompiler.js

@@ -1,8 +1,9 @@
 /**
- * agentRuntime/planCompiler.js — decision-first-runtime G4 (DR-06), IR v1.
+ * agentRuntime/planCompiler.js — decision-first-runtime G4 (DR-06), IR v1+v2.
  *
  * Pure plan compiler: validates a small DAG IR (frozen opcode set: RUN,
- * WAIT_EVENT, BRANCH, COMPLETE, ESCALATE) and emits an immutable
+ * WAIT_EVENT, BRANCH, COMPLETE, ESCALATE — plus IR v2 wrappers PARALLEL
+ * and TIMEOUT) and emits an immutable
  * ValidatedPlan { planVersion, nodes, entryNodes, order }.
  *
  * No I/O, no runtimeConfig reads, no imports of vmEngine. The only
@@ -21,6 +22,8 @@ export const PLAN_OPS = Object.freeze([
   'BRANCH',
   'COMPLETE',
   'ESCALATE',
+  'PARALLEL',
+  'TIMEOUT',
 ]);
 
 const OP_SET = new Set(PLAN_OPS);
@@ -34,6 +37,10 @@ const DEFAULT_MAX_ATTEMPTS = 1;
 const MAX_ATTEMPTS_CEILING = 3;
 const SELECTOR_OPS = new Set(['eq', 'neq', 'in', 'exists']);
 const PATH_TRAVERSAL = /(^|\/)\.\.(\/|$)/;
+/** Ceiling for TIMEOUT.deadlineMs — bounded deadlines only (IR v2). */
+const MAX_DEADLINE_MS = 1_800_000;
+const TIMEOUT_POLICIES = new Set(['fail', 'escalate']);
+const WRAPPABLE_OPS = new Set(['RUN', 'WAIT_EVENT']);
 
 function err(errors, code, nodeId, detail) {
   errors.push({ code, nodeId, detail });
@@ -254,6 +261,54 @@ export function compilePlan(ir, opts = {}) {
       }
     }
 
+    let children;
+    if (op === 'PARALLEL') {
+      children = node.children;
+      if (!Array.isArray(children) || children.length === 0) {
+        err(errors, 'invalid_children', nodeId, 'PARALLEL requires a non-empty children array');
+      } else if (children.some((c) => !isNonEmptyString(c)) || new Set(children).size !== children.length) {
+        err(errors, 'invalid_children', nodeId, 'PARALLEL children must be unique node ids');
+      } else {
+        for (const child of children) {
+          if (!ids.has(child)) {
+            err(errors, 'missing_ref', nodeId, `child ${JSON.stringify(child)} not in plan`);
+          }
+          if (child === nodeId) {
+            err(errors, 'cycle', nodeId, 'PARALLEL self-reference');
+          }
+        }
+      }
+      const join = node.join === undefined ? 'all' : node.join;
+      if (join !== 'all') {
+        err(errors, 'invalid_children', nodeId, `join ${JSON.stringify(node.join)} unsupported (only 'all')`);
+      }
+    }
+
+    let wrappedId;
+    if (op === 'TIMEOUT') {
+      wrappedId = node.node;
+      if (!isNonEmptyString(wrappedId)) {
+        err(errors, 'missing_ref', nodeId, 'TIMEOUT requires node: <nodeId>');
+      } else {
+        if (!ids.has(wrappedId)) {
+          err(errors, 'missing_ref', nodeId, `timeout target ${JSON.stringify(wrappedId)} not in plan`);
+        }
+        if (wrappedId === nodeId) {
+          err(errors, 'cycle', nodeId, 'TIMEOUT self-reference');
+        }
+      }
+      const deadline = node.deadlineMs;
+      if (!Number.isInteger(deadline) || deadline <= 0 || deadline > MAX_DEADLINE_MS) {
+        err(errors, 'unbounded_timeout', nodeId,
+          `deadlineMs must be an integer in 1..${MAX_DEADLINE_MS} (MAX_DEADLINE_MS)`);
+      }
+      const onTimeout = node.onTimeout === undefined ? 'fail' : node.onTimeout;
+      if (!TIMEOUT_POLICIES.has(onTimeout)) {
+        err(errors, 'invalid_timeout', nodeId, `onTimeout ${JSON.stringify(node.onTimeout)} unsupported`);
+      }
+    }
+
+
     const retry = validateRetryPolicy(node.retry, nodeId, declaredEffects, errors);
 
     const compiledNode = {
@@ -264,6 +319,11 @@ export function compilePlan(ir, opts = {}) {
       ...(node.selector !== undefined ? { selector: deepFreeze({ ...node.selector }) } : {}),
       ...(node.timeoutMs !== undefined ? { timeoutMs: node.timeoutMs } : {}),
       ...(node.spec !== undefined ? { spec: deepFreeze({ ...node.spec }) } : {}),
+      ...(Array.isArray(children) ? { children: deepFreeze([...children]) } : {}),
+      ...(wrappedId !== undefined ? { node: wrappedId } : {}),
+      ...(node.deadlineMs !== undefined ? { deadlineMs: node.deadlineMs } : {}),
+      ...(op === 'TIMEOUT' ? { onTimeout: node.onTimeout === undefined ? 'fail' : node.onTimeout } : {}),
+      ...(op === 'PARALLEL' ? { join: node.join === undefined ? 'all' : node.join } : {}),
       ...(branches !== undefined ? { branches: deepFreeze({ ...branches }) } : {}),
     };
     compiled.set(nodeId, compiledNode);
@@ -281,6 +341,30 @@ export function compilePlan(ir, opts = {}) {
     }
   }
 
+  // IR v2 wrapper containment (checked after all nodes are compiled):
+  // every PARALLEL child / TIMEOUT wrapped node is a RUN/WAIT_EVENT that
+  // declares exactly the wrapper as its dep — it can never be an entry
+  // node, never activate outside its wrapper, and the deps edge is what
+  // keeps the wrapper before it in `order`.
+  for (const node of compiled.values()) {
+    let ids = null;
+    if (node.op === 'PARALLEL') ids = node.children;
+    if (node.op === 'TIMEOUT' && isNonEmptyString(node.node)) ids = [node.node];
+    if (!ids) continue;
+    for (const childId of ids) {
+      const child = compiled.get(childId);
+      if (!child) continue; // missing_ref already reported
+      if (!WRAPPABLE_OPS.has(child.op)) {
+        err(errors, 'invalid_children', node.id,
+          `${node.op} may only wrap RUN/WAIT_EVENT nodes; ${childId} is ${child.op}`);
+      }
+      if (!(child.deps.length === 1 && child.deps[0] === node.id)) {
+        err(errors, 'missing_ref', childId,
+          `wrapped node must declare exactly deps:['${node.id}']`);
+      }
+    }
+  }
+
   const order = [];
   const queue = rawNodes
     .map((n) => n?.id)
@@ -298,12 +382,18 @@ export function compilePlan(ir, opts = {}) {
     err(errors, 'cycle', undefined, 'dependency cycle detected');
   }
 
+  // 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');
+
   if (errors.length > 0) {
     return { ok: false, errors };
   }
 
+  const canonical = canonicalize(order.map((id) => compiled.get(id)));
   const planVersion = createHash('sha256')
-    .update(canonicalize(order.map((id) => compiled.get(id))), 'utf8')
+    .update(usesV2 ? `v2:${canonical}` : canonical, 'utf8')
     .digest('hex')
     .slice(0, 16);
 

package/src/core/agentRuntime/planLibrary.js

@@ -0,0 +1,73 @@
+/**
+ * agentRuntime/planLibrary.js — V4 (phase-2 plan): versioned reference-plan
+ * artifacts.
+ *
+ * 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).
+ *
+ * Read-only: no writes, no host calls. Compile errors surface as
+ * { ok:false, errors } entries — they never throw so a bad draft plan cannot
+ * break the caller.
+ */
+
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { compilePlan } from './planCompiler.js';
+
+const PLANS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'plans');
+
+export function listPlanIds({ plansDir = PLANS_DIR } = {}) {
+  let entries;
+  try {
+    entries = fs.readdirSync(plansDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith('.json'))
+    .map((e) => e.name.slice(0, -'.json'.length))
+    .sort();
+}
+
+export function loadPlan(planId, { plansDir = PLANS_DIR } = {}) {
+  if (typeof planId !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(planId)) {
+    return { ok: false, errors: [{ code: 'invalid_plan_id', planId }] };
+  }
+  const file = path.join(plansDir, `${planId}.json`);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return { ok: false, errors: [{ code: 'plan_not_found', planId }] };
+  }
+  let ir;
+  try {
+    ir = JSON.parse(raw);
+  } catch {
+    return { ok: false, errors: [{ code: 'plan_malformed', planId }] };
+  }
+  const result = compilePlan(ir);
+  if (!result.ok) return result;
+  const irHash = createHash('sha256').update(raw, 'utf8').digest('hex').slice(0, 16);
+  return {
+    ok: true,
+    planId,
+    description: typeof ir?.description === 'string' ? ir.description : null,
+    irHash,
+    plan: result.plan,
+  };
+}
+
+export function loadPlanLibrary({ plansDir = PLANS_DIR } = {}) {
+  const catalog = {};
+  for (const planId of listPlanIds({ plansDir })) {
+    catalog[planId] = loadPlan(planId, { plansDir });
+  }
+  return Object.freeze(catalog);
+}

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

@@ -0,0 +1,107 @@
+{
+  "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).",
+  "nodes": [
+    {
+      "id": "reproduce",
+      "op": "RUN",
+      "deps": [],
+      "timeoutMs": 300000,
+      "retry": {
+        "sideEffectClass": "read_only",
+        "maxAttempts": 1,
+        "backoffMs": 0
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "run the reported failing test/command and capture output",
+        "sideEffects": [
+          "read_only"
+        ],
+        "writes": [],
+        "allowedPaths": []
+      }
+    },
+    {
+      "id": "locate-cause",
+      "op": "RUN",
+      "deps": [
+        "reproduce"
+      ],
+      "timeoutMs": 300000,
+      "retry": {
+        "sideEffectClass": "read_only",
+        "maxAttempts": 2,
+        "backoffMs": 500
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "query-index on error/symbol, open top suspects, trace backward to the source line",
+        "sideEffects": [
+          "read_only"
+        ],
+        "writes": [],
+        "allowedPaths": []
+      }
+    },
+    {
+      "id": "patch",
+      "op": "RUN",
+      "deps": [
+        "locate-cause"
+      ],
+      "timeoutMs": 300000,
+      "retry": {
+        "sideEffectClass": "write",
+        "maxAttempts": 1,
+        "backoffMs": 0
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "apply the minimal source fix at the located cause",
+        "sideEffects": [
+          "write"
+        ],
+        "writes": [],
+        "allowedPaths": []
+      }
+    },
+    {
+      "id": "verify",
+      "op": "RUN",
+      "deps": [
+        "patch"
+      ],
+      "timeoutMs": 600000,
+      "retry": {
+        "sideEffectClass": "read_only",
+        "maxAttempts": 1,
+        "backoffMs": 0
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "re-run the failing test plus the affected suite slice; require green",
+        "sideEffects": [
+          "read_only"
+        ],
+        "writes": [],
+        "allowedPaths": []
+      }
+    },
+    {
+      "id": "done",
+      "op": "COMPLETE",
+      "deps": [
+        "verify"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,116 @@
+{
+  "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).",
+  "nodes": [
+    {
+      "id": "collect-tasks",
+      "op": "RUN",
+      "deps": [],
+      "timeoutMs": 60000,
+      "retry": {
+        "sideEffectClass": "read_only",
+        "maxAttempts": 2,
+        "backoffMs": 500
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "list pending_review task files from docs/AI_HANDOFF/tasks",
+        "sideEffects": [
+          "read_only"
+        ],
+        "writes": [],
+        "allowedPaths": [
+          "docs/AI_HANDOFF/tasks"
+        ]
+      }
+    },
+    {
+      "id": "wait-reviews",
+      "op": "WAIT_EVENT",
+      "deps": [
+        "collect-tasks"
+      ],
+      "timeoutMs": 3600000,
+      "retry": {
+        "sideEffectClass": "read_only",
+        "maxAttempts": 1,
+        "backoffMs": 0
+      },
+      "selector": {
+        "eventType": "review.verdicts",
+        "boundary": "task-review"
+      },
+      "spec": {
+        "cmd": "wait for panel verdict rows (per member, per task)",
+        "sideEffects": [
+          "read_only"
+        ],
+        "writes": [],
+        "allowedPaths": []
+      }
+    },
+    {
+      "id": "aggregate",
+      "op": "RUN",
+      "deps": [
+        "wait-reviews"
+      ],
+      "timeoutMs": 120000,
+      "retry": {
+        "sideEffectClass": "read_only",
+        "maxAttempts": 1,
+        "backoffMs": 0
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "node .claude/ukit/index/review-panel-aggregate.mjs <tasks> \u2014 lead member takes precedence",
+        "sideEffects": [
+          "read_only",
+          "idempotent_write"
+        ],
+        "writes": [
+          "docs/AI_HANDOFF/tasks"
+        ],
+        "allowedPaths": [
+          "docs/AI_HANDOFF"
+        ]
+      }
+    },
+    {
+      "id": "gate",
+      "op": "BRANCH",
+      "deps": [
+        "aggregate"
+      ],
+      "selector": {
+        "eventType": "branch.selected",
+        "field": "verdict"
+      },
+      "branches": {
+        "approved": "done",
+        "blocked": "escalate"
+      }
+    },
+    {
+      "id": "done",
+      "op": "COMPLETE",
+      "deps": [
+        "gate"
+      ]
+    },
+    {
+      "id": "escalate",
+      "op": "ESCALATE",
+      "deps": [
+        "gate"
+      ],
+      "spec": {
+        "reason": "changes-requested-or-critical \u2014 deterministic gate stays authoritative"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,113 @@
+{
+  "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).",
+  "nodes": [
+    {
+      "id": "version-bump",
+      "op": "RUN",
+      "deps": [],
+      "timeoutMs": 60000,
+      "retry": {
+        "sideEffectClass": "idempotent_write",
+        "maxAttempts": 2,
+        "backoffMs": 500
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "npm version <v> --no-git-tag-version; sync baseline-reconciliation version",
+        "sideEffects": [
+          "idempotent_write"
+        ],
+        "writes": [
+          "package.json",
+          "docs/AI_HANDOFF/inventory/baseline-reconciliation.md"
+        ],
+        "allowedPaths": [
+          "package.json",
+          "docs/AI_HANDOFF"
+        ]
+      }
+    },
+    {
+      "id": "verify-tests",
+      "op": "RUN",
+      "deps": [
+        "version-bump"
+      ],
+      "timeoutMs": 600000,
+      "retry": {
+        "sideEffectClass": "read_only",
+        "maxAttempts": 1,
+        "backoffMs": 0
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "targeted vitest slice + templateParity + docs render check",
+        "sideEffects": [
+          "read_only"
+        ],
+        "writes": [],
+        "allowedPaths": []
+      }
+    },
+    {
+      "id": "ship",
+      "op": "RUN",
+      "deps": [
+        "verify-tests"
+      ],
+      "timeoutMs": 300000,
+      "retry": {
+        "sideEffectClass": "network",
+        "maxAttempts": 1,
+        "backoffMs": 0
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "commit \u2192 push \u2192 tag \u2192 GitHub release \u2192 npm publish",
+        "sideEffects": [
+          "network"
+        ],
+        "writes": [],
+        "allowedPaths": []
+      }
+    },
+    {
+      "id": "parity",
+      "op": "RUN",
+      "deps": [
+        "ship"
+      ],
+      "timeoutMs": 180000,
+      "retry": {
+        "sideEffectClass": "network",
+        "maxAttempts": 1,
+        "backoffMs": 0
+      },
+      "selector": {
+        "eventType": "operation.completed"
+      },
+      "spec": {
+        "cmd": "npm view dist-tags.latest must equal package.json version (poll until published)",
+        "sideEffects": [
+          "network"
+        ],
+        "writes": [],
+        "allowedPaths": []
+      }
+    },
+    {
+      "id": "done",
+      "op": "COMPLETE",
+      "deps": [
+        "parity"
+      ]
+    }
+  ]
+}

package/src/core/agentRuntime/vmEngine.js

@@ -4,7 +4,11 @@
  * flag; this module reads no config itself).
  *
  * Executes a compiled ValidatedPlan (SPEC §4 frozen shape — literal nodes
- * Map, entryNodes, topological order) purely against G1 durable primitives:
+ * Map, entryNodes, topological order) purely against G1 durable
+ * primitives. IR v2 adds wrapper opcodes: PARALLEL fans out to RUN/
+ * WAIT_EVENT children through the same activation path and folds when
+ * every child is terminal; TIMEOUT wraps one node and resolves on child
+ * terminal state or an elapsed deadline swept by deliver()/resume():
  *
  * - cursor + continuations are registered BEFORE the first node activation
  *   (register-before-start is structural; no "start without register" path)
@@ -206,6 +210,15 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
         inst.nodes[id].state = 'cancelled';
       }
     }
+    // a wrapped child needing recovery is an ambiguous window for the
+    // wrapper too — propagate so the wrapper never joins over a child
+    // whose side effects cannot be proven
+    const wrapperId = nodeId != null ? wrapperOf(inst, nodeId) : null;
+    if (wrapperId != null
+      && inst.nodes[wrapperId].state !== 'recovery_required'
+      && !isTerminal(inst.nodes[wrapperId].state)) {
+      await moveNode(inst, wrapperId, 'recovery_required', { reason });
+    }
   }
 
   async function cancelDependents(inst, nodeId) {
@@ -264,6 +277,27 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
         inst.forcedStatus = 'recovery_required';
         break;
       }
+      case 'PARALLEL': {
+        setNodeState(inst, nodeId, 'running');
+        await appendTransition(inst, nodeId, 'running');
+        // bounded fan-out: children are contained RUN/WAIT_EVENT nodes
+        // (deps === [this node] per compilePlan) — each takes the normal
+        // register-before-start activation path, deterministically in
+        // declared order, so a crash mid fan-out replays child-by-child
+        for (const childId of node.children ?? []) {
+          await activate(inst, childId, { suppressStart });
+        }
+        await resolveParallel(inst, nodeId);
+        break;
+      }
+      case 'TIMEOUT': {
+        setNodeState(inst, nodeId, 'running');
+        inst.nodes[nodeId].startedAt = clock().getTime();
+        await appendTransition(inst, nodeId, 'running');
+        await activate(inst, node.node, { suppressStart });
+        await resolveTimeout(inst, nodeId);
+        break;
+      }
       default:
         throw new VmEngineError('unknown_opcode', `${nodeId}: ${node.op}`);
     }
@@ -277,6 +311,142 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
     }
   }
 
+  /** The IR v2 wrapper (PARALLEL parent or TIMEOUT owner) containing nodeId. */
+  function wrapperOf(inst, nodeId) {
+    for (const [id, node] of inst.nodeMap) {
+      if (node.op === 'PARALLEL' && node.children?.includes(nodeId)) return id;
+      if (node.op === 'TIMEOUT' && node.node === nodeId) return id;
+    }
+    return null;
+  }
+
+  /**
+   * Fold a PARALLEL wrapper once every child is terminal (join: 'all').
+   * All-completed -> completed (and dependents activate); any failure wins
+   * over cancellation. Deterministic: the first failure/cancellation in
+   * declared child order decides the propagated reason.
+   */
+  async function resolveParallel(inst, nodeId, { suppressStart = false } = {}) {
+    const node = inst.nodeMap.get(nodeId);
+    if (!node || node.op !== 'PARALLEL') return null;
+    if (inst.nodes[nodeId].state !== 'running') return null;
+    const children = node.children ?? [];
+    if (!children.every((c) => isTerminal(inst.nodes[c]?.state))) return null;
+
+    const failed = children.find((c) => inst.nodes[c].state === 'failed');
+    const cancelled = children.find((c) => inst.nodes[c].state === 'cancelled');
+    if (failed) {
+      await moveNode(inst, nodeId, 'failed', { reason: `child_failed:${failed}` });
+      inst.recoveryReason = inst.recoveryReason ?? `parallel_child_failed:${failed}`;
+      return { node: nodeId, to: 'failed' };
+    }
+    if (cancelled) {
+      // mirror the RUN cancel path: running -> cancel_pending -> cancelled
+      setNodeState(inst, nodeId, 'cancel_pending');
+      await appendTransition(inst, nodeId, 'cancel_pending');
+      await moveNode(inst, nodeId, 'cancelled', { reason: `child_cancelled:${cancelled}` });
+      await cancelDependents(inst, nodeId);
+      return { node: nodeId, to: 'cancelled' };
+    }
+    await moveNode(inst, nodeId, 'completed');
+    await activateDependents(inst, nodeId, { suppressStart });
+    return { node: nodeId, to: 'completed' };
+  }
+
+  /**
+   * Resolve a TIMEOUT wrapper when its wrapped node is terminal — the
+   * wrapper mirrors the child's terminal state, never inventing an outcome.
+   */
+  async function resolveTimeout(inst, nodeId, { suppressStart = false } = {}) {
+    const node = inst.nodeMap.get(nodeId);
+    if (!node || node.op !== 'TIMEOUT') return null;
+    const wstate = inst.nodes[nodeId].state;
+    if (wstate !== 'running') return null;
+    const childId = node.node;
+    const cstate = inst.nodes[childId]?.state;
+    if (!isTerminal(cstate)) return null;
+
+    if (cstate === 'completed') {
+      await moveNode(inst, nodeId, 'completed');
+      await activateDependents(inst, nodeId, { suppressStart });
+      return { node: nodeId, to: 'completed' };
+    }
+    if (cstate === 'cancelled') {
+      setNodeState(inst, nodeId, 'cancel_pending');
+      await appendTransition(inst, nodeId, 'cancel_pending');
+      await moveNode(inst, nodeId, 'cancelled', { reason: `child_cancelled:${childId}` });
+      await cancelDependents(inst, nodeId);
+      return { node: nodeId, to: 'cancelled' };
+    }
+    await moveNode(inst, nodeId, 'failed', { reason: `child_failed:${childId}` });
+    inst.recoveryReason = inst.recoveryReason ?? `timeout_child_failed:${childId}`;
+    return { node: nodeId, to: 'failed' };
+  }
+
+  /**
+   * Fire a TIMEOUT whose deadline elapsed while the wrapped node is still
+   * non-terminal. 'fail' marks the wrapped node failed with
+   * 'deadline_exceeded' (a non-terminal, non-running wrapped node fails
+   * closed to recovery_required — the activation window is ambiguous);
+   * 'escalate' routes to ESCALATE semantics (wrapper completes escalated,
+   * plan forced recovery_required, wrapped node parked recovery_required).
+   */
+  async function fireTimeout(inst, nodeId) {
+    const node = inst.nodeMap.get(nodeId);
+    const childId = node.node;
+    const cstate = inst.nodes[childId]?.state;
+
+    if (node.onTimeout === 'escalate') {
+      if (!isTerminal(cstate)) {
+        await moveNode(inst, childId, 'recovery_required', { reason: 'deadline_exceeded' });
+      }
+      await moveNode(inst, nodeId, 'completed', { escalated: true, reason: 'deadline_exceeded' });
+      inst.recoveryReason = 'escalated';
+      inst.forcedStatus = 'recovery_required';
+      return { node: nodeId, to: 'completed', escalated: true };
+    }
+    if (cstate === 'running') {
+      await moveNode(inst, childId, 'failed', { reason: 'deadline_exceeded' });
+    } else if (!isTerminal(cstate)) {
+      await moveNode(inst, childId, 'recovery_required', { reason: 'deadline_exceeded' });
+    }
+    await moveNode(inst, nodeId, 'failed', { reason: 'deadline_exceeded' });
+    inst.recoveryReason = inst.recoveryReason ?? `deadline_exceeded:${childId}`;
+    return { node: nodeId, to: 'failed' };
+  }
+
+  /**
+   * Every TIMEOUT whose deadline elapsed while it is still running fires
+   * now — deterministic against the engine clock, journal-first like any
+   * other transition. Called from deliver() (before the delivered event is
+   * evaluated, so a deadline wins a same-instant race) and resume().
+   */
+  async function sweepTimeouts(inst, { suppressStart = false } = {}) {
+    const nowMs = clock().getTime();
+    const results = [];
+    for (const [id, node] of inst.nodeMap) {
+      if (node.op !== 'TIMEOUT') continue;
+      const rec = inst.nodes[id];
+      if (rec.state !== 'running' || rec.startedAt == null) continue;
+      if (nowMs - rec.startedAt < node.deadlineMs) continue;
+      const childState = inst.nodes[node.node]?.state;
+      results.push(isTerminal(childState)
+        ? await resolveTimeout(inst, id, { suppressStart })
+        : await fireTimeout(inst, id));
+    }
+    return results.filter(Boolean);
+  }
+
+  /** A wrapped child resolved — fold its wrapper (no-op when none exists). */
+  async function onChildResolved(inst, nodeId, { suppressStart = false } = {}) {
+    const wrapperId = wrapperOf(inst, nodeId);
+    if (wrapperId == null) return null;
+    const wrapper = inst.nodeMap.get(wrapperId);
+    return wrapper.op === 'TIMEOUT'
+      ? resolveTimeout(inst, wrapperId, { suppressStart })
+      : resolveParallel(inst, wrapperId, { suppressStart });
+  }
+
   function findWaiting(inst, event) {
     const nodeId = event.operationId.slice(inst.planInstanceId.length + 1);
     const node = inst.nodeMap.get(nodeId);
@@ -312,6 +482,14 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
       return { node: nodeId, to: 'completed', branch: value };
     }
 
+    // PARALLEL/TIMEOUT consume no external events — a classified route to a
+    // wrapper fails closed instead of silently completing it (wrappers only
+    // resolve from their contained nodes' states)
+    if (node.op === 'PARALLEL' || node.op === 'TIMEOUT') {
+      await markRecoveryRequired(inst, nodeId, `unroutable_event:${node.op}`);
+      return { node: nodeId, to: 'recovery_required' };
+    }
+
     // RUN / WAIT_EVENT
     const to = NODE_OUTCOMES[outcome];
     if (to == null) {
@@ -325,11 +503,13 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
       await appendTransition(inst, nodeId, 'cancel_pending');
       await moveNode(inst, nodeId, 'cancelled');
       await cancelDependents(inst, nodeId);
+      await onChildResolved(inst, nodeId, { suppressStart });
       return { node: nodeId, to: 'cancelled' };
     }
     if (to === 'completed') {
       await moveNode(inst, nodeId, 'completed');
       await activateDependents(inst, nodeId, { suppressStart });
+      await onChildResolved(inst, nodeId, { suppressStart });
     } else {
       // 'failed': bounded auto-retry only for AUTO_RETRYABLE classes per
       // validateRetry — the retry edge is running->retry_pending->running,
@@ -348,6 +528,7 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
       }
       await moveNode(inst, nodeId, 'failed', { reason: retry.code });
       inst.recoveryReason = inst.recoveryReason ?? `node_failed:${nodeId}:${retry.code}`;
+      await onChildResolved(inst, nodeId, { suppressStart });
     }
     return { node: nodeId, to };
   }
@@ -390,7 +571,7 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
       forcedStatus: null,
     };
     for (const [id] of nodes) {
-      inst.nodes[id] = { state: 'queued', attempt: 0, lastEventSeq: 0 };
+      inst.nodes[id] = { state: 'queued', attempt: 0, lastEventSeq: 0, startedAt: null };
       inst.cursors[id] = { lastSeq: 0, seenEventIds: new Set() };
       inst.journalSeq[id] = 0;
     }
@@ -459,6 +640,7 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
         state: seed.state ?? 'queued',
         attempt: seed.attempt ?? 0,
         lastEventSeq: seed.lastEventSeq ?? 0,
+        startedAt: null, // journal-derived below; never trusted from the cache
       };
       inst.cursors[id] = { lastSeq: 0, seenEventIds: new Set() };
       inst.journalSeq[id] = 0;
@@ -471,6 +653,12 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
     for (const [id] of nodeMap) {
       for await (const ev of readJournal(dir, opId(planInstanceId, id))) {
         inst.journalSeq[id] = ev.seq;
+        // a TIMEOUT deadline is anchored to the FIRST activation record's
+        // journal timestamp — replay must land on the same deadline
+        if (ev.eventType === 'operation.transition' && ev.safePayload?.to === 'starting'
+          && inst.nodes[id].startedAt == null) {
+          inst.nodes[id].startedAt = Date.parse(ev.observedAt) || null;
+        }
       }
     }
     // continuation registration survived the crash on disk — recover the ids
@@ -505,6 +693,11 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
     const pi = sep > 0 ? event.operationId.slice(0, sep) : null;
     const inst = pi ? await ensureInst(pi) : null;
     if (!inst) return { consumed: false, code: 'unroutable' };
+
+    // fire elapsed TIMEOUT deadlines before the delivered event is
+    // evaluated: a deadline wins the same-instant race (deterministic),
+    // and journaled wrapper folds replay identically on resume
+    const swept = await sweepTimeouts(inst);
     const { nodeId, node, matched } = findWaiting(inst, event);
     const cursor = inst.cursors[nodeId] ?? { lastSeq: 0, seenEventIds: new Set() };
 
@@ -559,7 +752,7 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
       return { consumed: false, code: 'duplicate' };
     }
 
-    const transitions = [await applyOutcome(inst, nodeId, node, outcome, event)];
+    const transitions = [...swept, await applyOutcome(inst, nodeId, node, outcome, event)];
     await persist(inst);
     return { consumed: true, transitions };
   }
@@ -584,6 +777,11 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
         cursor.seenEventIds.add(ev.eventId);
         if (ev.eventType === 'operation.transition' && ev.safePayload?.to) {
           derived = ev.safePayload.to;
+          // deadline anchor for TIMEOUT wrappers: the journaled activation
+          // timestamp, identical across replay (never the resume clock)
+          if (ev.safePayload.to === 'starting' && inst.nodes[nodeId].startedAt == null) {
+            inst.nodes[nodeId].startedAt = Date.parse(ev.observedAt) || null;
+          }
         } else {
           delivered.push(ev);
         }
@@ -614,6 +812,44 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
         await activate(inst, nodeId, { suppressStart: true });
       }
     }
+
+    // IR v2 wrapper post-pass: wrappers replay no journal of their own
+    // outcome — they join/resolve deterministically from child states.
+    // A crash between fan-out and join is folded here: completed children
+    // are never re-activated (their journals are terminal), queued children
+    // of an already-started wrapper re-arm via the suppressed activation
+    // path, and a non-idempotent child still mid-flight already resolved
+    // to recovery_required in the main loop above (propagated to the
+    // wrapper by markRecoveryRequired).
+    for (const [nodeId, node] of inst.nodeMap) {
+      const wstate = inst.nodes[nodeId].state;
+      if (node.op === 'PARALLEL' && (wstate === 'starting' || wstate === 'running')) {
+        if (wstate === 'starting') await moveNode(inst, nodeId, 'running');
+        // a crash between the child's recovery record and the wrapper
+        // propagation leaves the join hanging — propagate on replay
+        if ((node.children ?? []).some((c) => inst.nodes[c]?.state === 'recovery_required')) {
+          await moveNode(inst, nodeId, 'recovery_required', { reason: 'child_recovery' });
+          continue;
+        }
+        for (const childId of node.children ?? []) {
+          if (inst.nodes[childId].state === 'queued') {
+            await activate(inst, childId, { suppressStart: true });
+          }
+        }
+        const folded = await resolveParallel(inst, nodeId);
+        if (folded) report.recovered.push(nodeId);
+      }
+      if (node.op === 'TIMEOUT' && (wstate === 'starting' || wstate === 'running')) {
+        if (wstate === 'starting') await moveNode(inst, nodeId, 'running');
+        if (inst.nodes[node.node]?.state === 'queued') {
+          await activate(inst, node.node, { suppressStart: true });
+        }
+        const resolved = isTerminal(inst.nodes[node.node]?.state)
+          ? await resolveTimeout(inst, nodeId)
+          : (await sweepTimeouts(inst)).length > 0;
+        if (resolved) report.recovered.push(nodeId);
+      }
+    }
     await persist(inst);
     report.status = inst.forcedStatus ?? planStatus(inst);
     return report;

package/src/core/runtimeConfig.js

@@ -431,14 +431,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     learning: {
       feedback: { enabled: true, maxEvents: 200 },
       proposals: { minCount: 3, minSessions: 2 },
-      episodes: { autoWrite: false },
+      episodes: { autoWrite: true },
       tuning: { enabled: true, applyMode: 'manual' },
       // C52 M04.2 stage keys (SPEC §5 FR-016–FR-018). candidates: repeated
       // corrections/suppressions/escalations promote to a LearningCandidate
       // only after minOccurrences + cross-session evidence; report-only at
       // 'shadow'. overlays: delta overlays on policy fields; base-version
       // mismatch → conflict, never silent apply. Promotion stays manual.
-      candidates: { stage: 'off', minOccurrences: 3 },
+      candidates: { stage: 'shadow', minOccurrences: 3 },
       overlays: { stage: 'off' },
     },
     // C52 M04.1 compact resumable state (SPEC §5 FR-012–FR-015). Stage 'off'

package/template_project/ukit/storage/config.json

@@ -342,14 +342,14 @@
       "minSessions": 2
     },
     "episodes": {
-      "autoWrite": false
+      "autoWrite": true
     },
     "tuning": {
       "enabled": true,
       "applyMode": "manual"
     },
     "candidates": {
-      "stage": "off",
+      "stage": "shadow",
       "minOccurrences": 3
     },
     "overlays": {
@@ -772,5 +772,8 @@
         "specRequired": "true = handoff-create b\u1eaft bu\u1ed9c vi\u1ebft docs/AI_HANDOFF/SPEC.md chi ti\u1ebft tr\u01b0\u1edbc khi t\u1ea1o task."
       }
     }
+  },
+  "observability": {
+    "stage": "default"
   }
-}
+}