@ngockhoale/ukit 3.1.9 → 3.3.0

package/src/core/agentRuntime/telemetry.js

@@ -7,6 +7,7 @@
  *   emitSpanRecord(telemetry, ctx, semanticName, payload) → EmitResult
  *   durationMs(startNs, nowNs) → positive ms | null
  *   projectRootFromRuntimeDir(runtimeDir) → projectRoot | null
+ *   buildTraceExcerpt(records, opts) → {entries, gaps, stats} (V-06)
  *
  * Contracts:
  *   - Emission is fire-and-forget: every helper is synchronous, wraps
@@ -31,6 +32,11 @@ import path from 'node:path';
 import { getRecorder } from '../observability/emit/lifecycle.js';
 import { RESOURCE_SOURCES } from '../observability/schema/constants.js';
 import { REASON_CODES } from '../observability/schema/registry.js';
+import { validateSemanticRecord } from '../observability/schema/validate.js';
+import { sanitizeForSupport } from '../observability/privacy/sanitizeForSupport.js';
+import { MAX_SUPPORT_STRING_CHARS } from '../observability/privacy/allowlist.js';
+import { redactString } from '../observability/privacy/redaction.js';
+import { scanText } from '../sensitiveValueScanner.js';
 
 /** Monotonic nanoseconds — BigInt where available (process.hrtime). */
 export function nowNs() {
@@ -55,6 +61,10 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && value.length > 0;
 }
 
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
 /**
  * agent_id source (SPEC §14): UKIT_AGENT_ID env first, config.agent.id
  * second, absent otherwise. The field is omitted entirely — never ''.
@@ -202,3 +212,116 @@ export function typedResource(resource) {
   if (source && source !== 'UNKNOWN') return { resource: { value, source }, complete: true };
   return { resource: { value, source: 'ESTIMATED' }, complete: true };
 }
+
+// --- 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
+// for a support bundle. Every record passes validateSemanticRecord AND
+// the independent sanitizeForSupport second gate; survivors keep only
+// allowlisted envelope/payload fields, strings pass redactString, and
+// caller-supplied pseudonyms replace raw ids. Non-conforming records are
+// reported as typed gap entries — never silently smuggled, never thrown.
+
+const TRACE_ID_FIELDS = Object.freeze([
+  'record_id', 'trace_id', 'span_id', 'parent_span_id',
+  'execution_id', 'session_id', 'project_ref', 'boot_id', 'writer_id',
+]);
+
+const TRACE_ENVELOPE_KEEP = new Set([
+  'record_type', 'semantic_name', 'schema_version', 'record_id', 'trace_id',
+  'span_id', 'parent_span_id', 'execution_id', 'session_id', 'project_ref',
+  'boot_id', 'writer_id', 'sequence', 'wall_time_utc', 'monotonic_ns',
+  'importance', 'privacy_class', 'redaction_version', 'sampling',
+]);
+
+/**
+ * Build a sanitized trace excerpt from SemanticRecords. Never throws.
+ *
+ * Every record passes the FULL two-gate chain — validateSemanticRecord
+ * then the independent sanitizeForSupport default-deny gate — so a
+ * survivor's payload is already allowlist-clean (codes, counts, timings
+ * only). The excerpt keeps only the envelope fields named in
+ * TRACE_ENVELOPE_KEEP, re-passes strings through redactString, and
+ * substitutes caller-supplied pseudonyms for raw ids. Rejects land as
+ * typed gap entries — never silently smuggled, never thrown.
+ *
+ * @param {unknown} records array of records (non-array → 'trace_unavailable')
+ * @param {object} [opts]
+ * @param {number} [opts.maxRecords=256] entry cap (gaps share the budget)
+ * @param {(value:string)=>{hasSecret:boolean}} [opts.scanner] defaults scanText
+ * @param {(value:string,kind:string)=>string} [opts.pseudonymize] id rewrite
+ * @returns {{ entries: Array, gaps: Array, stats: {in:number, kept:number,
+ *   rejected:number, truncated:number} }}
+ */
+
+export function buildTraceExcerpt(records, opts = {}) {
+  const maxRecords = Number.isInteger(opts.maxRecords) ? Math.max(0, opts.maxRecords) : 256;
+  const scanner = typeof opts.scanner === 'function' ? opts.scanner : scanText;
+  const pseudonymize = typeof opts.pseudonymize === 'function' ? opts.pseudonymize : null;
+  const local = { scanner, maxChars: MAX_SUPPORT_STRING_CHARS };
+
+  const entries = [];
+  const gaps = [];
+  const stats = { in: 0, kept: 0, rejected: 0, truncated: 0 };
+
+  if (!Array.isArray(records)) {
+    gaps.push({ index: 0, code: 'trace_unavailable' });
+    return { entries, gaps, stats };
+  }
+
+  for (const record of records) {
+    stats.in += 1;
+    if (entries.length + gaps.length >= maxRecords) {
+      stats.truncated += 1;
+      continue;
+    }
+    const index = stats.in - 1;
+    if (!isPlainObject(record)) {
+      stats.rejected += 1;
+      gaps.push({ index, code: 'record_not_object' });
+      continue;
+    }
+    const valid = validateSemanticRecord(record);
+    if (!valid.ok) {
+      stats.rejected += 1;
+      gaps.push({ index, code: 'schema_rejected' });
+      continue;
+    }
+    const gate = sanitizeForSupport(record, { scanner });
+    if (!gate.ok) {
+      stats.rejected += 1;
+      gaps.push({ index, code: 'support_gate_rejected' });
+      continue;
+    }
+
+    const out = {};
+    for (const key of Object.keys(gate.record)) {
+      if (!TRACE_ENVELOPE_KEEP.has(key)) continue;
+      const value = gate.record[key];
+      if (key === 'sampling') {
+        const s = isPlainObject(value) ? value : {};
+        out.sampling = {
+          policy_version: typeof s.policy_version === 'string'
+            ? redactString(s.policy_version, local) : null,
+          rate: typeof s.rate === 'number' && Number.isFinite(s.rate) ? s.rate : null,
+        };
+        continue;
+      }
+      if (TRACE_ID_FIELDS.includes(key) && typeof value === 'string') {
+        out[key] = pseudonymize ? pseudonymize(value, key) : redactString(value, local);
+        continue;
+      }
+      if (typeof value === 'string') {
+        out[key] = redactString(value, local);
+        continue;
+      }
+      out[key] = value;
+    }
+    // The gate already allowlist-pruned the payload — copy it verbatim.
+    out.payload = gate.record.payload;
+
+    entries.push(out);
+    stats.kept += 1;
+  }
+  return { entries, gaps, stats };
+}

