@ngockhoale/ukit 3.4.46 → 3.4.48

package/CHANGELOG.md

@@ -2,13 +2,21 @@
 
 All notable changes to UKit are documented here.
 
-## Unreleased
+## 3.4.48 - 2026-10-19
+
+**Completion evidence closure and reproducible multi-host installation.**
+- Recognize standalone `git diff --check` as native Git verification rather than a dry-run mutation. Failed/masked mutations, piped verification, foreign-task evidence and release remote/tag divergence still block.
+- Preserve task ownership through host-consumed coordination notices and continuations; bound Stop diagnostics without accepting incomplete work. Explicit no-publication lists and quoted/report-only references do not authorize a release.
+- Integrate verified OMP child-session/model-ownership safeguards, delegation runtime, installer defaults migration, runtime package dependencies and reproducible scaffolds.
+- Verified locally on macOS/Node 22. Claude/Codex/OMP asset installation is covered; OMP Full Playbook live correctness and trusted worker/dispatch attribution remain UNVERIFIED. No paid OMP smoke or cross-platform live PASS is claimed.
 
-**`/ukit:ci-check`: manual-only cross-platform CI (not yet released; no version bump).**
-- `cross-platform-ci.yml` is now `workflow_dispatch` only (push trigger removed). No push/pull_request/schedule/workflow_run path can start CI.
-- New `/ukit:ci-check` command + `ci-check.mjs` helper (core pack): prechecks, fail-closed budget guard, local preflight, at most one dispatch per invocation, write-ahead run-id state, `status` (never dispatches), `--ref`, `--dry-run`, per-OS report. Never pushes, merges or publishes.
-- Default-branch bootstrap stub documented in `docs/design/CI-CROSS-PLATFORM-MATRIX.md` (requires separate approval).
+## 3.4.47 - 2026-10-18
 
+**Supervisor subagent usage attribution and rendered-instruction parity checks.**
+- Record subagent usage at the supervisor's terminal completion/cancellation boundary, using typed operation metadata and existing exactly-once guards. Provider-authenticated usage remains blocked; host transcript values are not relabeled as provider data.
+- Add read-only `render-instructions.mjs --parity` to byte-compare rendered root instructions with existing root files, including fixture-target support and drift diagnostics.
+- Add manual-only `/ukit:ci-check` cross-platform CI tooling; it remains opt-in and never pushes, merges, or publishes.
+- Locally verified on macOS/Node 22. Q-C98-1 and Q-C98-3 remain blocked on provider-authenticated data/privacy approval; no provider identity/pricing/cache model is claimed.
 ## 3.4.46 - 2026-10-18
 
 **Completion contract P0: forensic intent, attributable release evidence and conditional NO-GO.**

package/manifests/documentation.yaml

@@ -517,6 +517,28 @@ entries:
     validation: [none]
     archive_policy: immutable
     notes: 2026-10-10 orchestration regression test inventory
+  - id: docs-analysis-completion-task-ownership
+    path: docs/analysis/COMPLETION-TASK-OWNERSHIP.md
+    class: archive
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/COMPLETION-TASK-OWNERSHIP.md
+    merge_strategy: none
+    load_policy: never
+    validation: [none]
+    archive_policy: immutable
+    notes: 2026-10-19 task boundary reproduction and bounded Stop verification
+  - id: docs-analysis-omp-runtime-closure
+    path: docs/analysis/OMP-RUNTIME-CLOSURE.md
+    class: archive
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/OMP-RUNTIME-CLOSURE.md
+    merge_strategy: none
+    load_policy: never
+    validation: [none]
+    archive_policy: immutable
+    notes: 2026-10-19 captured OMP lifecycle closure and offline verification boundaries
   - id: docs-analysis-orchestration-final-verification
     path: docs/analysis/ORCHESTRATION-FINAL-VERIFICATION.md
     class: archive

package/manifests/platform.full.yaml

@@ -1222,6 +1222,7 @@ items:
       - hook-auto-allow-bash
       - hook-block-dangerous
       - hook-handoff-model-guard
+      - hook-delegation-gate-module
       - hook-auto-prune-bash
       - hook-project-important
     # Env block is post-merged by applyGatewayResilienceEnv (TASK-011) to add managed
@@ -1422,6 +1423,20 @@ items:
     packs:
       - core
 
+  # P0 delegation enforcement: in-proc PreToolUse chain step (Edit|Write, MultiEdit, Bash). Claude Code
+  # only (agent_id main/worker identity); reads route state + ledger from ukit-runtime-scripts.
+  - id: hook-delegation-gate-module
+    type: hook
+    sourceTemplate: .claude/hooks/delegation-gate.mjs
+    targetPath: .claude/hooks/delegation-gate.mjs
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-handoff-model-guard
     type: hook
     sourceTemplate: .claude/hooks/handoff-model-guard.sh
