@ngockhoale/ukit 3.4.1 → 3.4.3

package/src/core/observability/emit/recorder.js

@@ -53,7 +53,13 @@ import { sanitizeObserved } from '../privacy/sanitizeObserved.js';
 import { SEMANTIC_REGISTRY } from '../schema/registry.js';
 import { SCHEMA_VERSION } from '../schema/constants.js';
 import { appendRecord } from '../segments/retention.js';
-import { resolveStage, resolveSampling, samplingConfigInvalid } from './config.js';
+import {
+  resolveStage,
+  resolveSampling,
+  samplingConfigInvalid,
+  samplingConfigInvalidReported,
+  markSamplingConfigInvalidReported,
+} from './config.js';
 
 const DEFAULT_QUEUE_SIZE = 1024;
 const SAMPLING_BUCKETS = 10000;
@@ -138,7 +144,6 @@ export function createRecorder({ root, config, queueSize, writer, clock, samplin
     invalid_spans: 0,
     dropped_sampled: 0,
     pending_sampled: 0,
-    config_invalid_reported: false,
     flushes: 0,
     last_flush: null,
     last_error: null,
@@ -376,13 +381,16 @@ export function createRecorder({ root, config, queueSize, writer, clock, samplin
         state.pending_sampled = 0;
       }
     }
-    if (samplingConfigInvalid() && !state.config_invalid_reported) {
-      if (queueSelfRecord({
+    // TASK-C91-015 (W3-OB2): the report latch lives in config.js at process
+    // scope — sessionBoot.js creates one recorder per emit, so a per-recorder
+    // flag re-reported CONFIG_INVALID on every emit. Mirror parity: claim
+    // before queueing (the mirror sets its flag before the bounded write).
+    if (samplingConfigInvalid() && !samplingConfigInvalidReported()) {
+      markSamplingConfigInvalidReported();
+      queueSelfRecord({
         semantic_name: 'telemetry.dropped',
         payload: { reason_code: 'CONFIG_INVALID', dropped_count: 1 },
-      }, policyAtFlush)) {
-        state.config_invalid_reported = true;
-      }
+      }, policyAtFlush);
     }
     const run = pump(deadlineMs);
     state.pumping = run;

package/src/core/observability/privacy/sanitizeObserved.js

@@ -67,7 +67,9 @@ function sanitizeValue(value, ctx, depth) {
     let kept = 0;
     for (const [k, v] of Object.entries(value)) {
       if (kept >= MAX_OBJECT_KEYS) break;
-      if (DENIED_PAYLOAD_FIELDS.has(k)) continue;
+      // TASK-C91-015 (W3-OB1): denylist matching is case-insensitive —
+      // 'Prompt'/'AUTHORIZATION' carry the same data as lowercase keys.
+      if (DENIED_PAYLOAD_FIELDS.has(k.toLowerCase())) continue;
       const key = sanitizeKey(k, ctx);
       if (key === null) continue;
       const sv = sanitizeValue(v, ctx, depth + 1);

package/src/core/observability/segments/internal.js

@@ -182,29 +182,57 @@ const STATE_DEFAULTS = Object.freeze({
   active_since_ms: null,
 });
 
-/** Best-effort state read; corrupt/missing state degrades to defaults. */
+/**
+ * Marks a readState result synthesized from a FAILED read (corrupt file,
+ * transient EACCES/IO_TIMEOUT, non-object payload). Symbols never serialize,
+ * so the marker is in-memory only. Fail-closed gating still reads the flag
+ * via `state.disabled`; writeState refuses to persist marked state — a
+ * transient read error must never be committed as durable `disabled:true`.
+ */
+export const STATE_READ_FAILED = Symbol('ukit.observability.stateReadFailed');
+
+/** Best-effort state read; a missing file is "no state yet", corrupt is closed. */
 export async function readState(root, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
   try {
     const raw = await withTimeout(fs.promises.readFile(path.join(root, STATE_FILE), 'utf8'), timeoutMs);
     const parsed = JSON.parse(raw);
-    return { ...STATE_DEFAULTS, ...(parsed && typeof parsed === 'object' ? parsed : {}) };
-  } catch {
-    return { ...STATE_DEFAULTS };
+    // TASK-C91-015 (W3-OB3): fail closed on unreadable/invalid state — a
+    // torn _state.json that defaults to disabled:false would keep the
+    // total-size gate open through corruption. ENOENT alone is the open
+    // default; anything else (or a non-object payload) is disabled:true
+    // until a clean write re-enables the store. The state is MARKED
+    // (STATE_READ_FAILED) so it is never persisted back — it synthesizes
+    // values, not facts.
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ...STATE_DEFAULTS, disabled: true, [STATE_READ_FAILED]: true };
+    }
+    return { ...STATE_DEFAULTS, ...parsed };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { ...STATE_DEFAULTS };
+    return { ...STATE_DEFAULTS, disabled: true, [STATE_READ_FAILED]: true };
   }
 }
 
 export async function writeState(root, state, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
+  // TASK-C91-015 (W3-OB3): atomic publish — tmp sibling + rename so a
+  // crash mid-write leaves the previous _state.json (or none), never a
+  // torn file that readState must fail closed on. A state synthesized from
+  // a failed read is never published: persisting it would turn a transient
+  // I/O error into permanent disabled:true that never heals.
+  if (state && state[STATE_READ_FAILED]) return false;
+  const statePath = path.join(root, STATE_FILE);
+  const tmpPath = `${statePath}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
   try {
-    await withTimeout(
-      fs.promises.writeFile(path.join(root, STATE_FILE), JSON.stringify(state, null, 2)),
-      timeoutMs,
-    );
+    await withTimeout(fs.promises.writeFile(tmpPath, JSON.stringify(state, null, 2)), timeoutMs);
+    await withTimeout(fs.promises.rename(tmpPath, statePath), timeoutMs);
     return true;
   } catch {
+    try { await fs.promises.unlink(tmpPath); } catch { /* best-effort */ }
     return false;
   }
 }
 
+
 export function sanitizeNameComponent(value) {
   const s = typeof value === 'string' && value.length > 0 ? value : 'unknown';
   return s.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64) || 'unknown';

package/src/core/observability/segments/retention.js

@@ -57,6 +57,7 @@ import {
   nowOf,
   policyOf,
   readState,
+  STATE_READ_FAILED,
   resolveRoot,
   sanitizeNameComponent,
   sha256Buffer,
@@ -477,6 +478,16 @@ export async function enforceRetention(root, policy) {
   }
 
   const disabled = usage > p.maxTotalBytes;
+  if (state[STATE_READ_FAILED]) {
+    // The read failed: `state` is synthesized (fail-closed disabled:true +
+    // zeroed counters), never facts — persisting it would turn a transient
+    // read error into a permanent shutdown and wipe expired_segments. A
+    // real cap breach is enforced independently of the failed read, so a
+    // bare {disabled:true} is still committed; everything else heals on the
+    // next successful read.
+    if (disabled) await writeState(resolved.root, { disabled: true }, timeoutMs);
+    return { ok: true, expired, disabled };
+  }
   state.expired_segments = (state.expired_segments || 0) + expired;
   if (disabled) state.disabled = true;
   await writeState(resolved.root, state, timeoutMs);

package/src/core/observability/support/import.js

@@ -262,9 +262,22 @@ async function readBundleDir(dir) {
     // ignored — a support dir may hold user files; only manifest-listed
     // members are verified below.
     if (!dent.isFile() || !isSafeEntryName(dent.name)) continue;
+    const memberPath = path.join(dir, dent.name);
+    // W2-B4 (TASK-C91-015): stat before read — a bundle member past the
+    // entry cap is rejected on its declared size, not after its bytes are
+    // already in memory.
+    let st;
+    try {
+      st = await fs.promises.stat(memberPath);
+    } catch (err) {
+      return fail(ioReason(err));
+    }
+    if (st.size > IMPORT_LIMITS.MAX_ENTRY_BYTES) {
+      return fail('entry_too_large', { name: dent.name, bytes: st.size });
+    }
     let buf;
     try {
-      buf = await fs.promises.readFile(path.join(dir, dent.name));
+      buf = await fs.promises.readFile(memberPath);
     } catch (err) {
       return fail(ioReason(err));
     }
@@ -342,6 +355,11 @@ export async function validateSupportBundle(input = {}) {
   let provenance;
   let isDir = false;
   if (hasBuffer) {
+    // W2-B4 (TASK-C91-015): stdin/pipe-fed bundles arrive as buffers — cap
+    // them at the same total bound before unzip work begins.
+    if (input.buffer.length > IMPORT_LIMITS.MAX_TOTAL_BYTES) {
+      return fail('bundle_too_large', { bytes: input.buffer.length });
+    }
     const parsed = unzip(input.buffer);
     if (!parsed.ok) return parsed;
     entries = parsed.entries;
@@ -360,12 +378,20 @@ export async function validateSupportBundle(input = {}) {
       if (!read.ok) return read;
       entries = read.entries;
     } else if (st.isFile()) {
+      // W2-B4 (TASK-C91-015): bound the archive read by its declared size —
+      // an over-cap file is rejected on lstat, not after an unbounded read.
+      if (st.size > IMPORT_LIMITS.MAX_TOTAL_BYTES) {
+        return fail('bundle_too_large', { bytes: st.size });
+      }
       let buf;
       try {
         buf = await fs.promises.readFile(input.path);
       } catch (err) {
         return fail(ioReason(err));
       }
+      if (buf.length > IMPORT_LIMITS.MAX_TOTAL_BYTES) {
+        return fail('bundle_too_large', { bytes: buf.length });
+      }
       const parsed = unzip(buf);
       if (!parsed.ok) return parsed;
       entries = parsed.entries;

package/src/core/output/index.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { readJsonIfExists, writeJson, withFileLock, escapeRegExp } from '../fileOps.js';
@@ -268,6 +269,7 @@ function buildRecoveryFileName({
   summary = '',
   profile = 'generic',
   exitCode = null,
+  contentHash = '',
 } = {}) {
   const slug = sanitizeFileComponent(String(command).split(/\s+/).slice(0, 3).join('-'), {
     fallback: sanitizeFileComponent(profile, { fallback: 'output', maxLength: 16 }),
@@ -278,6 +280,9 @@ function buildRecoveryFileName({
     summary: String(summary ?? '').trim(),
     profile: String(profile ?? 'generic').trim(),
     exitCode: Number.isFinite(Number(exitCode)) ? Number(exitCode) : null,
+    // C90-05: bind the name to the bytes it stores — the shipped twin's
+    // fingerprint is the recovery name's only unique component.
+    contentHash: String(contentHash ?? ''),
   }).split(':').at(-1)?.replace(/[^a-z0-9_-]/gi, '-').slice(0, 16) || 'recovery';
   const uniqueSuffix = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
   return `${slug}-${uniqueSuffix}-${fingerprint}.log`;
@@ -451,6 +456,11 @@ async function persistRawOutput(projectRoot, {
     summary,
     profile,
     exitCode,
+    contentHash: crypto.createHash('sha256')
+      .update(String(stdout ?? ''))
+      .update('\0')
+      .update(String(stderr ?? ''))
+      .digest('hex'),
   });
   const absolutePath = path.join(teeCacheDir, fileName);
   const rawOutputText = buildRawOutputText({
@@ -1071,7 +1081,12 @@ export function compressToolOutput({
         maxLines,
         forceFirstCount: Math.min(1 + anchorLines.length, 5),
       }).join('\n').trim();
-      validationMode = 'forced-anchors';
+      // Same contract as compactContextBlock: 'forced-anchors' must mean every
+      // anchor is present — re-validate and report the shortfall instead of
+      // claiming an anchor-complete summary that dropped the tail anchors.
+      validationMode = findMissingAnchors(summary, anchorLines).length === 0
+        ? 'forced-anchors'
+        : 'anchor-shortfall';
     }
   }
 

package/src/core/permissionDoctor.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import { parse } from 'yaml';
-import { pathExists, readJsonIfExists } from './fileOps.js';
+import { pathExists } from './fileOps.js';
 import { VALID_PERMISSION_MODES } from './runtimeConfig.js';
 import {
   compilePermissionPolicy,
@@ -47,15 +47,45 @@ async function readOmpConfig(projectRoot) {
   }
 }
 
+// FR-025 / W2-C3 — corrupt `.ukit/storage/config.json` / `.claude/settings.json`
+// are exactly what doctor exists to diagnose: readJsonIfExists would throw the
+// SyntaxError and kill the run, so both surface reads stay tolerant and the
+// parse error is reported back as a finding instead.
+async function readRuntimeConfigSurface(projectRoot) {
+  const configPath = path.join(projectRoot, '.ukit', 'storage', 'config.json');
+  try {
+    return { exists: true, parsed: JSON.parse(await fs.readFile(configPath, 'utf8')), parseError: null };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, parsed: null, parseError: null };
+    return { exists: true, parsed: null, parseError: error?.message ?? String(error) };
+  }
+}
+
 async function readClaudeSurface(projectRoot) {
   const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
-  const settings = await readJsonIfExists(settingsPath);
-  const permissions = settings?.permissions;
+  let settings = null;
+  let exists = false;
+  let parseError = null;
+  try {
+    settings = JSON.parse(await fs.readFile(settingsPath, 'utf8'));
+    exists = true;
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      exists = true;
+      parseError = error?.message ?? String(error);
+    }
+  }
+  // A corrupt file yields no usable surface — present stays false so the corrupt
+  // file's finding (its own check) is not masked as a phantom "no permissions"
+  // surface or inflated into per-entry deny-loss noise.
+  const permissions = parseError ? null : settings?.permissions;
   if (!permissions || typeof permissions !== 'object') {
-    return { present: false, deny: [], allow: [], ask: [] };
+    return { exists, parseError, present: false, deny: [], allow: [], ask: [] };
   }
   const list = (key) => (Array.isArray(permissions[key]) ? permissions[key].filter((e) => typeof e === 'string') : []);
   return {
+    exists,
+    parseError,
     present: true,
     deny: list('deny'),
     allow: list('allow'),
@@ -80,12 +110,13 @@ async function scanUnresolvedTokens(projectRoot) {
 }
 
 export async function inspectPermissions({ projectRoot, ompPath = 'omp' }) {
-  const runtimeConfig = await readJsonIfExists(
-    path.join(projectRoot, '.ukit', 'storage', 'config.json'),
-  );
+  const runtimeConfigSurface = await readRuntimeConfigSurface(projectRoot);
+  const runtimeConfig = runtimeConfigSurface.parseError ? null : runtimeConfigSurface.parsed;
   const declaredRaw = runtimeConfig?.orchestration?.permissionMode;
   const declared = declaredRaw === undefined ? 'unattended' : declaredRaw;
-  const modeValid = VALID_PERMISSION_MODES.has(declared);
+  // Corrupt config → declared mode is unreadable, not 'unattended (default)':
+  // failing modeValid keeps corruption from masquerading as a healthy default.
+  const modeValid = !runtimeConfigSurface.parseError && VALID_PERMISSION_MODES.has(declared);
   const allowUnsafeEval = runtimeConfig?.orchestration?.allowUnsafeEval === true;
 
   // --- Surface reads ---------------------------------------------------------
@@ -241,6 +272,8 @@ export async function inspectPermissions({ projectRoot, ompPath = 'omp' }) {
   if (evalMismatch) failures.push('unsafe-eval-mismatch');
   if (unresolvedTokens.length > 0) failures.push('unrendered-token');
   if (!modeValid) failures.push('invalid-permission-mode');
+  if (runtimeConfigSurface.parseError) failures.push('corrupt-runtime-config');
+  if (claude.parseError) failures.push('corrupt-claude-settings');
 
   const check = (label, passed, remediationClass, remedy, extra = {}) => ({
     label,
@@ -252,12 +285,29 @@ export async function inspectPermissions({ projectRoot, ompPath = 'omp' }) {
   });
 
   const checks = [
+    check(
+      'runtime config.json parses',
+      !runtimeConfigSurface.parseError,
+      'owner-action',
+      'Fix or remove .ukit/storage/config.json — invalid JSON hides the declared permissionMode.',
+      {
+        detail: runtimeConfigSurface.parseError
+          ? `corrupt: ${runtimeConfigSurface.parseError}`
+          : runtimeConfigSurface.exists
+            ? 'parsed'
+            : 'absent (defaults apply)',
+      },
+    ),
     check(
       'permission mode declared and valid',
       modeValid,
       'owner-action',
       `Set orchestration.permissionMode in .ukit/storage/config.json to one of: ${[...VALID_PERMISSION_MODES].join(', ')}.`,
-      { detail: `declared: ${declared}${declaredRaw === undefined ? ' (default)' : ''} → effective: ${modeValid ? declared : 'unknown'}` },
+      {
+        detail: runtimeConfigSurface.parseError
+          ? 'declared: unreadable (corrupt config.json) → effective: unknown'
+          : `declared: ${declared}${declaredRaw === undefined ? ' (default)' : ''} → effective: ${modeValid ? declared : 'unknown'}`,
+      },
     ),
     check(
       'no prompts reachable under unattended mode',
@@ -315,6 +365,19 @@ export async function inspectPermissions({ projectRoot, ompPath = 'omp' }) {
           : `missing: ${denyMissingAll.join(', ')}`,
       },
     ),
+    check(
+      'claude settings.json parses',
+      !claude.parseError,
+      'owner-action',
+      'Fix or remove .claude/settings.json — invalid JSON hides the claude permission surface.',
+      {
+        detail: claude.parseError
+          ? `corrupt: ${claude.parseError}`
+          : claude.exists
+            ? 'parsed'
+            : 'absent (no claude permission surface)',
+      },
+    ),
     check(
       'eval posture matches allowUnsafeEval',
       !evalMismatch,

package/src/core/repairBrokenHooks.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { writeFileAtomic } from './fileOps.js';
 
 // Claude Code rejects any hook whose stdout carries a `hookSpecificOutput` object
 // without `hookEventName` inside it, and surfaces it as a per-tool-call
@@ -199,8 +200,20 @@ export async function repairBrokenHooks({ projectRoot, homeDir = os.homedir() }
 
     // Keep a restore point before touching a file the user did not ask us to edit.
     await fs.writeFile(backupPathFor(settingsPath), raw, 'utf8');
-    await fs.writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
-
+    // C92-C-05: ~/.claude/settings.json is user-GLOBAL — every Claude Code
+    // session on the machine reads it. A truncate-then-write leaves a torn
+    // (zero-length or partial) file observable to a concurrent session; publish
+    // the repaired settings through the same atomic tmp+rename helper the rest
+    // of the pipeline uses.
+    // Fix round 1: when settings.json is a symlink (dotfiles setups link it
+    // into a repo checkout), writeFileAtomic's rename would REPLACE the link
+    // with a regular file — severing the link and leaving the target's broken
+    // hook unrepaired. Write through to the link target instead.
+    const linkStat = await fs.lstat(settingsPath);
+    const writePath = linkStat.isSymbolicLink()
+      ? await fs.realpath(settingsPath)
+      : settingsPath;
+    await writeFileAtomic(writePath, `${JSON.stringify(settings, null, 2)}\n`);
     files.push(settingsPath);
     removals.push(...found.map((entry) => ({ ...entry, settingsPath })));
   }

package/src/core/reviewPanelAggregate.js

@@ -14,9 +14,11 @@
 //
 // Consensus rules (SPEC §5 FR-008):
 //   changes_requested — ≥1 CRITICAL verdict, ≥1 critical-severity finding,
-//                       or ≥2 CHANGES-REQUESTED verdicts.
-//   approved          — ≥2 APPROVED verdicts and no critical.
-//   approved_minor    — everything else (incl. degenerate/empty panel).
+//                       ≥1 CHANGES-REQUESTED verdict, or zero parseable
+//                       blocks. Fail closed: when in doubt, the more
+//                       conservative verdict wins.
+//   approved          — ≥2 APPROVED verdicts and no critical/change request.
+//   approved_minor    — everything else.
 //
 // High signal: a finding reported by ≥2 panel members, or any critical-severity
 // finding (a lone critical must never be buried below the lead's judgment).
@@ -47,17 +49,31 @@ export function parseVerdictBlock(text) {
     const rest = src.slice(findingsMatch.index + findingsMatch[0].length);
     let severity = null;
     for (const line of rest.split('\n')) {
-      if (/^\S/.test(line)) break; // next top-level field ends FINDINGS
-      const sev = line.match(/^\s{2}(critical|important|minor)\s*:/);
+      if (line.trim() === '') continue;
+      // Non-canonical layouts are tolerated: severity headers may carry any
+      // indentation or capitalization, and inline text after the colon
+      // (e.g. `Critical: auth bypass`) still counts as a finding.
+      const sev = line.match(/^\s*(critical|important|minor)\s*:\s*(.*)$/i);
       if (sev) {
-        severity = sev[1];
+        severity = sev[1].toLowerCase();
+        const inline = sev[2].trim();
+        // Placeholders — `none`, `(none)`, `-`, `(none — reason)` — are not
+        // findings; `critical: (none)` must not fabricate a critical.
+        const lc = inline.toLowerCase();
+        if (inline !== '' && lc !== '-' && lc !== 'none' && !lc.startsWith('(none')) {
+          findings[severity].push(inline);
+        }
         continue;
       }
-      const item = line.match(/^\s{4}-\s+(.+?)\s*$/);
+      const item = line.match(/^\s*[-*]\s+(.+?)\s*$/);
       if (item && severity) {
-        const text2 = item[1];
-        if (text2 !== 'none' && text2 !== '-') findings[severity].push(text2);
+        // Same placeholder set for bullets — `- (none)` under `critical:` must
+        // not fabricate a critical.
+        const text2 = item[1].toLowerCase();
+        if (text2 !== 'none' && text2 !== '-' && !text2.startsWith('(none')) findings[severity].push(item[1]);
+        continue;
       }
+      if (/^\S/.test(line)) break; // next top-level field ends FINDINGS
     }
   }
 
@@ -112,7 +128,7 @@ export function aggregatePanelVerdicts(verdicts) {
     parsed.some((p) => p.verdict === 'CRITICAL') || parsed.some((p) => p.findings.critical.length > 0);
 
   let verdict;
-  if (hasCritical || changeRequests >= 2) verdict = 'changes_requested';
+  if (hasCritical || changeRequests >= 1 || parsed.length === 0) verdict = 'changes_requested';
   else if (approvals >= 2) verdict = 'approved';
   else verdict = 'approved_minor';
 

package/src/core/runInstallPipeline.js

@@ -10,12 +10,12 @@ import { buildInstallPlan } from './buildPlan.js';
 import { diffInstallPlan } from './diffPlan.js';
 import { applyDiffResults, pruneOldBackups } from './applyPlan.js';
 import { summarizeDiff, toDiffRows } from './report.js';
-import { writeInstallMetadata, writeCliLocator } from './metadata.js';
+import { writeInstallMetadata, writeCliLocator, readInstallMetadata } from './metadata.js';
 import { cleanupLegacyPaths, migrateLegacyRuntimeRoot } from './migrateLegacy.js';
 import { ensureGitignore } from './ensureGitignore.js';
 import { repairBrokenHooks } from './repairBrokenHooks.js';
 import { applyGatewayResilienceEnv } from './gatewayResilienceEnv.js';
-import { cleanupEmptyParents, readJsonIfExists, removeFileOrLinkOnly, resolveProjectRelativePath, writeJson } from './fileOps.js';
+import { cleanupEmptyParents, copyFileSafe, removeFileOrLinkOnly, resolveProjectRelativePath, writeJson } from './fileOps.js';
 import { findOpencodeArtifacts, opencodeSteerMessage } from './opencodeSteer.js';
 import { loadRuntimeConfig } from './runtimeConfig.js';
 import { buildUserPaths } from './userPaths.js';
@@ -188,14 +188,16 @@ async function pruneObsoleteManagedPaths({
   projectRoot,
   managedRelativePaths,
   managedLinkRelativePaths = [],
+  backupRoot,
 }) {
+  const prune = { removed: 0, paths: [] };
   if (installMetaData?.tool !== 'ukit') {
-    return 0;
+    return prune;
   }
 
   const previousFiles = Array.isArray(installMetaData?.files) ? installMetaData.files : [];
   if (previousFiles.length === 0) {
-    return 0;
+    return prune;
   }
 
   const activePathSet = new Set(
@@ -210,7 +212,6 @@ async function pruneObsoleteManagedPaths({
   );
   const activeLinkPaths = [...activeLinkPathSet];
 
-  let removedCount = 0;
   for (const entry of previousFiles) {
     const relativePath = normalizeRelativePath(typeof entry === 'string' ? entry : entry?.p);
     if (!relativePath || activePathSet.has(relativePath) || !shouldAutoPruneObsoletePath(relativePath)) {
@@ -225,29 +226,64 @@ async function pruneObsoleteManagedPaths({
       continue;
     }
 
-    const removed = await removeFileOrLinkOnly(absolutePath);
-    if (removed) {
-      removedCount += 1;
-      await cleanupEmptyParents(absolutePath, projectRoot);
+    let stat;
+    try {
+      stat = await fs.lstat(absolutePath);
+    } catch {
+      // Already gone — nothing to prune and nothing to warn about.
       continue;
     }
 
-    // removeFileOrLinkOnly refuses real directories. A path recorded as managed that is
-    // now a real directory means the user replaced it — say so instead of silently
-    // leaving it behind, matching the link-update warning in applyPlan.js.
-    try {
-      const stat = await fs.lstat(absolutePath);
-      if (stat.isDirectory() && !stat.isSymbolicLink()) {
+    if (stat.isDirectory() && !stat.isSymbolicLink()) {
+      // removeFileOrLinkOnly refuses real directories. A path recorded as managed that is
+      // now a real directory means the user replaced it — say so instead of silently
+      // leaving it behind, matching the link-update warning in applyPlan.js.
+      console.warn(
+        `[UKit] Warning: skipping obsolete path ${absolutePath} — exists as a real directory (possible user content). Remove it manually if intended.`,
+      );
+      continue;
+    }
+
+    // C92-C-02: this is the only deletion lane for .claude/skills/** — every
+    // write lane for the same files goes through overwrite_with_backup, so a
+    // prune must produce the same restore point before unlinking. When no
+    // backup can be written (no backupRoot configured, or the copy failed),
+    // refuse the unlink and warn: a stale-but-alive file beats an
+    // unrecoverable deletion. Symlinks carry no content to preserve.
+    if (!stat.isSymbolicLink()) {
+      if (!backupRoot) {
         console.warn(
-          `[UKit] Warning: skipping obsolete path ${absolutePath} — exists as a real directory (possible user content). Remove it manually if intended.`,
+          `[UKit] Warning: skipping obsolete path ${relativePath} — no backup root configured, refusing to delete a managed file without a restore point.`,
         );
+        continue;
       }
-    } catch {
-      // Already gone — nothing to prune and nothing to warn about.
+      try {
+        await copyFileSafe(
+          absolutePath,
+          path.join(backupRoot, `${relativePath}.${Date.now()}.bak`),
+        );
+      } catch (backupError) {
+        console.warn(
+          `[UKit] Warning: skipping obsolete path ${relativePath} — backup failed (${backupError?.message ?? backupError}).`,
+        );
+        continue;
+      }
+    }
+
+    const removed = await removeFileOrLinkOnly(absolutePath);
+    if (removed) {
+      prune.removed += 1;
+      prune.paths.push(relativePath);
+      await cleanupEmptyParents(absolutePath, projectRoot);
+      continue;
     }
+
+    console.warn(
+      `[UKit] Warning: could not prune obsolete path ${absolutePath}. Remove it manually if intended.`,
+    );
   }
 
-  return removedCount;
+  return prune;
 }
 // SPEC FR-004 — user-layer seeding pass. Runs after the project plan/diff (and
 // after the project apply on real installs): seeds ~/.ukit/ from
@@ -333,7 +369,10 @@ export async function runInstallPipeline({
   // cleanupLegacyPaths() is only safe to run on reinstalls: on a fresh install
   // there are no legacy UKit files to migrate, so running it risks deleting user
   // files that happen to share a legacy path name (e.g. .claude/skills/delivery.md).
-  const installMetaData = await readJsonIfExists(pathConfig.installMetaPath);
+  // FR-015 (W2-C2): a corrupt install.json is fatal and typed — treating it as
+  // "not installed" would re-scaffold over a real UKit project and lose the
+  // tracked-file manifest the uninstall path depends on.
+  const installMetaData = await readInstallMetadata(pathConfig.installMetaPath);
   const isReinstall = Boolean(installMetaData?.tool === 'ukit');
 
   // SPEC FR-004/§security — a leftover opencode.json is a user file: detect and
@@ -351,7 +390,10 @@ export async function runInstallPipeline({
 
   const manifest = await loadManifest(pathConfig.manifestPath);
   const stackContext = await detectStack(pathConfig.projectRoot);
-  const projectContext = await detectProjectContext(pathConfig.projectRoot);
+  // C92-C-03/C-04: mint only on a real install (ukit diff runs this pipeline
+  // with dryRun: true) and thread homeDir so sandboxed callers never touch the
+  // caller's real home registry.
+  const projectContext = await detectProjectContext(pathConfig.projectRoot, { homeDir, mint: !dryRun });
   const providerContext = await detectProviders(pathConfig.projectRoot);
   // FR-004 — feeds the omp.evalApproval render variable. Missing/invalid config
   // degrades to defaults (allowUnsafeEval: false) inside loadRuntimeConfig, so
@@ -451,11 +493,16 @@ export async function runInstallPipeline({
       projectRoot: pathConfig.projectRoot,
     });
 
-    await pruneObsoleteManagedPaths({
+    // C92-C-02: the obsolete-path prune is the only deletion lane for
+    // .claude/skills/** — it must carry the same backup discipline as
+    // overwrite_with_backup, and its result is surfaced to the caller so the
+    // install summary reports it instead of silently swallowing unlinks.
+    const pruneResult = await pruneObsoleteManagedPaths({
       installMetaData,
       projectRoot: pathConfig.projectRoot,
       managedRelativePaths,
       managedLinkRelativePaths,
+      backupRoot: pathConfig.backupRoot,
     });
 
     // Adjust summary to reflect entries that were skipped for safety
@@ -503,6 +550,7 @@ export async function runInstallPipeline({
       hookRepair,
       gatewayResilience,
       userLayer,
+      prune: pruneResult,
     };
   }
 
@@ -527,5 +575,6 @@ export async function runInstallPipeline({
     hookRepair: { removals: [], files: [] },
     gatewayResilience: { customGateway: false, reason: 'dry-run' },
     userLayer,
+    prune: { removed: 0, paths: [] },
   };
 }