package/src/core/agentRuntime/vmEngine.js

@@ -1,7 +1,8 @@
 /**
  * agentRuntime/vmEngine.js — decision-first-runtime G4 (DR-06), VM vertical
- * slice, omp-scoped, off-rollout (gated by host-side `decisionRuntime.vm`
- * flag; this module reads no config itself).
+ * slice, omp-scoped, off-rollout (`decisionRuntime.vm` gates the V-05
+ * decision-plane classifyFn default below; deterministic escalation stays
+ * the default lane regardless of the flag).
  *
  * Executes a compiled ValidatedPlan (SPEC §4 frozen shape — literal nodes
  * Map, entryNodes, topological order) purely against G1 durable
@@ -39,7 +40,11 @@ import {
   validateTransition,
   validateSemanticEvent,
   validateRetry,
+  validateClassifyVerdict,
 } from './contract.js';
+import { resolveDecisionRuntimeStage } from '../runtimeConfig.js';
+import { createDecisionClient } from '../../decision/client.js';
+import { createVmClassifyFn } from '../../decision/runtimeDecide.js';
 import {
   registerContinuation,
   consumeContinuation,
@@ -88,18 +93,48 @@ async function writeFileAtomic(target, data) {
   await fs.rename(tmp, target);
 }
 
+
 /**
  * Migration contract (decision plane): `classifyFn` is invoked only when the
  * IR itself cannot route an event (see deliver()). It may only consult the
  * decision plane (unic-decision / createDecisionClient registry keys) for a
  * bounded route/escalate answer — never a general LLM call.
  *
- * @param {{dir:string, now?:()=>Date, classifyFn?:Function, startFn?:Function, hooks?:object}} opts
+ * V-05 default: when no `classifyFn` is injected AND
+ * `decisionRuntime.vm.stage` resolves non-'off', the engine installs the
+ * bounded runtimeDecide adapter (runtime.node_route.v1 /
+ * runtime.node_classify.v1 through `decisionClient` — or the default
+ * createDecisionClient when none is injected). Stage 'off' (absent or
+ * malformed) leaves `classifyFn` unset → zero decision calls, byte-identical
+ * behaviour to the deterministic escalation lane.
+ *
+ * @param {{dir:string, now?:()=>Date, classifyFn?:Function, startFn?:Function,
+ *         hooks?:object, config?:object, decisionClient?:object,
+ *         decider?:object}} opts
  */