@@ -1442,6 +1457,7 @@ items:
       - ukit-runtime-scripts
       - ukit-index-route-resolver-script
       - ukit-index-tier-selection-script
+      - ukit-index-tier-lane-script
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1865,6 +1881,16 @@ items:
     packs:
       - core
 
+  - id: ukit-index-tier-lane-script
+    type: config
+    sourceTemplate: .claude/ukit/index/tier-lane.mjs
+    targetPath: .claude/ukit/index/tier-lane.mjs
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-session-history-extractor-script
     type: config
     sourceTemplate: .claude/ukit/index/session-history-extractor.mjs
@@ -2012,6 +2038,7 @@ items:
       - ukit-index-session-history-extractor-script
       - ukit-index-fix-loop-escalation-script
       - ukit-index-tier-selection-script
+      - ukit-index-tier-lane-script
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.46",
+  "version": "3.4.48",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -36,6 +36,9 @@
     "!scripts/audit/c100/usage-provenance.mjs",
     "!scripts/audit/decision-coverage.mjs",
     "!scripts/audit/subagent-cost/**",
+    "!scripts/bench/**",
+    "scripts/bench/decision-runtime-metrics.mjs",
+    "!scripts/perf/**",
     "template_project/",
     "template_user/",
     "!template_project/**/.smbdelete*",

