@ngockhoale/ukit 3.3.2 → 3.4.0

package/src/core/agentRuntime/shadowRun.js

@@ -22,16 +22,35 @@
  * unroutable node degrades to the deterministic escalation lane
  * (recovery_required) exactly as the V-05 contract requires.
  *
+ * Live lane (BL-031): `runLivePlan` drives the same engine through the
+ * REAL startFn — a `createSupervisor` launch per RUN node rooted at
+ * `.ukit/storage/agent-runtime/live/<planId>/`. Only plan specs carrying
+ * the supervisor contract (`spec.command` or `spec.argv`) launch;
+ * descriptive `spec.cmd` prose is never shelled out — an unlaunchable
+ * spec resolves its node 'failed' with the launch code recorded.
+ * Supervisor terminal outcomes are relayed back into the engine as
+ * selector-matched `operation.completed` events. The lane is gated at
+ * `decisionRuntime.vm` canary/default: 'off' → `stage_off`, 'shadow' →
+ * `live_stage_required`, both zero-write typed refuses.
+ *
+ * Replay comparison (BL-031): `buildReplayComparison` pairs VM replay
+ * verdicts with archived doc-pipeline outcomes and applies the
+ * pre-registered promotion bar verbatim — promote ONLY if the VM catches
+ * ≥1 defect the doc pipeline missed OR cuts cycle time ≥25% at equal
+ * verdicts. `recordReplayComparison` appends the artifact to the evidence
+ * store where `ukit vm evidence` reports it.
+ *
  * Never throws: every failure resolves to a typed
  * `{ ok:false, code, reason }` — `stage_off` (decisionRuntime.vm 'off' →
- * zero filesystem writes, G-D1), plan-load error codes verbatim from
- * loadPlan, `malformed_plan`, `unknown_plan_id`, `engine_error`,
- * `unterminated` (bounded-loop guard tripped).
+ * zero filesystem writes, G-D1), `live_stage_required`, plan-load error
+ * codes verbatim from loadPlan, `malformed_plan`, `unknown_plan_id`,
+ * `engine_error`, `unterminated` (bounded-loop guard tripped).
  *
  * Evidence (D-03): each run appends one JSONL record to
  * `.ukit/storage/agent-runtime/evidence/<key>.jsonl`