-export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
+export function createVmEngine({
+  dir,
+  now,
+  classifyFn,
+  startFn,
+  hooks,
+  config,
+  decisionClient,
+  decider,
+} = {}) {
   if (typeof dir !== 'string' || dir === '') {
     throw new VmEngineError('malformed_opts', 'dir required');
   }
+  // The injected classifyFn always wins; the decision-plane adapter is a
+  // stage-gated default for embedders that opt in via runtime config.
+  const classify =
+    classifyFn
+    ?? (resolveDecisionRuntimeStage(config ?? null, 'vm') === 'off'
+      ? undefined
+      : createVmClassifyFn({
+          decider,
+          client: decisionClient ?? createDecisionClient({ config }),
+        }));
   const clock = typeof now === 'function' ? now : () => new Date();
   const fire = typeof startFn === 'function' ? startFn : async () => {};
   const instances = new Map(); // planInstanceId -> instance
@@ -712,20 +747,26 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
 
     // classify only when the IR itself cannot route the event (G4-FR05);
     // classifyFn may consult the decision plane for bounded route/escalate
-    // answers only — never a general LLM call (see createVmEngine opts).
+    // answers only — never a general LLM call (see createVmEngine opts). A
+    // throwing classifyFn or a malformed verdict is an unclassifiable event,
+    // never a hard failure (V-05 never-throws contract).
     let outcome = event.safePayload?.outcome;
     let targetMatched = matched;
     if (!targetMatched) {
-      if (typeof classifyFn !== 'function') {
+      if (typeof classify !== 'function') {
         return escalateUnclassified(inst, event);
       }
-      const verdict = await classifyFn(event, { planInstanceId: pi, nodeId, node });
-      if (verdict?.action === 'escalate' || verdict == null) {
-        return escalateUnclassified(inst, event);
+      let verdict = null;
+      try {
+        verdict = await classify(event, { planInstanceId: pi, nodeId, node });
+      } catch {
+        verdict = null;
       }
-      if (verdict?.action === 'route' && typeof verdict.outcome === 'string') {
+      if (validateClassifyVerdict(verdict).ok && verdict.action === 'route') {
         outcome = verdict.outcome;
         targetMatched = node != null && inst.nodes[nodeId]?.state === 'running';
+      } else {
+        return escalateUnclassified(inst, event);
       }
     }
     if (!targetMatched) return escalateUnclassified(inst, event);

package/src/core/memory/episodes.js

@@ -0,0 +1,168 @@
+// episodes.js — session episode records from exec-ledgers (SPEC §7b).
+//
+// One episode per exec-ledger file, keyed (and deduped) by the ledger file
+// name. Shared by `ukit memory episode` (single session) and the self-improve
+// cycle (backfill every idle ledger), so the record shape has one owner.
+//
+// Engine-agnostic by construction: the self-improve backfill walks the ledger
+// directory instead of trusting a stop event's session id — omp's
+// `session_stop` id and the session key its tool events write under can
+// differ, and Codex has no stop event at all.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { loadRecords } from './storeV2.js';
+import { mutateMemory } from './mutateMemory.js';
+import { detectProjectContext } from '../../context/detectProjectContext.js';
+import { listLedgerFiles, LEDGER_DIR_REL } from '../../diagnostics/ledgerFiles.js';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+// Mirrors execution-ledger.mjs safeSegment — src/ cannot import the runtime
+// module, so the segment rule is duplicated deliberately.
+export function safeSegment(value) {
+  return String(value || 'default')
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]/g, '_')
+    .slice(0, 96) || 'default';
+}
+
+async function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Resolution order: explicit session id → most-recent ledger.
+export async function resolveLedger(projectRoot, sessionId) {
+  const dir = path.join(projectRoot, LEDGER_DIR_REL);
+  if (sessionId) {
+    const file = `${safeSegment(sessionId)}.json`;
+    const ledger = await readJsonIfExists(path.join(dir, file));
+    return { ledger, ledgerKey: file };
+  }
+  const [name] = await listLedgerFiles(dir, 1);
+  if (!name) return { ledger: null, ledgerKey: null };
+  return { ledger: await readJsonIfExists(path.join(dir, name)), ledgerKey: name };
+}
+
+export function episodeText(ledger, sessionId) {
+  const write = ledger.writeSucceeded === true ? 'writeOk' : 'writeFail';
+  const verify = ledger.verificationAttempted !== true
+    ? 'not-run'
+    : ledger.verificationSucceeded === true ? 'ok' : 'fail';
+  const receipts = Array.isArray(ledger.receipts) ? ledger.receipts : [];
+  const lastReceipt = receipts.length > 0 ? receipts[receipts.length - 1] : null;
+  const lastCommand = lastReceipt
+    ? String(lastReceipt?.command ?? '').split('\n')[0].trim() || 'n/a'
+    : 'n/a';
+  const text = `Session ${sessionId}: ${write}, verify=${verify}, `
+    + `${receipts.length} receipts, last command ${lastCommand}`;
+  return text.slice(0, 300);
+}
+
+function ledgerSessionId(ledger, ledgerKey) {
+  return ledger.sessionId ?? ledger.sessionKey
+    ?? (ledgerKey ? ledgerKey.replace(/\.json$/, '') : 'unknown');
+}
+
+// Writes one episode for `ledger`. Returns
+//   { status: 'recorded', id, sessionId } | { status: 'duplicate' }
+//   | { status: 'rejected', result } | { status: 'failed', reason }.
+// `existingKeys` (Set of ledgerKeys already recorded) skips the store read
+// when the caller batches.
+export async function writeEpisode(projectRoot, {
+  ledger,
+  ledgerKey,
+  config,
+  homeDir,
+  projectId,
+  existingKeys,
+} = {}) {
+  const sessionId = ledgerSessionId(ledger, ledgerKey);
+  const keys = existingKeys ?? new Set(
+    (await loadRecords(projectRoot, { homeDir })).map((r) => r.meta?.ledgerKey).filter(Boolean),
+  );
+  if (keys.has(ledgerKey)) return { status: 'duplicate' };
+
+  const ttlDays = Number(config?.memoryV2?.episodeTtlDays) || 90;
+  const resolvedProjectId = projectId
+    ?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
+  // FR-023: the ledger key is the idempotency key — a rerun is a journal
+  // 'duplicate' even when the meta.ledgerKey fast path above is bypassed.
+  const res = await mutateMemory(
+    { kind: 'project', projectRoot, homeDir },
+    {
+      op: 'add',
+      idempotencyKey: ledgerKey,
+      payload: {
+        type: 'episode',
+        scope: 'session',
+        text: episodeText(ledger, sessionId),
+        provenance: 'exec-ledger',
+        confidence: 0.6,
+        createdBy: 'episode-hook',
+        projectId: resolvedProjectId,
+        validUntil: Date.now() + ttlDays * DAY_MS,
+        meta: { sessionId, ledgerKey },
+      },
+    },
+  );
+  if (res.status === 'duplicate') return { status: 'duplicate' };
+  if (res.status === 'rejected') return { status: 'rejected', result: res };
+  if (res.status !== 'ok') {
+    return { status: 'failed', reason: `${res.status}${res.reason ? ` — ${res.reason}` : ''}` };
+  }
+  keys.add(ledgerKey);
+  return { status: 'recorded', id: res.record.id, sessionId };
+}
+
+// Backfills an episode for every ledger that has been idle for `idleMs`
+// (so a live session is never summarized mid-flight) and has none yet.
+// Bounded by `limit` newest ledgers; never throws.
+export async function backfillEpisodes(projectRoot, {
+  config,
+  homeDir,
+  idleMs = 10 * 60 * 1000,
+  limit = 50,
+  now = Date.now(),
+} = {}) {
+  const summary = { scanned: 0, recorded: 0, skipped: 0, failed: 0 };
+  try {
+    if (config?.memoryV2?.enabled === false || config?.learning?.episodes?.autoWrite === false) {
+      return { ...summary, reason: 'disabled' };
+    }
+    const dir = path.join(projectRoot, LEDGER_DIR_REL);
+    const names = await listLedgerFiles(dir, limit);
+    if (names.length === 0) return summary;
+    const existingKeys = new Set(
+      (await loadRecords(projectRoot, { homeDir })).map((r) => r.meta?.ledgerKey).filter(Boolean),
+    );
+    const projectId = (await detectProjectContext(projectRoot, { homeDir })).project.name;
+    for (const name of names) {
+      summary.scanned += 1;
+      if (existingKeys.has(name)) { summary.skipped += 1; continue; }
+      let stat;
+      try { stat = await fs.stat(path.join(dir, name)); } catch { summary.skipped += 1; continue; }
+      if (now - stat.mtimeMs < idleMs) { summary.skipped += 1; continue; }
+      const ledger = await readJsonIfExists(path.join(dir, name));
+      const receipts = Array.isArray(ledger?.receipts) ? ledger.receipts.length : 0;
+      if (!ledger || (receipts === 0 && ledger.writeSucceeded !== true)) {
+        summary.skipped += 1;
+        continue;
+      }
+      const res = await writeEpisode(projectRoot, {
+        ledger, ledgerKey: name, config, homeDir, projectId, existingKeys,
+      });
+      if (res.status === 'recorded') summary.recorded += 1;
+      else if (res.status === 'duplicate') summary.skipped += 1;
+      else summary.failed += 1;
+    }
+  } catch (error) {
+    return { ...summary, reason: error?.message ?? String(error) };
+  }
+  return summary;
+}

package/src/core/metadata.js

@@ -114,6 +114,27 @@ export async function writeInstallMetadata({
   }
 }
 
+export const CLI_LOCATOR_REL = path.join('.ukit', 'storage', 'cli.json');
+
+// `.ukit/storage/cli.json` — absolute node + CLI entry of the install that
+// last refreshed this project. Read by .claude/ukit/runtime/ukit-cli.mjs so
+// hook-side CLI spawns work without `ukit` on the host's PATH. Advisory:
+// a write failure only degrades hooks back to the PATH lookup.
+export async function writeCliLocator({ projectRoot, packageRoot, packageVersion }) {
+  if (!projectRoot || !packageRoot) return false;
+  try {
+    await writeJson(path.join(projectRoot, CLI_LOCATOR_REL), {
+      node: process.execPath,
+      bin: path.join(path.resolve(packageRoot), 'bin', 'ukit'),
+      version: packageVersion ?? null,
+      writtenAt: new Date().toISOString(),
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function removeTrackedPathsFromMetadata({
   installMetaPath,
   projectRoot,

package/src/core/runInstallPipeline.js

@@ -10,7 +10,7 @@ import { buildInstallPlan } from './buildPlan.js';
 import { diffInstallPlan } from './diffPlan.js';
 import { applyDiffResults, pruneOldBackups } from './applyPlan.js';
 import { summarizeDiff, toDiffRows } from './report.js';
-import { writeInstallMetadata } from './metadata.js';
+import { writeInstallMetadata, writeCliLocator } from './metadata.js';
 import { cleanupLegacyPaths, migrateLegacyRuntimeRoot } from './migrateLegacy.js';
 import { ensureGitignore } from './ensureGitignore.js';
 import { repairBrokenHooks } from './repairBrokenHooks.js';
@@ -477,6 +477,11 @@ export async function runInstallPipeline({
       retainedManagedRelativePaths,
     });
 
+    // 3.3.0: hooks spawn the CLI (episodes, self-improve) from a GUI-launched
+    // host whose PATH often lacks nvm/volta shims — `ukit` on PATH silently
+    // failed. Record the absolute node + bin path of THIS install instead.
+    await writeCliLocator({ projectRoot: pathConfig.projectRoot, packageRoot: pathConfig.packageRoot, packageVersion });
+
     const { userLayer, userRows } = await runUserLayerPass({
       pathConfig,
       homeDir,

package/src/core/runtimeConfig.js

@@ -5,6 +5,7 @@ import { buildRuntimePaths } from './runtimePaths.js';
 import { buildUserPaths } from './userPaths.js';
 import { loadShippedCompactBudget } from './compact/contextBudget.js';
 import { buildConfigContracts } from './executionContracts.js';
+import { mergeTunedOverlay } from '../learning/tunedOverlay.js';
 
 const require = createRequire(import.meta.url);
 const { version: PACKAGE_VERSION } = require('../../package.json');
@@ -204,6 +205,18 @@ export function resolveConfigStage(config = null, path) {
   return VALID_ROUTE_STAGES.has(node) ? node : 'off';
 }
 
+// decisionRuntime family stage resolver (V-03): resolves
+// `decisionRuntime.<key>.stage` for one pinned family flag ('vm',
+// 'supervisor', 'scheduler', 'contract', 'adapters', 'context',
+// 'completion', 'quality', 'promotion', 'resourcePolicy',
+// 'diagnostics'). Same semantics as resolveConfigStage: absent config,
+// absent family, non-string key, or malformed stage all resolve 'off'
+// — a bad config can never promote a decisionRuntime slice.
+export function resolveDecisionRuntimeStage(config = null, key = 'vm') {
+  if (typeof key !== 'string' || key.trim() === '') return 'off';
+  return resolveConfigStage(config, `decisionRuntime.${key}.stage`);
+}
+
 // Pushes a stage-enum error when `node.stage` is present but not reserved.
 // Absent stage is valid (absence = 'off'); a non-object node is reported by
 // the caller's own "must be an object" check.
@@ -287,11 +300,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     },
     // M01.1 stage keys (docs/pstack/MIGRATION_ROLLBACK named-keys table). Every stage
     // key treats absence as "off"; stages promote off -> shadow -> canary -> default.
+    // 3.3.0 zero-config: every routing stage ships 'default'. escalation at
+    // 'default' enforces verification evidence at Stop for high-risk routes —
+    // self-healing (run the verification), never a hard deadlock.
     routing: {
-      routeSchema: { stage: 'off' },
-      rigor: { stage: 'off' },
-      fastPath: { stage: 'off' },
-      escalation: { stage: 'off' },
+      routeSchema: { stage: 'default' },
+      rigor: { stage: 'default' },
+      fastPath: { stage: 'default' },
+      escalation: { stage: 'default' },
     },
     // C52 M07: `unic-decision` is the owner's local non-LLM Lava/JEV model in
     // UNIC Provider. Its OpenAI-compatible API is transport only, not proof of
@@ -401,13 +417,12 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       promotion: { episodeToRuleRequiresApproval: true },
       recall: { maxRecords: 8 },
       // M06 rollout flags (SPEC §5 FR-001): per-plane stage on the shared
-      // off→shadow→canary→default ladder. eligibility/writer/index ship
-      // 'default' (the w1-2 path is the shipped behavior); decision ships
-      // 'off' — plumbing only, no consumer yet. killSwitch is absolute.
+      // off→shadow→canary→default ladder. 3.3.0 zero-config: every plane
+      // ships 'default'. killSwitch is absolute.
       eligibility: { stage: 'default' },
       writer: { stage: 'default' },
       index: { stage: 'default' },
-      decision: { stage: 'off' },
+      decision: { stage: 'default' },
       canaryProjects: [],
       killSwitch: false,
     },
@@ -426,26 +441,29 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       maxRetries: 1,
       confidenceThreshold: 50,
     },
-    // Phase-4 learning loop (SPEC §8a). Advisory only — applyMode 'manual'
-    // means suggestions are computed + persisted, never auto-applied.
+    // Phase-4 learning loop (SPEC §8a). 3.3.0 zero-config: applyMode 'auto'
+    // lets the self-improve cycle apply clamped one-step tuning through the
+    // .ukit/storage/learning/tuned.json overlay (src/learning/tunedOverlay.js);
+    // 'manual' = suggestions only, 'off' = nothing computed.
     learning: {
       feedback: { enabled: true, maxEvents: 200 },
       proposals: { minCount: 3, minSessions: 2 },
       episodes: { autoWrite: true },
-      tuning: { enabled: true, applyMode: 'manual' },
+      tuning: { enabled: true, applyMode: 'auto' },
+      // 3.3.0: automatic collect → learn → apply pass (src/learning/selfImprove.js).
+      selfImprove: { enabled: true },
       // 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: 'shadow', minOccurrences: 3 },
-      overlays: { stage: 'off' },
+      // only after minOccurrences + cross-session evidence (status
+      // 'proposed'; rule promotion still needs approval). overlays: only
+      // approved + enabled overlays apply; base-version mismatch → conflict.
+      candidates: { stage: 'default', minOccurrences: 3 },
+      overlays: { stage: 'default' },
     },
-    // C52 M04.1 compact resumable state (SPEC §5 FR-012–FR-015). Stage 'off'
-    // → no resumable-run records written or consumed; resume falls back to
-    // the existing reinject path.
+    // C52 M04.1 compact resumable state (SPEC §5 FR-012–FR-015): a bounded
+    // resumable-run record per route so a compacted session resumes mid-task.
     continuity: {
-      resumableRun: { stage: 'off' },
+      resumableRun: { stage: 'default' },
     },
     // C63 DR-02 + C64 DR-03/04 + C66 DR-06 + C67 DR-07/08 + C69 DR-10
     // decision-first-runtime (SPEC §2 G1-FR07, §2 G2-FR07/08, §2 G4-FR07,
@@ -459,29 +477,35 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     // gates the G6 caller-wait promotion profile and
     // `decisionRuntime.resourcePolicy` gates the G6 pressure/coalescing
     // policy; `decisionRuntime.diagnostics` gates the G7 explainable-trace /
-    // replay / support-record readers. Absence or malformed stage resolves
-    // 'off' → zero files under .ukit/storage/agent-runtime/, zero behavior
-    // change.
+    // replay / support-record readers. 3.3.0 zero-config: every family ships
+    // 'shadow' — evidence is recorded while the deterministic owners stay
+    // authoritative; promotion.js promotes a family only once its frozen
+    // PROMOTION_CRITERIA hold on sampled runs. diagnostics ships 'default'
+    // (sanitized support records, explicit CLI act).
     decisionRuntime: {
-      contract: { stage: 'off' },
-      supervisor: { stage: 'off' },
-      scheduler: { stage: 'off' },
-      vm: { stage: 'off' },
-      adapters: { stage: 'off' },
-      context: { stage: 'off' },
-      completion: { stage: 'off' },
-      quality: { stage: 'off' },
-      promotion: { stage: 'off' },
-      resourcePolicy: { stage: 'off' },
-      diagnostics: { stage: 'off' },
+      contract: { stage: 'shadow' },
+      supervisor: { stage: 'shadow' },
+      scheduler: { stage: 'shadow' },
+      vm: { stage: 'shadow' },
+      adapters: { stage: 'shadow' },
+      context: { stage: 'shadow' },
+      completion: { stage: 'shadow' },
+      quality: { stage: 'shadow' },
+      promotion: { stage: 'shadow' },
+      resourcePolicy: { stage: 'shadow' },
+      diagnostics: { stage: 'default' },
     },
 
-    // C52 M06 experiments (SPEC §5 FR-021–FR-023). Disabled by default —
-    // zero calls and zero prompt content when off; no auto-promotion.
+    // C52 M06 experiments (SPEC §5 FR-021–FR-023). 3.3.0 zero-config: enabled;
+    // each experiment still runs only where a caller invokes it and never
+    // auto-promotes its own result.
     experiments: {
-      deliberation: { enabled: false },
-      dynamicWorkflow: { enabled: false, maxAttemptsPerFailure: 2, noProgressCap: 3 },
+      deliberation: { enabled: true },
+      dynamicWorkflow: { enabled: true, maxAttemptsPerFailure: 2, noProgressCap: 3 },
     },
+    // Flight recorder (docs/OBSERVABILITY.md): 'default' activates recorder,
+    // analytics, support projection and evaluation. 'off' is the kill switch.
+    observability: { stage: 'default' },
     safePatch: {
       enabled: true,
       strictSharedRisk: true,
@@ -1079,12 +1103,19 @@ export function validateRuntimeConfig(config) {
           errors.push('learning.tuning must be an object.');
         } else {
           pushBooleanError(errors, learning.tuning.enabled, 'learning.tuning.enabled');
-          const VALID_APPLY_MODES = new Set(['manual', 'off']);
+          const VALID_APPLY_MODES = new Set(['auto', 'manual', 'off']);
           if (!VALID_APPLY_MODES.has(learning.tuning.applyMode)) {
             errors.push(`learning.tuning.applyMode must be one of: ${[...VALID_APPLY_MODES].join(', ')}.`);
           }
         }
       }
+      if (learning.selfImprove !== undefined) {
+        if (!isPlainObject(learning.selfImprove)) {
+          errors.push('learning.selfImprove must be an object.');
+        } else {
+          pushBooleanError(errors, learning.selfImprove.enabled, 'learning.selfImprove.enabled');
+        }
+      }
       // C52 M04.2 stage keys — same optional-present contract as routing.*.
       if (learning.candidates !== undefined) {
         if (!isPlainObject(learning.candidates)) {
@@ -1179,7 +1210,7 @@ export async function inspectRuntimeConfig(projectRoot, { homeDir } = {}) {
 
   const user = await readUserConfig(homeDir);
   const userLayer = user.parseError ? null : stripProjectManagedKeys(user.rawConfig);
-  const mergedRaw = mergeObjects(userLayer ?? {}, rawConfig ?? {});
+  const mergedRaw = await mergeTunedOverlay(projectRoot, mergeObjects(userLayer ?? {}, rawConfig ?? {}));
 
   const config = normalizeLegacyOpencodeEntries(buildDefaultRuntimeConfig(mergedRaw));
   const validation = validateRuntimeConfig(config);