package/scripts/dev/capture-omp-stall.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+// One-shot development capture. Every subprocess is bounded; OMP is never signalled or modified.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readBoundedTail, summarizeSessionTail, buildStallSnapshot, associateSessionEvidence, classifySessionActivity, parseProcessInventory, processInventoryCommand, parseOwnerPids, runBoundedProcess } from '../../src/diagnostics/ompStallSnapshot.js';
+const ownPath = fileURLToPath(import.meta.url);
+const args = process.argv.slice(2);
+const option = (key) => { const at = args.indexOf(key); return at < 0 ? null : args[at + 1]; };
+const worker = process.env.UKIT_STALL_CAPTURE_WORKER === '1';
+
+if (!worker) {
+  const child = spawn(process.execPath, [ownPath, '--worker', ...args], { stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, UKIT_STALL_CAPTURE_WORKER: '1' } });
+  let output = '';
+  let failed = false;
+  const timer = setTimeout(() => { failed = true; child.kill('SIGKILL'); }, 5000);
+  child.stdout.on('data', (chunk) => {
+    output += chunk;
+    if (Buffer.byteLength(output) > 131072) { failed = true; child.kill('SIGKILL'); }
+  });
+  child.on('error', () => { clearTimeout(timer); console.error('Capture unavailable'); process.exitCode = 1; });
+  child.on('close', async (code) => {
+    clearTimeout(timer);
+    if (code !== 0 || failed) { console.error('Capture incomplete: collector deadline or bounded I/O failure; OMP untouched.'); process.exitCode = 1; return; }
+    try {
+      const report = JSON.parse(output);
+      const dir = path.resolve(option('--output-dir') || path.join(os.tmpdir(), 'ukit-stall-captures'));
+      await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+      const dirStat = await fs.lstat(dir);
+      if (!dirStat.isDirectory() || dirStat.isSymbolicLink()) throw new Error('unsafe output directory');
+      await fs.chmod(dir, 0o700);
+      let file = null;
+      let handle = null;
+      const startSlot = Date.now() % 8;
+      for (let attempt = 0; attempt < 8 && !file; attempt += 1) {
+        const slot = (startSlot + attempt) % 8;
+        const candidate = path.join(dir, `snapshot-${slot}.json`);
+        try {
+          const existing = await fs.lstat(candidate);
+          if (!existing.isFile() || existing.isSymbolicLink()) continue;
+          await fs.unlink(candidate);
+        } catch (error) { if (error.code !== 'ENOENT') throw error; }
+        file = candidate;
+        const temporary = path.join(dir, `snapshot-${slot}-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`);
+        try {
+          handle = await fs.open(temporary, 'wx', 0o600);
+          await handle.chmod(0o600);
+          await handle.writeFile(`${JSON.stringify(report, null, 2)}\n`);
+          await handle.close();
+          handle = null;
+          await fs.rename(temporary, file);
+        } catch (error) {
+          if (handle) await handle.close();
+          await fs.unlink(temporary).catch(() => {});
+          file = null;
+          if (attempt === 7) throw error;
+        }
+      }
+      if (!file) throw new Error('no safe snapshot slot available');
+      console.log(`${report.captureStatus} — snapshot saved: ${file}`);
+    } catch {
+      console.error('Capture incomplete: private snapshot could not be saved; OMP untouched.');
+      process.exitCode = 1;
+    }
+  });
+} else {
+  const maxSessions = 32;
+  const maxLogs = 8;
+  const home = option('--omp-home') || path.join(os.homedir(), '.omp');
+  const sessionsRoot = option('--sessions-root') || path.join(home, 'agent', 'sessions');
+  const ownersRoot = option('--owners-root') || path.join(home, 'run', 'session-owners');
+  const logsRoot = option('--logs-root') || path.join(home, 'logs');
+  const explicitSession = option('--session');
+  const packageInfo = JSON.parse(await fs.readFile(new URL('../../package.json', import.meta.url), 'utf8'));
+
+  async function discoverTranscripts(root) {
+    const candidates = [];
+    let truncated = false;
+    try {
+      const rootDir = await fs.opendir(root);
+      let visited = 0;
+      for await (const entry of rootDir) {
+        if (++visited > 128) { truncated = true; break; }
+        if (entry.isFile() && entry.name.endsWith('.jsonl')) candidates.push(path.join(root, entry.name));
+        if (!entry.isDirectory()) continue;
+        let childCount = 0;
+        try {
+          const childDir = await fs.opendir(path.join(root, entry.name));
+          for await (const child of childDir) {
+            if (++childCount > 128 || candidates.length >= maxSessions) { truncated = true; break; }
+            if (child.isFile() && child.name.endsWith('.jsonl')) candidates.push(path.join(root, entry.name, child.name));
+          }
+        } catch { truncated = true; }
+        if (candidates.length >= maxSessions) { truncated = true; break; }
+      }
+      return { state: 'OBSERVED', paths: candidates.slice(0, maxSessions), truncated };
+    } catch { return { state: 'NOT_OBSERVABLE', paths: [], truncated: true }; }
+  }
+
+  async function discoverOwnerIds(root) {
+    try {
+      const dir = await fs.opendir(root);
+      const ids = [];
+      let visited = 0;
+      let truncated = false;
+      for await (const entry of dir) {
+        if (++visited > 128) { truncated = true; break; }
+        if (!entry.isFile() || !entry.name.endsWith('.lock')) continue;
+        const sessionId = entry.name.slice(0, -5);
+        if (/^[\w.-]{1,120}$/.test(sessionId)) ids.push(sessionId);
+        if (ids.length >= maxSessions) { truncated = true; break; }
+      }
+      return { state: 'OBSERVED', ids, truncated };
+    } catch { return { state: 'NOT_OBSERVABLE', ids: [], truncated: true }; }
+  }
+
+  async function runBounded(command, commandArgs, timeout = 650) {
+    return runBoundedProcess(command, commandArgs, { timeoutMs: timeout, maxBuffer: 65536 });
+  }
+
+
+  async function probeOwnerLock(sessionId, rootExists) {
+    if (!rootExists || !/^[\w.-]{1,120}$/.test(sessionId)) return { state: 'NOT_OBSERVABLE', pids: [] };
+    const file = path.join(ownersRoot, `${sessionId}.lock`);
+    try {
+      const stat = await fs.lstat(file);
+      if (!stat.isFile()) return { state: 'NOT_OBSERVABLE', pids: [] };
+    } catch (error) {
+      return error.code === 'ENOENT' ? { state: 'UNHELD', pids: [] } : { state: 'NOT_OBSERVABLE', pids: [] };
+    }
+    if (process.platform === 'win32') {
+      const handles = await runBounded('handle.exe', ['-nobanner', file], 400);
+      if (!handles.ok) return { state: 'NOT_OBSERVABLE', pids: [] };
+      const expected = path.resolve(file).replaceAll('/', '\\').toLowerCase();
+      const matches = handles.stdout.split(/\r?\n/).flatMap((line) => {
+        const match = line.match(/\bpid:\s*(\d+)\s+type:\s*File\b.*?:\s*(.+)$/i);
+        if (!match || match[2].trim().replaceAll('/', '\\').toLowerCase() !== expected) return [];
+        return [Number(match[1])];
+      });
+      const pids = [...new Set(matches)];
+      return pids.length === 1 ? { state: 'OBSERVED', pids } : { state: 'NOT_OBSERVABLE', pids: [] };
+    }
+    const lsof = await runBounded('lsof', ['-t', '--', file], 250);
+    if (lsof.ok) return { state: 'OBSERVED', pids: parseOwnerPids('lsof', lsof.stdout) };
+    if (lsof.exitCode === 1) return /permission|denied|error/i.test(lsof.stderr) ? { state: 'NOT_OBSERVABLE', pids: [] } : { state: 'OBSERVED', pids: [] };
+    if (lsof.errorCode !== 'ENOENT') return { state: 'NOT_OBSERVABLE', pids: [] };
+    const fuser = await runBounded('fuser', ['-f', file], 250);
+    if (fuser.ok) return { state: 'OBSERVED', pids: parseOwnerPids('fuser', `${fuser.stdout}\n${fuser.stderr}`) };
+    if (fuser.exitCode === 1) return /permission|denied|error/i.test(fuser.stderr) ? { state: 'NOT_OBSERVABLE', pids: [] } : { state: 'OBSERVED', pids: [] };
+    return { state: 'NOT_OBSERVABLE', pids: [] };
+  }
+
+
+  async function readProcessInventory() {
+    const [command, commandArgs] = processInventoryCommand(process.platform);
+    const result = await runBounded(command, commandArgs);
+    if (!result.ok) return { state: 'NOT_OBSERVABLE', processes: [], ompProcessCount: null };
+    const processes = parseProcessInventory(process.platform, result.stdout);
+    return { state: 'OBSERVED', processes, ompProcessCount: processes.filter((entry) => /^omp(?:\.exe)?$/i.test(entry.name)).length };
+  }
+
+  async function readOmpLog(pid) {
+    try {
+      const names = [];
+      const directory = await fs.opendir(logsRoot);
+      let visited = 0;
+      for await (const entry of directory) {
+        if (++visited > 256) break;
+        if (entry.isFile() && new RegExp(`^omp\\.\\d{4}-\\d{2}-\\d{2}\\.${pid}\\.log$`).test(entry.name)) names.push(entry.name);
+      }
+      names.sort();
+      const name = names.at(-1);
+      if (!name) return null;
+      const tail = await readBoundedTail(path.join(logsRoot, name), { maxBytes: 32768 });
+      const rows = [];
+      for (const line of tail.text.split('\n')) {
+        try {
+          const row = JSON.parse(line);
+          // Never copy message text, URLs, account fields, headers or response bodies.
+          const timestamp = typeof row.timestamp === 'string' && Number.isFinite(Date.parse(row.timestamp)) ? new Date(row.timestamp).toISOString() : null;
+          rows.push({ timestamp,
+            level: ['debug', 'info', 'warn', 'error'].includes(row.level) ? row.level : null,
+            status: Number.isInteger(row.status) ? row.status : null });
+        } catch { /* Partial log row. */ }
+      }
+      return { pid, bytesRead: tail.bytesRead, rows: rows.slice(-16) };
+    } catch { return null; }
+  }
+
+  let discovery;
+  if (explicitSession) discovery = { state: 'OBSERVED', paths: [explicitSession] };
+  else discovery = await discoverTranscripts(sessionsRoot);
+  const transcriptSessions = [];
+  for (const transcriptPath of discovery.paths.slice(0, maxSessions)) {
+    try {
+      const tail = await readBoundedTail(transcriptPath);
+      const summary = summarizeSessionTail(tail.text);
+      const filenameId = path.basename(transcriptPath).replace(/\.jsonl$/i, '');
+      const uuidFromFilename = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(filenameId) ? filenameId : null;
+      const sessionId = summary.sessionId || uuidFromFilename;
+      const summarySessionId = summary.sessionId;
+      summary.sessionId = sessionId;
+      transcriptSessions.push({ sessionId, transcriptPath, summary, sourceCoverage: { sessionTailBytes: tail.bytesRead, truncated: tail.truncated, sessionIdentityObserved: summarySessionId !== null || uuidFromFilename !== null } });
+    } catch { transcriptSessions.push({ sessionId: null, transcriptPath, summary: null, sourceCoverage: { state: 'NOT_OBSERVABLE' } }); }
+  }
+  const ownerDiscovery = await discoverOwnerIds(ownersRoot);
+  const sessions = [...transcriptSessions];
+  for (const sessionId of ownerDiscovery.ids) if (!sessions.some((entry) => entry.sessionId === sessionId)) sessions.push({ sessionId, transcriptPath: null, summary: null, sourceCoverage: { state: 'NOT_OBSERVABLE' } });
+  const boundedSessions = sessions.slice(0, maxSessions);
+  const ownerRootExists = ownerDiscovery.state === 'OBSERVED';
+  const [ownerResults, processInventory] = await Promise.all([
+    Promise.all(boundedSessions.filter((entry) => entry.sessionId).map(async (entry) => [entry.sessionId, await probeOwnerLock(entry.sessionId, ownerRootExists)])),
+    readProcessInventory(),
+  ]);
+  const ownerLocks = Object.fromEntries(ownerResults);
+  const logs = (await Promise.all([...new Set(ownerResults.flatMap(([, lock]) => lock.state === 'OBSERVED' ? lock.pids : []))].slice(0, maxLogs).map(readOmpLog))).filter(Boolean);
+  const associations = associateSessionEvidence({ sessions: boundedSessions, ownerLocks, processInventory, logs });
+  const snapshots = associations.map((association, index) => {
+    const source = boundedSessions[index];
+    const summary = source.summary;
+    const sessionActivity = classifySessionActivity({ association: association.sessionAssociation, summary });
+    return { ...association, sessionActivity, ...(summary || {}), sourceCoverage: source.sourceCoverage };
+  });
+  const activeOwners = snapshots.filter((entry) => entry.sessionAssociation === 'ACTIVE_OWNER');
+  const allLocksUnheld = ownerResults.length === boundedSessions.filter((entry) => entry.sessionId).length
+    && ownerResults.every(([, lock]) => lock.state === 'UNHELD');
+  const coverageComplete = !discovery.truncated && !ownerDiscovery.truncated && sessions.length <= maxSessions;
+  const transcriptsFullyIdentified = transcriptSessions.every((entry) => entry.sessionId !== null);
+  const executionState = activeOwners.length ? 'EXECUTING'
+    : coverageComplete && transcriptsFullyIdentified && ownerDiscovery.state === 'OBSERVED' && processInventory.state === 'OBSERVED'
+      && processInventory.ompProcessCount === 0 && allLocksUnheld ? 'NO_EXECUTION' : 'NOT_OBSERVABLE';
+  const activity = activeOwners.length === 1 ? activeOwners[0].sessionActivity
+    : activeOwners.length > 1 ? 'MULTIPLE_ACTIVE_SESSIONS' : executionState === 'NO_EXECUTION' ? 'NO_EXECUTION' : 'NOT_OBSERVABLE';
+  const captureStatus = activeOwners.length > 0 && activeOwners.every((entry) => entry.sourceCoverage && entry.summary)
+    && discovery.state === 'OBSERVED' && !discovery.truncated && ownerDiscovery.state === 'OBSERVED' && !ownerDiscovery.truncated
+    && processInventory.state === 'OBSERVED' && ownerResults.every(([, lock]) => lock.state === 'OBSERVED' || lock.state === 'UNHELD')
+    && snapshots.every((entry) => entry.sessionId !== null && entry.identityVerified) ? 'CAPTURE_READY' : 'CAPTURE_PARTIAL';
+  const snapshot = buildStallSnapshot({ executionState, activity, captureStatus,
+    sessionDiscovery: discovery.state, ownerLockDiscovery: ownerDiscovery.state,
+    processInventory: { state: processInventory.state, ompProcessCount: processInventory.ompProcessCount },
+    sessions: snapshots, ompVersion: 'NOT_OBSERVABLE', ukitVersion: packageInfo.version,
+    limitations: ['Persisted transcript events do not prove live stream or gateway state.', 'Unobservable ownership and operation states remain NOT_OBSERVABLE.', 'No OMP freeze root cause is inferred.'] });
+  process.stdout.write(JSON.stringify(snapshot) + '\n');
+}