- * `{planId, irHash, planVersion, planInstanceId, status, transitions,
+ * `{planId, irHash, planVersion, planInstanceId, status, lane?, transitions,
  *   wallMs, qualityDelta, wallP95Ratio, costRatio, forbidden, at}` —
+ * `lane:'live'` marks records produced by runLivePlan (absent = shadow).
  * qualityDelta/wallP95Ratio/costRatio stay `null` until a measured
  * baseline exists (promotion.js treats missing metrics as non-passing,
  * so shadow evidence can never self-promote). The file rotates to
@@ -43,8 +62,9 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
 import { resolveDecisionRuntimeStage } from '../runtimeConfig.js';
-import { isTerminal, CONTRACT_VERSION } from './contract.js';
+import { isTerminal, CONTRACT_VERSION, SIDE_EFFECT_CLASSES } from './contract.js';
 import { createVmEngine } from './vmEngine.js';
+import { createSupervisor } from './supervisor.js';
 import { loadPlan } from './planLibrary.js';
 
 const RUNTIME_REL = path.join('.ukit', 'storage', 'agent-runtime');
@@ -382,3 +402,459 @@ async function engineStateSafe(engine, pi) {
     return null;
   }
 }
+
+// --- BL-031: live lane (real startFn) --------------------------------------
+
+// Live runs are the evidence-gated lane: only canary/default stages execute
+// real operation launches. 'shadow' is evidence collection via replay only.
+const LIVE_STAGES = new Set(['canary', 'default']);
+
+// Poll cadence and a hard wall budget for the live driver loop. A launched
+// op can legitimately run for minutes; nodes whose spec cannot produce an
+// outcome (parked WAIT_EVENT/BRANCH, lost launches) surface 'unterminated'
+// the moment nothing is pending rather than spinning to the deadline.
+const LIVE_POLL_MS = 50;
+const LIVE_MAX_WALL_MS = 10 * 60 * 1000;
+
+const SIDE_EFFECT_SET = new Set(SIDE_EFFECT_CLASSES);
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Translate a plan-node spec into a supervisor launch spec, or null when
+ * the spec is not launchable. `spec.cmd` in the plan DSL is descriptive
+ * prose — it is never shelled out; only the supervisor contract fields
+ * (`spec.command` or `spec.argv`) produce a real child process.
+ */
+function liveLaunchSpec(pi, nodeId, node, attempt) {
+  const spec = node?.spec && typeof node.spec === 'object' ? node.spec : {};
+  const argv = Array.isArray(spec.argv) && spec.argv.length > 0
+    && spec.argv.every((a) => typeof a === 'string' && a !== '')
+    ? spec.argv : null;
+  const command = typeof spec.command === 'string' && spec.command !== ''
+    ? spec.command : null;
+  if (argv == null && command == null) return null;
+  const firstClass = Array.isArray(spec.sideEffects) ? spec.sideEffects[0] : null;
+  const retryClass = node?.retry?.sideEffectClass;
+  const sideEffectClass = SIDE_EFFECT_SET.has(firstClass)
+    ? firstClass
+    : (SIDE_EFFECT_SET.has(retryClass) ? retryClass : 'write');
+  const launch = {
+    // one supervisor operation per attempt — a retry must land on a fresh
+    // journal, not collide with the previous attempt's seq
+    operationId: `${pi}:${nodeId}:a${attempt}`,
+    attempt,
+    sideEffectClass,
+  };
+  if (argv != null) launch.argv = argv;
+  else launch.command = command;
+  if (typeof spec.cwd === 'string' && spec.cwd !== '') launch.cwd = spec.cwd;
+  if (spec.env !== null && typeof spec.env === 'object' && !Array.isArray(spec.env)) {
+    launch.env = spec.env;
+  }
+  if (typeof spec.host === 'string' && spec.host !== '') launch.host = spec.host;
+  if (Number.isInteger(node?.timeoutMs) && node.timeoutMs > 0) {
+    launch.wallTimeoutMs = node.timeoutMs;
+  }
+  return launch;
+}
+
+/** SemanticEvent relaying a supervised terminal outcome into the engine. */
+function liveOutcomeEvent(pi, nodeId, node, seq, outcome, observedAt, code) {
+  return {
+    eventId: `live-${pi}-${nodeId}-${seq}`,
+    operationId: `${pi}:${nodeId}`,
+    seq,
+    eventType: node?.selector?.eventType ?? 'operation.completed',
+    observedAt,
+    producerVersion: 'ukit-vm-live',
+    contractVersion: CONTRACT_VERSION,
+    privacyClass: 'internal',
+    artifactRefs: [],
+    safePayload: {
+      outcome,
+      ...(typeof code === 'string' && code !== '' ? { code } : {}),
+    },
+  };
+}
+
+/**
+ * Run one plan through the REAL live path: a real `createVmEngine` (journals
+ * under `.ukit/storage/agent-runtime/live/<planId>/`) whose `startFn`
+ * launches RUN-node specs through `createSupervisor`, and a driver that
+ * relays each supervised terminal outcome back into the engine as a
+ * selector-matched outcome event.
+ *
+ * Stage gate (BL-031): 'off' → `stage_off`; 'shadow' → `live_stage_required`
+ * — both typed refuses with zero writes. Execution requires canary/default.
+ *
+ * A run that reaches a terminal status (incl. 'unterminated' — a real
+ * bounded outcome, e.g. a plan parked on a producer-free WAIT_EVENT)
+ * appends one evidence record with `lane:'live'`; 'failed' and
+ * 'recovery_required' mark the run forbidden. Never throws.
+ *
+ * @param {string} planId
+ * @param {{projectRoot?: string, config?: object, plansDir?: string,
+ *   engineDir?: string, supervisorDir?: string, supervisor?: object,
+ *   classifyFn?: Function, decisionClient?: object, decider?: object,
+ *   evidence?: boolean, maxWallMs?: number, pollMs?: number}} [opts]
+ *   `supervisor` passthrough injects createSupervisor opts (spawnImpl etc.)
+ *   for tests; `plansDir`/`engineDir`/`supervisorDir` are fixture escapes —
+ *   the CLI never passes them.
+ * @returns {Promise<object>} frozen result or typed refuse — same shape as
+ *   runShadowPlan's contract.
+ */
+export async function runLivePlan(planId, opts = {}) {
+  const { projectRoot, config = null } = opts;
+  try {
+    const stage = resolveDecisionRuntimeStage(config, 'vm');
+    if (stage === 'off') {
+      return refuse('stage_off', 'decisionRuntime.vm.stage is off — zero writes');
+    }
+    if (!LIVE_STAGES.has(stage)) {
+      return refuse(
+        'live_stage_required',
+        `decisionRuntime.vm.stage is ${stage} — live execution requires canary or default`,
+      );
+    }
+
+    const loaded = loadPlan(planId, {
+      ...(opts.plansDir ? { plansDir: opts.plansDir } : {}),
+      config,
+    });
+    if (!loaded.ok) {
+      const first = loaded.errors?.[0] ?? {};
+      return refuse(
+        typeof first.code === 'string' ? first.code : 'plan_not_found',
+        `${planId}: ${JSON.stringify(first)}`,
+      );
+    }
+    const plan = loaded.plan;
+    if (!plan || !(plan.nodes instanceof Map) || plan.nodes.size === 0) {
+      return refuse('malformed_plan', `${planId}: compiled plan has no nodes`);
+    }
+
+    const dir = typeof opts.engineDir === 'string' && opts.engineDir !== ''
+      ? opts.engineDir
+      : (typeof projectRoot === 'string' && projectRoot !== ''
+        ? path.join(runtimeDir(projectRoot), 'live', planId)
+        : null);
+    if (dir == null) return refuse('invalid_root', 'projectRoot or engineDir required');
+
+    const supDir = typeof opts.supervisorDir === 'string' && opts.supervisorDir !== ''
+      ? opts.supervisorDir
+      : path.join(dir, 'supervisor');
+
+    // The vm stage is this lane's gate; the supervisor's own
+    // decisionRuntime.supervisor.stage kill switch still applies — an
+    // operator-set 'off' refuses launches typed and fails the node honestly.
+    const supervisor = createSupervisor({
+      runtimeDir: supDir,
+      config,
+      // closeWaitMs is capped low: supervisor.close()'s deadline timer keeps
+      // the event loop alive for its full span even when op chains already
+      // settled — 250ms still drains terminal journals without parking the
+      // CLI for the library default (5s per run).
+      limits: { closeWaitMs: 250 },
+      ...(opts.supervisor && typeof opts.supervisor === 'object' ? opts.supervisor : {}),
+    });
+
+    const inFlight = new Map();   // nodeId -> supervisor start() handle
+    const launchErrors = new Map(); // nodeId -> typed code (preflight/launch refuse)
+    const attempts = new Map();   // nodeId -> attempt counter (journal-safe opIds)
+
+    // REAL startFn: every activated RUN node launches a supervised child.
+    // A spec outside the supervisor contract (descriptive `spec.cmd`) never
+    // reaches spawn — its failure code is delivered as a 'failed' outcome.
+    const startFn = async (spec, { planInstanceId, nodeId, node }) => {
+      const attempt = (attempts.get(nodeId) ?? 0) + 1;
+      attempts.set(nodeId, attempt);
+      const launchSpec = liveLaunchSpec(planInstanceId, nodeId, node ?? { spec }, attempt);
+      if (launchSpec == null) {
+        launchErrors.set(nodeId, 'invalid_spec');
+        return;
+      }
+      try {
+        const res = await supervisor.start(launchSpec, {});
+        if (res?.unsupported) {
+          launchErrors.set(nodeId, res.code ?? 'launch_refused');
+        } else if (res?.ok === false) {
+          launchErrors.set(nodeId, res.code ?? 'launch_failed');
+        } else {
+          inFlight.set(nodeId, res);
+        }
+      } catch (err) {
+        launchErrors.set(nodeId, err?.code ?? 'launch_error');
+      }
+    };
+
+    const engine = createVmEngine({
+      dir,
+      ...(typeof opts.classifyFn === 'function' ? { classifyFn: opts.classifyFn } : {}),
+      ...(opts.decisionClient != null ? { decisionClient: opts.decisionClient } : {}),
+      ...(opts.decider != null ? { decider: opts.decider } : {}),
+      startFn,
+      config,
+    });
+
+    const started = Date.now();
+    const maxWallMs = Number.isInteger(opts.maxWallMs) && opts.maxWallMs > 0
+      ? opts.maxWallMs : LIVE_MAX_WALL_MS;
+    const pollMs = Number.isInteger(opts.pollMs) && opts.pollMs > 0
+      ? opts.pollMs : LIVE_POLL_MS;
+    const deadline = started + maxWallMs;
+
+    let pi = null;
+    const transitions = [];
+    let status = 'running';
+    try {
+      const startRes = await engine.start(plan);
+      if (!startRes || startRes.unsupported || typeof startRes.planInstanceId !== 'string') {
+        return refuse('malformed_plan', `${planId}: engine refused start (${startRes?.code ?? 'no instance'})`);
+      }
+      pi = startRes.planInstanceId;
+
+      while (Date.now() <= deadline) {
+        // eslint-disable-next-line no-await-in-loop
+        const snapshot = await engine.state(pi);
+        status = snapshot.status;
+        if (isTerminal(status) || status === 'recovery_required') break;
+
+        let acted = false;
+        const seqFor = (nodeId) => (snapshot.cursor?.[nodeId] ?? 0) + 1;
+        const observed = () => new Date().toISOString();
+
+        // Deliver preflight/launch failures for nodes still 'running'.
+        for (const [nodeId, code] of launchErrors) {
+          if (snapshot.nodes[nodeId]?.state === 'running' && !inFlight.has(nodeId)) {
+            // eslint-disable-next-line no-await-in-loop
+            const res = await engine.deliver(
+              liveOutcomeEvent(pi, nodeId, plan.nodes.get(nodeId), seqFor(nodeId), 'failed', observed(), code),
+            );
+            if (!res.consumed) {
+              return refuse('event_not_consumed',
+                `${planId}/${nodeId}: deliver rejected (${res.code ?? 'unknown'})`);
+            }
+            for (const t of res.transitions ?? []) {
+              transitions.push({ node: t.node, to: t.to, ...(t.branch !== undefined ? { branch: t.branch } : {}) });
+            }
+            launchErrors.delete(nodeId);
+            acted = true;
+            break; // re-snapshot after each delivered event (shadow parity)
+          }
+        }
+        if (acted) continue;
+
+        // Relay terminal supervisor outcomes back into the engine.
+        for (const [nodeId, handle] of inFlight) {
+          const opState = handle?.currentState;
+          if (opState === 'completed' || opState === 'failed' || opState === 'cancelled') {
+            // eslint-disable-next-line no-await-in-loop
+            const res = await engine.deliver(
+              liveOutcomeEvent(pi, nodeId, plan.nodes.get(nodeId), seqFor(nodeId), opState, observed()),
+            );
+            if (!res.consumed) {
+              return refuse('event_not_consumed',
+                `${planId}/${nodeId}: deliver rejected (${res.code ?? 'unknown'})`);
+            }
+            for (const t of res.transitions ?? []) {
+              transitions.push({ node: t.node, to: t.to, ...(t.branch !== undefined ? { branch: t.branch } : {}) });
+            }
+            inFlight.delete(nodeId);
+            acted = true;
+            break;
+          }
+        }
+        if (acted) continue;
+
+        // Terminate honestly as soon as nothing can still produce an
+        // outcome: a running RUN node with neither a live op nor a pending
+        // launch failure is a driver fault — never spin it to the wall cap.
+        let pending = false;
+        let launchlessRun = false;
+        for (const [id, rec] of Object.entries(snapshot.nodes)) {
+          if (rec.state !== 'running') continue;
+          const op = plan.nodes.get(id)?.op;
+          if (op === 'RUN') {
+            if (inFlight.has(id) || launchErrors.has(id)) pending = true;
+            else launchlessRun = true;
+          } else if (op === 'WAIT_EVENT' || op === 'BRANCH') {
+            pending = true;
+          }
+        }
+        if (launchlessRun) break;
+        if (!pending) break;
+
+        // eslint-disable-next-line no-await-in-loop
+        await sleep(pollMs);
+      }
+    } catch (err) {
+      return refuse('engine_error', err?.code ?? String(err));
+    } finally {
+      try { await engine.close(); } catch { /* persist-best-effort; run result stands */ }
+      try { await supervisor.close(); } catch { /* kill+drain best-effort */ }
+    }
+
+    const final = pi ? await engineStateSafe(engine, pi) : null;
+    if (final) status = final.status;
+    const wallMs = Date.now() - started;
+
+    const nodeStates = {};
+    for (const [id, n] of Object.entries(final?.nodes ?? {})) {
+      nodeStates[id] = { state: n.state, attempt: n.attempt };
+    }
+
+    const resolved = isTerminal(status) || status === 'recovery_required';
+    const result = Object.freeze({
+      ok: true,
+      code: resolved ? status : 'unterminated',
+      planId,
+      planInstanceId: pi,
+      status: resolved ? status : 'unterminated',
+      transitions: Object.freeze(transitions),
+      nodeStates: Object.freeze(nodeStates),
+      wallMs,
+      irHash: loaded.irHash,
+      planVersion: loaded.planVersion,
+    });
+
+    // D-03 evidence append (caller may opt out with evidence:false). Live
+    // rows carry lane:'live'; 'unterminated' is a recorded real outcome,
+    // not a refuse — the evidence bar needs it counted honestly.
+    if (opts.evidence !== false && typeof projectRoot === 'string' && projectRoot !== '') {
+      const append = await appendEvidence(projectRoot, {
+        planId,
+        irHash: loaded.irHash,
+        planVersion: loaded.planVersion,
+        planInstanceId: pi,
+        status: result.status,
+        lane: 'live',
+        transitions: transitions.length,
+        wallMs,
+        qualityDelta: null,
+        wallP95Ratio: null,
+        costRatio: null,
+        // Live failures and recovery ambiguities are forbidden lanes;
+        // 'unterminated'/'cancelled' are bounded honest outcomes.
+        forbidden: result.status === 'failed' || result.status === 'recovery_required',
+        at: new Date().toISOString(),
+      }, { key: 'vm' });
+      if (!append.ok) {
+        return refuse('evidence_write_error', `${planId}: ${append.reason}`);
+      }
+    }
+    return result;
+  } catch (err) {
+    // Outer never-throws guard — same contract as runShadowPlan.
+    return refuse('engine_error', err?.code ?? String(err?.message ?? err));
+  }
+}
+
+// --- BL-031: replay comparison artifact ------------------------------------
+
+/**
+ * The pre-registered BL-031 promotion bar, verbatim (frozen before any
+ * comparison exists): the live lane promotes ONLY if the VM catches ≥1
+ * defect the doc pipeline missed OR cuts cycle time ≥25% at equal verdicts
+ * — otherwise it stays shadow. `promote()` remains the only mechanism that
+ * can move a stage; this artifact is recorded evidence, never a write.
+ */
+export const REPLAY_PROMOTION_BAR = Object.freeze({
+  minDefectsCaught: 1,
+  minCycleTimeCutRatio: 0.25,
+});
+
+const COMPARISON_KIND = 'replay-comparison';
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+
+function replayRow(input) {
+  const r = input && typeof input === 'object' ? input : {};
+  const vm = typeof r.vmVerdict === 'string' ? r.vmVerdict : 'unknown';
+  const doc = typeof r.docVerdict === 'string' ? r.docVerdict : 'unknown';
+  return {
+    planId: typeof r.planId === 'string' ? r.planId : 'unknown',
+    vmVerdict: vm,
+    docVerdict: doc,
+    vmWallMs: isNum(r.vmWallMs) ? r.vmWallMs : null,
+    docWallMs: isNum(r.docWallMs) ? r.docWallMs : null,
+    equalVerdicts: vm === doc,
+    // Asymmetric on purpose: the VM catching what the doc lane called good
+    // is evidence FOR promotion; the doc lane catching what the VM missed
+    // is evidence AGAINST — never counted as a VM save.
+    defectCaught: vm !== doc && doc === 'completed',
+  };
+}
+
+/**
+ * Pair VM replay verdicts with archived doc-pipeline outcomes and apply the
+ * pre-registered bar. Pure: no I/O, never throws — missing/malformed fields
+ * degrade to 'unknown' verdicts and null timings.
+ *
+ * Verdict order: defects caught → verdict divergence → ≥25% cycle-time cut
+ * (only when EVERY row carries both timings — archived runs with thin
+ * telemetry resolve 'insufficient_data:cycle_time', never a fabricated pass)
+ * → 'bar_not_met'.
+ *
+ * @param {object[]} replays [{planId, vmVerdict, docVerdict, vmWallMs?, docWallMs?}]
+ * @returns {object} frozen { kind, bar, rows, defectsCaught, divergedRows,
+ *   timedRows, timedRatio, verdict, reason }
+ */
+export function buildReplayComparison(replays = []) {
+  const rows = (Array.isArray(replays) ? replays : []).map(replayRow);
+  const defectsCaught = rows.filter((r) => r.defectCaught).length;
+  const divergedRows = rows.filter((r) => !r.equalVerdicts && !r.defectCaught).length;
+  const timedRows = rows.filter((r) => isNum(r.vmWallMs) && isNum(r.docWallMs)).length;
+  let timedRatio = null;
+  if (rows.length > 0 && timedRows === rows.length) {
+    const vmTotal = rows.reduce((s, r) => s + r.vmWallMs, 0);
+    const docTotal = rows.reduce((s, r) => s + r.docWallMs, 0);
+    if (docTotal > 0) timedRatio = (docTotal - vmTotal) / docTotal;
+  }
+  const bar = REPLAY_PROMOTION_BAR;
+  let verdict = 'no-promote';
+  let reason;
+  if (defectsCaught >= bar.minDefectsCaught) {
+    verdict = 'promote';
+    reason = `defects_caught:${defectsCaught}`;
+  } else if (divergedRows > 0) {
+    reason = `verdicts_diverged:${divergedRows}:doc_better`;
+  } else if (timedRatio == null) {
+    reason = 'insufficient_data:cycle_time';
+  } else if (timedRatio >= bar.minCycleTimeCutRatio) {
+    verdict = 'promote';
+    reason = `cycle_time_cut:${timedRatio.toFixed(2)}>=${bar.minCycleTimeCutRatio}`;
+  } else {
+    reason = 'bar_not_met';
+  }
+  return Object.freeze({
+    kind: COMPARISON_KIND,
+    bar,
+    rows: Object.freeze(rows),
+    defectsCaught,
+    divergedRows,
+    timedRows,
+    timedRatio,
+    verdict,
+    reason,
+  });
+}
+
+/**
+ * Build the comparison artifact and append it to the evidence store as one
+ * `kind:'replay-comparison'` record — the surface `ukit vm evidence` reads
+ * to report the recorded promote/no-promote verdict.
+ *
+ * @param {string} projectRoot
+ * @param {object[]} replays
+ * @param {{key?: string}} [opts]
+ * @returns {Promise<{ok:true, record:object, bytes:number}
+ *   |{ok:false, code:string, reason:string}>}
+ */
+export async function recordReplayComparison(projectRoot, replays, { key = 'vm' } = {}) {
+  const record = { ...buildReplayComparison(replays), at: new Date().toISOString() };
+  const append = await appendEvidence(projectRoot, record, { key });
+  if (!append.ok) return append;
+  return { ok: true, record: Object.freeze(record), bytes: append.bytes };
+}

package/src/core/agentRuntime/telemetry.js

@@ -37,6 +37,7 @@ import { sanitizeForSupport } from '../observability/privacy/sanitizeForSupport.
 import { MAX_SUPPORT_STRING_CHARS } from '../observability/privacy/allowlist.js';
 import { redactString } from '../observability/privacy/redaction.js';
 import { scanText } from '../sensitiveValueScanner.js';
+import { resolveConfigStage } from '../runtimeConfig.js';
 
 /** Monotonic nanoseconds — BigInt where available (process.hrtime). */
 export function nowNs() {
@@ -108,6 +109,10 @@ export function resolveTelemetry({ recorder, projectRoot, config, env, clock } =
     recorder: rec,
     agent_id,
     nowNs: clock && typeof clock.nowNs === 'function' ? clock.nowNs.bind(clock) : nowNs,
+    // TASK-C89-002 (SPEC §11): subagentOrchestrator.telemetry is opt-in —
+    // 'off' or absent means recordSubagentUsage is a typed no-op and the
+    // emit path is never touched, preserving route/prompt/Stop parity.
+    subagentTelemetryStage: resolveConfigStage(config, 'subagentOrchestrator.telemetry.stage'),
   };
 }
 
@@ -146,6 +151,9 @@ export function makeSpanContext(parent) {
  * floor. Never throws — a throwing recorder returns a typed drop.
  */
 export function emitSpanRecord(telemetry, ctx, semanticName, payload) {
+  if (telemetry == null || ctx == null || typeof telemetry.recorder?.emit !== 'function') {
+    return { status: 'dropped', reason: 'recorder-disabled' };
+  }
   try {
     return telemetry.recorder.emit({
       semantic_name: semanticName,
@@ -213,6 +221,119 @@ export function typedResource(resource) {
   return { resource: { value, source: 'ESTIMATED' }, complete: true };
 }
 
+// --- TASK-C89-002 subagent usage provenance (SPEC §3 FR-01, §11) -----------
+// `recordSubagentUsage` is observation-only: it emits one 'subagent.usage'
+// span record describing a child run's prompt composition and usage
+// provenance. It never fabricates: bytes are locally measured facts,
+// tokens are deterministic ESTIMATED unless a caller types them, provider
+// usage survives only via typedResource's PROVIDER rule, and unknown
+// lineage/usage stays UNKNOWN/null — never 0, never a guessed id.
+// The emit is gated on subagentOrchestrator.telemetry.stage (off = the
+// lane never touches the recorder — zero-cost typed drop).
+
+/** Deterministic token estimate: ceil(bytes / 4), the repo's TOKEN_CHAR_RATIO
+ *  convention (codeintel/compiler.js). Always labeled ESTIMATED. */
+export function estimateSubagentTokens(bytes) {
+  return Number.isFinite(bytes) && bytes >= 0 ? Math.ceil(bytes / 4) : null;
+}
+
+function sha256Hex(input) {
+  return crypto.createHash('sha256').update(input).digest('hex');
+}
+
+// Normalize one prompt component into a content-free metadata row:
+// {ref, fingerprint, bytes, tokens{value,source}, count}. `text` is hashed
+// and measured, then discarded — raw prompt bodies never enter the payload.
+function componentRow(component) {
+  if (!isPlainObject(component)) return null;
+  const ref = isNonEmptyString(component.ref)
+    ? component.ref
+    : `sha256:component-${sha256Hex(JSON.stringify(component)).slice(0, 16)}`;
+  const text = typeof component.text === 'string' ? component.text : null;
+  const bytes = Number.isFinite(component.bytes) && component.bytes >= 0
+    ? component.bytes
+    : (text !== null ? Buffer.byteLength(text, 'utf8') : null);
+  // The fingerprint binds ref + content so a re-read of the same bytes
+  // dedupes while an edited same-path file cannot pretend to be the same
+  // component. Content hash covers text; absent text it covers bytes only.
+  const contentKey = text !== null ? `text:${sha256Hex(text)}` : `bytes:${bytes}`;
+  const fingerprint = `sha256:${sha256Hex(`${ref}\n${contentKey}`).slice(0, 24)}`;
+  let tokens;
+  if (component.tokens !== undefined) {
+    tokens = typedResource(component.tokens).resource;
+  } else if (bytes !== null) {
+    tokens = { value: estimateSubagentTokens(bytes), source: 'ESTIMATED' };
+  } else {
+    tokens = { value: null, source: 'UNKNOWN' };
+  }
+  return { ref, fingerprint, bytes, tokens, count: 1 };
+}
+
+// Exact dedupe by fingerprint (SPEC §3: exact dedupe only; semantic pruning
+// is deferred). A repeated identical read increments `count` once per extra
+// occurrence and keeps a single row.
+function dedupeComponents(components) {
+  const rows = [];
+  const byFingerprint = new Map();
+  for (const raw of Array.isArray(components) ? components : []) {
+    const row = componentRow(raw);
+    if (row === null) continue;
+    const seen = byFingerprint.get(row.fingerprint);
+    if (seen) {
+      seen.count += 1;
+      continue;
+    }
+    byFingerprint.set(row.fingerprint, row);
+    rows.push(row);
+  }
+  return rows;
+}
+
+/**
+ * Emit one 'subagent.usage' provenance record for a child run.
+ *
+ *   recordSubagentUsage(telemetry, ctx, {components, parentRunId, usage})
+ *     → recorder emit result ({status:'accepted'|...}) or a typed drop.
+ *
+ * `ctx` should come from makeSpanContext(parent) when the parent span was
+ * observed — that is what links child lineage; a fabricated parent id is
+ * never synthesized. `parentRunId` is the caller's observed parent run
+ * identifier (execution_ref family); absent → parent_run_ref: null.
+ *
+ * Stage gate: subagentOrchestrator.telemetry.stage must resolve to
+ * shadow/canary/default; 'off'/absent/garbage returns
+ * {status:'dropped',reason:'stage_off'} without touching the recorder.
+ */
+export function recordSubagentUsage(telemetry, ctx, { components, parentRunId, usage } = {}) {
+  if (telemetry == null) {
+    return { status: 'dropped', reason: 'recorder-disabled' };
+  }
+  if ((telemetry.subagentTelemetryStage ?? 'off') === 'off') {
+    return { status: 'dropped', reason: 'stage_off' };
+  }
+  const rows = dedupeComponents(components);
+  const instanceCount = rows.reduce((n, row) => n + row.count, 0);
+  // Aggregate token estimate is ESTIMATED only when every component's
+  // estimate is numeric; a single unknown component keeps the aggregate
+  // honestly UNKNOWN rather than silently summing a partial.
+  const tokens = rows.length > 0 && rows.every((row) => typeof row.tokens.value === 'number')
+    ? {
+        value: rows.reduce((n, row) => n + row.tokens.value * row.count, 0),
+        source: 'ESTIMATED',
+      }
+    : { value: null, source: 'UNKNOWN' };
+  const { resource, complete } = typedResource(usage);
+  return emitSpanRecord(telemetry, ctx, 'subagent.usage', {
+    kind: 'child-run',
+    parent_run_ref: isNonEmptyString(parentRunId) ? parentRunId : null,
+    components: rows,
+    count: instanceCount,
+    tokens,
+    resource,
+    telemetry_complete: complete,
+  });
+}
+
 // --- V-06 trace excerpt for support bundles --------------------------------
 // `buildTraceExcerpt` is the read-side counterpart of emitSpanRecord: it
 // turns recorder-fed SemanticRecords into bounded, sanitized trace lines