package/scripts/dev/worktree-preflight.mjs

@@ -7,6 +7,8 @@
 //   - already bootstrapped            → no-op
 //   - missing prerequisites           → run `ukit install` once, re-check
 //   - not a linked worktree           → refuse (the primary checkout's .claude/ is the maintainer runtime)
+// Install can also create template-owned scaffolds missing from the checkout (docs/AI_HANDOFF/PLAN.md, SPEC.md);
+// those are not gitignored, so they are reported as `visibleWrites` + a warning, never hidden or deleted.
 // `ukit install` writes the install flavour of root CLAUDE.md/AGENTS.md, but those files are
 // gitignored *render outputs* of template_project/instructions (docs:render). The preflight
 // re-renders them when they drift — never a tracked render target, which is only reported.
@@ -57,6 +59,15 @@ function isTracked(root, rel) {
 
 const RENDER_CLI = 'scripts/docs/render-instructions.mjs';
 
+// Visible (non-ignored) paths in `git status`. `ukit install` creates template-owned scaffolds that
+// are missing from the checkout (docs/AI_HANDOFF/PLAN.md, SPEC.md — mergeStrategy skip, handoff-clear
+// restores them to template, never deletes them). They are not gitignored, so a HEAD that lost them
+// turns the bootstrap into a visible write. Report it truthfully instead of hiding or deleting it.
+function visibleStatus(root) {
+  const res = spawnSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd: root, encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
+  return res.status === 0 ? new Set(res.stdout.split('\n').filter(Boolean)) : null;
+}
+
 // → rel paths whose rendered bytes differ from disk (`DRIFT <target>` lines of --check).
 export function renderDrift(root) {
   const res = spawnSync(process.execPath, [path.join(root, RENDER_CLI), '--check'], { cwd: root, encoding: 'utf8', timeout: RENDER_TIMEOUT_MS });
@@ -71,7 +82,7 @@ export function missingPrerequisites(root) {
 
 export function preflight({ root, check = false } = {}) {
   const projectRoot = fs.realpathSync(root);
-  const result = { root: projectRoot, ok: false, bootstrapped: false, missing: [], rendered: [], warnings: [], home: null, error: null };
+  const result = { root: projectRoot, ok: false, bootstrapped: false, missing: [], rendered: [], visibleWrites: [], warnings: [], home: null, error: null };
 
   if (!fs.existsSync(path.join(projectRoot, 'bin/ukit'))) {
     return { ...result, exitCode: 2, error: `not a UKit checkout (no bin/ukit): ${projectRoot}` };
@@ -91,6 +102,7 @@ export function preflight({ root, check = false } = {}) {
     // worktree's ignored .cache/ so a preflight never mutates the real home or leaks from it.
     result.home = path.join(projectRoot, '.cache/worktree-preflight-home');
     fs.mkdirSync(result.home, { recursive: true });
+    const visibleBefore = visibleStatus(projectRoot);
     const install = spawnSync(process.execPath, [path.join(projectRoot, 'bin/ukit'), 'install'], {
       cwd: projectRoot,
       encoding: 'utf8',
@@ -98,6 +110,13 @@ export function preflight({ root, check = false } = {}) {
       timeout: 120_000,
     });
     result.bootstrapped = true;
+    const visibleAfter = visibleStatus(projectRoot);
+    if (visibleBefore && visibleAfter) {
+      result.visibleWrites = [...visibleAfter].filter((l) => !visibleBefore.has(l)).map((l) => l.slice(3));
+      if (result.visibleWrites.length > 0) {
+        result.warnings.push(`ukit install created non-ignored file(s) missing from this checkout: ${result.visibleWrites.join(', ')} — template-owned scaffolds; restore/commit them (not deleted)`);
+      }
+    }
     result.missing = missingPrerequisites(projectRoot);
     if (install.status !== 0 || result.missing.length > 0) {
       const tail = `${install.stdout || ''}${install.stderr || ''}`.trim().split('\n').slice(-5).join('\n');

package/scripts/docs/render-instructions.mjs

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 // DOC-102 renderer CLI (SPEC §8.2).
 //   node scripts/docs/render-instructions.mjs --write   (default) regenerate all outputs
-//   node scripts/docs/render-instructions.mjs --check   print DRIFT <path> per mismatch, exit 1
+//   node scripts/docs/render-instructions.mjs --parity  check installed root instructions read-only
+// `--parity` takes precedence over `--check`/`--write`; `--parity-root` overrides only the
+// comparison target directory for fixture/testing use, never the source/layout root.
 import path from 'node:path';
+import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 import {
@@ -12,18 +15,39 @@ import {
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 
-const USAGE = 'usage: render-instructions.mjs [--write|--check]';
 
+const USAGE = 'usage: render-instructions.mjs [--write|--check|--parity] [--parity-root <dir>]';
 const args = process.argv.slice(2);
-const unknown = args.filter((a) => a !== '--write' && a !== '--check');
-if (unknown.length > 0) {
-  console.error(`${USAGE}\nunknown flag: ${unknown[0]}`);
+const parityRootArg = args.indexOf('--parity-root');
+const parityRoot = parityRootArg === -1 ? repoRoot : path.resolve(args[parityRootArg + 1] || '');
+const unknown = args.filter((a, i) => a !== '--write' && a !== '--check' && a !== '--parity'
+  && a !== '--parity-root' && !(parityRootArg !== -1 && i === parityRootArg + 1));
+if (unknown.length > 0 || (parityRootArg !== -1 && !args[parityRootArg + 1])) {
+  console.error(`${USAGE}\nunknown flag or missing value: ${unknown[0] || '--parity-root'}`);
+  process.exit(2);
+}
+if (parityRootArg !== -1 && !args.includes('--parity')) {
+  console.error(`${USAGE}\n--parity-root requires --parity`);
   process.exit(2);
 }
 
 const mode = args.includes('--check') ? 'check' : 'write';
+const parity = args.includes('--parity');
 
 try {
+  if (parity) {
+    const rendered = await renderInstructionsFromDisk({ repoRoot, write: false });
+    const targets = [...rendered].filter(([target]) => target === 'CLAUDE.md' || target === 'AGENTS.md');
+    const drift = targets.filter(([target, content]) => {
+      const file = path.join(parityRoot, target);
+      return !fs.existsSync(file) || !fs.readFileSync(file).equals(Buffer.from(content));
+    });
+    for (const [target] of drift) console.log(`DRIFT ${target}`);
+    if (drift.length > 0) process.exit(1);
+    console.log(`PARITY OK ${targets.length} files`);
+    process.exit(0);
+  }
+
   if (mode === 'check') {
     const drift = await checkRenderedInstructions({ repoRoot });
     for (const target of drift) {

package/src/core/agentRuntime/supervisor.js

@@ -47,8 +47,8 @@ import {
   durationMs,
   reasonCodeForFailure,
   projectRootFromRuntimeDir,
+  recordSubagentUsage,
 } from './telemetry.js';
-
 const SUPERVISOR_FLAG = 'decisionRuntime.supervisor.stage';
 // G6 (DR-09): `decisionRuntime.promotion.stage` — absent/malformed → 'off';
 // 'shadow' consults selectWaitPolicy at the caller-wait decision and records a
@@ -396,6 +396,13 @@ export function createSupervisor(opts = {}) {
             errorCode: reasonCodeForFailure({ cancelReason: op.cancelReason ?? 'cancel_requested' }),
             exitCode: op.exitInfo?.code,
           });
+          if (op.spansClosed) {
+            recordSubagentUsage(telemetry, op.telemetryCtx, {
+              components: op.spec?.subagentUsage?.components,
+              parentRunId: op.spec?.parentRunId,
+              usage: op.spec?.subagentUsage?.usage,
+            });
+          }
         });
       }
     }, limits.killGraceMs));
@@ -521,6 +528,13 @@ export function createSupervisor(opts = {}) {
         exitCode: op.exitInfo?.code,
       });
     }
+    if (op.spansClosed) {
+      recordSubagentUsage(telemetry, op.telemetryCtx, {
+        components: op.spec?.subagentUsage?.components,
+        parentRunId: op.spec?.parentRunId,
+        usage: op.spec?.subagentUsage?.usage,
+      });
+    }
   }
 
   function onExit(op, code, signal) {

package/src/core/diffPlan.js

@@ -62,6 +62,15 @@ async function checkLinkStatus(targetPath, linkTarget) {
 //   Template-filled:                    keys the user does not have take the template value.
 // Gateway-resilience env keys are post-apply managed (applyGatewayResilienceEnv) and are
 // ignored by the drift comparison.
+//
+// One-time defaults migration (orchestrator tier + effort): UKit used to ship `model: "sonnet"`
+// and `effortLevel: "high"`; it now ships `opus` / `medium` (main orchestrator = Tier 3, effort
+// Medium unless the task is high-risk). A key is migrated ONLY when the file is UKit-tracked, the
+// user's value still equals the old shipped default, and the migration has not run before
+// (install.json `settingsDefaultsMigration`) — so a later deliberate choice is never touched
+// again, and settings.local.json / user settings (never edited by UKit) always win at runtime.
+export const SETTINGS_DEFAULTS_MIGRATION_ID = 'orchestrator-opus-medium-v1';
+const LEGACY_SHIPPED_SETTINGS = { model: 'sonnet', effortLevel: 'high' };
 const UKIT_OWNED_TOP_LEVEL_KEYS = new Set(['hooks']);
 const PERMISSION_LIST_KEYS = new Set(['allow', 'deny', 'ask', 'additionalDirectories']);
 const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
@@ -94,7 +103,22 @@ function unionList(templateList, userList) {
   return out;
 }
 
-function mergeSettingsObjects(existing, rendered) {
+// Keys whose old shipped default is still in place and should take the new template value.
+function legacyDefaultKeys(existing, rendered, migrate) {
+  if (!migrate) return [];
+  return Object.keys(LEGACY_SHIPPED_SETTINGS).filter((key) => (
+    existing[key] === LEGACY_SHIPPED_SETTINGS[key] && key in rendered && rendered[key] !== existing[key]
+  ));
+}
+
+export function settingsDefaultsMigrationKeys(existingContent, renderedContent) {
+  const existing = parseSettingsJson(existingContent);
+  const rendered = parseSettingsJson(renderedContent);
+  return existing && rendered ? legacyDefaultKeys(existing, rendered, true) : [];
+}
+
+function mergeSettingsObjects(existing, rendered, { migrateDefaults = false } = {}) {
+  const migrated = new Set(legacyDefaultKeys(existing, rendered, migrateDefaults));
   const merged = {};
   for (const key of Object.keys(rendered)) {
     if (BLOCKED_KEYS.has(key)) continue;
@@ -124,7 +148,7 @@ function mergeSettingsObjects(existing, rendered) {
       // user value has the wrong shape (e.g. permissions: "x") — template shape wins
       merged[key] = templateValue;
     } else {
-      merged[key] = userValue; // user-owned scalar/section (model, effortLevel, …)
+      merged[key] = migrated.has(key) ? templateValue : userValue; // user-owned scalar/section (model, effortLevel, …)
     }
   }
   return merged;
@@ -133,11 +157,11 @@ function mergeSettingsObjects(existing, rendered) {
 // Merge rendered settings.json with the user's existing file per the ownership model above.
 // Returns the merged JSON as a string, or the rendered content unchanged when either side is
 // unparseable (the caller still takes a timestamped backup before writing).
-export function mergeSettingsJson(existingContent, renderedContent) {
+export function mergeSettingsJson(existingContent, renderedContent, options = {}) {
   const existing = parseSettingsJson(existingContent);
   const rendered = parseSettingsJson(renderedContent);
   if (!existing || !rendered) return renderedContent;
-  return `${JSON.stringify(mergeSettingsObjects(existing, rendered), null, 2)}\n`;
+  return `${JSON.stringify(mergeSettingsObjects(existing, rendered, options), null, 2)}\n`;
 }
 
 function withoutGatewayEnv(settings) {
@@ -147,11 +171,11 @@ function withoutGatewayEnv(settings) {
   return { ...settings, env };
 }
 
-function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent) {
+function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent, options = {}) {
   const existing = parseSettingsJson(existingContent);
   const rendered = parseSettingsJson(renderedContent);
   if (!existing || !rendered) return false;
-  const merged = mergeSettingsObjects(existing, rendered);
+  const merged = mergeSettingsObjects(existing, rendered, options);
   return JSON.stringify(canonicalize(withoutGatewayEnv(merged)))
     === JSON.stringify(canonicalize(withoutGatewayEnv(existing)));
 }
@@ -208,7 +232,7 @@ function ukitInstalledText(mergedText, renderedText) {
   }
 }
 
-function resolveFileAction(entry, existingContent, ompOwnership = null) {
+function resolveFileAction(entry, existingContent, ompOwnership = null, settingsMigration = null) {
   const exists = existingContent !== null;
   const binaryEntry = Buffer.isBuffer(entry.renderedContent);
 
@@ -273,9 +297,11 @@ function resolveFileAction(entry, existingContent, ompOwnership = null) {
     // User-owned permission keys (permissions.defaultMode) are excluded from the drift
     // check AND merged back into the content that gets written, so install/update can
     // never flip the user's chosen permission mode.
-    const merged = mergeSettingsJson(existingContent, entry.renderedContent);
-    action = settingsJsonIgnoresGatewayEnvDiff(existingContent, entry.renderedContent) ? 'unchanged' : 'update';
-    return { ...entry, renderedContent: merged, exists, action, existingContent };
+    const mergeOptions = { migrateDefaults: settingsMigration?.pending === true };
+    const merged = mergeSettingsJson(existingContent, entry.renderedContent, mergeOptions);
+    action = settingsJsonIgnoresGatewayEnvDiff(existingContent, entry.renderedContent, mergeOptions) ? 'unchanged' : 'update';
+    const migratedKeys = mergeOptions.migrateDefaults ? settingsDefaultsMigrationKeys(existingContent, entry.renderedContent) : [];
+    return { ...entry, renderedContent: merged, exists, action, existingContent, ...(migratedKeys.length ? { settingsDefaultsMigrated: migratedKeys } : {}) };
   } else if (entry.id === 'runtime-config' && typeof existingContent === 'string' && typeof entry.renderedContent === 'string') {
     // U2: .ukit/storage/config.json is user-owned state seeded from the template — merge
     // by ownership instead of overwriting (see runtimeConfigMerge.js).
@@ -332,7 +358,7 @@ async function resolveSkipEntryAction(entry, ompOwnership = null) {
   return resolveFileAction(entry, read.content, ompOwnership);
 }
 
-export async function diffInstallPlan(plan, { ompOwnership = null } = {}) {
+export async function diffInstallPlan(plan, { ompOwnership = null, settingsMigration = null } = {}) {
   // Check all entries in parallel
   const results = await Promise.all(
     plan.entries.map(async (entry) => {
@@ -352,7 +378,7 @@ export async function diffInstallPlan(plan, { ompOwnership = null } = {}) {
       if (read.status === 'unreadable') {
         return conflictResult(entry, read.error);
       }
-      return resolveFileAction(entry, read.status === 'ok' ? read.content : null, ompOwnership);
+      return resolveFileAction(entry, read.status === 'ok' ? read.content : null, ompOwnership, settingsMigration);
     }),
   );