@ngockhoale/ukit 1.6.4 → 1.6.6

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to UKit are documented here.
 
+## 1.6.6 - 2026-08-03
+
+### Fixed
+
+- **`ensureGitignore`** no longer silently no-ops on a damaged UKit block (missing/duplicate end marker). Marker detection is now a single source of truth (`parseGitignore` + `locateBlock`, exact-line matching, shared with `removeGitignoreBlock`), fixing data loss on substring-collision lines, content between two legitimate blocks, and CRLF round-tripping, while staying idempotent.
+- **Install summary counts** no longer go negative or misattribute a skip. `applyDiffResults` now tracks skips per planned action (`create`/`update`), and `runInstallPipeline` subtracts each skip from its own bucket instead of always assuming `update`.
+- **Runtime config default version** is now read from `package.json` instead of a hardcoded, drifting literal (was stuck at `1.5.2`).
+- **`mergeObjects` (runtime config)** now refuses `__proto__`, `constructor`, and `prototype` keys at every merge depth, closing a prototype-pollution path via a hand-edited `.ukit/storage/config.json`.
+- **`buildInstallPlan`** no longer aborts the entire install when a template is missing for a *non-selected/excluded* item — it skips quietly. A missing template for a *selected* item still fails loudly with a clear error.
+- **`uninstallUkit`** now reports out-of-scope/forged tracked paths on real runs, not only `--dry-run`, while routine link-child paths stay silent.
+
+## 1.6.5 - 2026-08-02
+
+### Added
+
+- **Enforced `unic-vision` image lane.** Images are now mechanically routed to a vision-capable model instead of being guessed at by `unic-code`/`unic-smart`, which cannot read images on the UNIC gateway.
+  - `.claude/ukit/index/extract-image.mjs` — decodes pasted images out of the session transcript to disk (a spawned subagent receives text only and does not inherit image blocks), and writes content-addressed `pending-<sha>.json` markers. Single owner of the sha256; both the marker and the image filename come from the same hash.
+  - `.claude/hooks/vision-router.sh` (`UserPromptSubmit`) — detects all three input forms (pasted, local path, image URL) and arms a marker for each. Fails OPEN: a failure here degrades to no hint and no markers, never a wedged prompt.
+  - `.claude/hooks/vision-gate.sh` (`PreToolUse`, `Edit|Write` only) — hard-blocks the write (exit 2) until an `analyzed-<sha>.json` receipt exists whose self-reported model is vision-capable. A receipt from `unic-code`, `unic-smart`, `sonnet`, or `opus` is treated as ABSENT and still blocks. Fails CLOSED, and gateway detection that is missing or broken DENIES the fallback-model exception rather than granting it. `Read`/`Grep`/`Glob`/`Bash` are never gated — the vision analyst needs them to clear the gate.
+  - `ukit-vision-analyst` agent — pinned to `unic-vision`, the only lane permitted to interpret images. Reports findings only; it has no `Edit`/`Write`.
+  - `.claude/ukit/index/unic-gateway.mjs` — detects a `unicjsc.com` gateway across Claude Code env, Codex config, Kilo config, and `OPENAI_BASE_URL`. Only ever tests for substring presence; never reads credential file contents into output.
+
+### Changed
+
+- `orchestration.escalation` now has real consumers. `route-task.mjs` reads `debugLoopThreshold`, `tierOrder`, and `cap` from config instead of hardcoded literals, and emits `escalatedTier` alongside `modelTier` — one rung up, capped at `smart`. The same literals remain as fallbacks, so projects that never opted in behave identically.
+- `orchestration.modelTiers` documents all four UNIC models. `vision` is a capability lane orthogonal to the lite/code/smart cost tiers, never a fourth tier, and is stripped from any configured `tierOrder`.
+- `handoff-model-guard.sh`: `tierOf()` hardened against vision/unknown model names.
+
 ## 1.6.4 - 2026-07-27
 
 ### Added

package/manifests/platform.full.yaml

@@ -819,6 +819,17 @@ items:
     packs:
       - core
 
+  - id: agent-ukit-vision-analyst
+    type: agent
+    sourceTemplate: .claude/agents/ukit-vision-analyst.md
+    targetPath: .claude/agents/ukit-vision-analyst.md
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: command-handoff-create
     type: command
     sourceTemplate: .claude/commands/ukit/handoff-create.md
@@ -1037,6 +1048,32 @@ items:
     packs:
       - core
 
+  - id: hook-vision-router
+    type: hook
+    sourceTemplate: .claude/hooks/vision-router.sh
+    targetPath: .claude/hooks/vision-router.sh
+    requires:
+      - ukit-index-extract-image-script
+      - ukit-index-unic-gateway-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: hook-vision-gate
+    type: hook
+    sourceTemplate: .claude/hooks/vision-gate.sh
+    targetPath: .claude/hooks/vision-gate.sh
+    requires:
+      - ukit-index-extract-image-script
+      - ukit-index-unic-gateway-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-compress-output
     type: hook
     sourceTemplate: .claude/hooks/compress-output.sh
@@ -1266,6 +1303,26 @@ items:
     packs:
       - core
 
+  - id: ukit-index-unic-gateway-script
+    type: config
+    sourceTemplate: .claude/ukit/index/unic-gateway.mjs
+    targetPath: .claude/ukit/index/unic-gateway.mjs
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-index-extract-image-script
+    type: config
+    sourceTemplate: .claude/ukit/index/extract-image.mjs
+    targetPath: .claude/ukit/index/extract-image.mjs
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-route-task-script
     type: config
     sourceTemplate: .claude/ukit/index/route-task.mjs
@@ -1274,6 +1331,8 @@ items:
       - ukit-index-core-lib
       - ukit-index-cache-utils-script
       - ukit-index-route-catalog-script
+      - ukit-index-unic-gateway-script
+      - ukit-index-extract-image-script
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.6.4",
+  "version": "1.6.6",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/src/core/applyPlan.js

@@ -15,6 +15,7 @@ function isTccProtectedPath(filePath) {
 export async function applyDiffResults(diffResults, { backupRoot, projectRoot } = {}) {
   const writes = [];
   let skippedUpdates = 0;
+  const skippedByAction = { create: 0, update: 0 };
 
   for (const entry of diffResults) {
     if (entry.action !== 'create' && entry.action !== 'update') {
@@ -36,6 +37,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
             `[UKit] Warning: skipping link update for ${entry.targetPath} — exists as a ${existingKind} (possible user content). Remove it manually if intended.`,
           );
           skippedUpdates += 1;
+          skippedByAction[entry.action] += 1;
           continue;
         }
       }
@@ -47,6 +49,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
             `[UKit] Warning: skipping link creation for ${entry.targetPath} — permission denied. Run 'ukit install' from within the target tool to create it.`,
           );
           skippedUpdates += 1;
+          skippedByAction[entry.action] += 1;
           continue;
         }
         throw linkError;
@@ -78,6 +81,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
             `[UKit] Warning: skipping backup for ${entry.targetPath} — permission denied.`,
           );
           skippedUpdates += 1;
+          skippedByAction.update += 1;
           continue;
         }
         throw backupError;
@@ -111,6 +115,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
           `[UKit] Warning: skipping write for ${entry.targetPath} — permission denied (macOS TCC). Run 'ukit install' from within the owning tool to update it.`,
         );
         skippedUpdates += 1;
+        skippedByAction[entry.action] += 1;
         continue;
       }
       throw writeError;
@@ -126,5 +131,5 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
     });
   }
 
-  return { writes, skippedUpdates };
+  return { writes, skippedUpdates, skippedByAction };
 }

package/src/core/buildPlan.js

@@ -101,7 +101,17 @@ export async function buildInstallPlan({
   for (const item of manifest.items) {
     if (!selectedIds.has(item.id) && item.type !== 'link') {
       const sourcePath = safeResolve(templatesRoot, item.sourceTemplate);
-      const stat = await fs.stat(sourcePath);
+      let stat;
+      try {
+        stat = await fs.stat(sourcePath);
+      } catch (error) {
+        if (error?.code === 'ENOENT') {
+          // An excluded item only contributes an auto-discovery filter, so a
+          // missing source for a pack the user does not have is harmless.
+          continue;
+        }
+        throw error;
+      }
       const sourceDir = (stat.isDirectory() ? sourcePath : path.dirname(sourcePath)) + path.sep;
       excludedSourceDirs.push(sourceDir);
     }
@@ -145,7 +155,11 @@ export async function buildInstallPlan({
           });
           continue;
         }
-        throw error;
+        throw new Error(
+          `Cannot install manifest item "${item.id}": missing or unreadable template `
+            + `"${item.sourceTemplate}".`,
+          { cause: error },
+        );
       }
       if (stat.isDirectory()) {
         const nestedFiles = await walkDirectory(sourcePath);

package/src/core/ensureGitignore.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { escapeRegExp, writeFileAtomic } from './fileOps.js';
+import { writeFileAtomic } from './fileOps.js';
 
 const UKIT_ENTRIES = [
   '.cache/',
@@ -20,6 +20,76 @@ const UKIT_ENTRIES = [
 const MARKER_START = '# UKit generated (do not edit)';
 const MARKER_END = '# /UKit';
 
+/*
+ * Single source of truth for "where is the UKit block in this file".
+ *
+ * Both `ensureGitignore` and `removeGitignoreBlock` go through `parseGitignore`
+ * + `locateBlock`. There is deliberately NO regex/substring notion of a marker
+ * anywhere else in this module — historically the fast path used a substring
+ * regex, the repair path used `line === MARKER`, and the entry guard used
+ * `content.includes(...)`; those three disagreed and silently deleted user
+ * lines that merely *contained* marker-like text.
+ *
+ * Documented behaviour:
+ *  - A marker is ONLY a line that, after stripping a trailing `\r`, is exactly
+ *    equal to MARKER_START / MARKER_END. `# UKit generated (do not edit) v2`
+ *    or a marker with a trailing space is ordinary user content, everywhere.
+ *  - Line endings: the file's *dominant* ending wins (CRLF only if CRLF pairs
+ *    outnumber bare LFs; ties go to LF). A file is only ever rewritten when its
+ *    content actually changes, and a rewrite normalises the whole file to that
+ *    dominant ending — so a mixed-ending file converges after one normalising
+ *    write.
+ *  - Only the FIRST block is managed. Any further marker lines are treated as
+ *    user content so a second, legitimate block — and every user line between
+ *    the two — is never touched.
+ */
+
+/**
+ * Detect the dominant line ending and split into `\r`-free lines.
+ * @param {string} content
+ * @returns {{ eol: string, lines: string[] }}
+ */
+function parseGitignore(content) {
+  const crlfCount = (content.match(/\r\n/g) ?? []).length;
+  const lfCount = (content.match(/\n/g) ?? []).length;
+  const bareLfCount = lfCount - crlfCount;
+  const eol = crlfCount > bareLfCount ? '\r\n' : '\n';
+  const lines = content
+    .split('\n')
+    .map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line));
+  return { eol, lines };
+}
+
+/**
+ * Locate the first UKit block at or after `from`, using exact-line equality only.
+ *
+ * The block spans `[startIdx, endIdx]` inclusive. The search for the closing
+ * marker is bounded by the NEXT start marker, so an excision can never run past
+ * a second block. If no end marker exists inside that bound the block is
+ * "unterminated" and ends just before the next start marker (or at EOF).
+ *
+ * @param {string[]} lines `\r`-free lines from {@link parseGitignore}
+ * @param {number} [from]
+ * @returns {{ startIdx: number, endIdx: number, terminated: boolean } | null}
+ */
+function locateBlock(lines, from = 0) {
+  const startIdx = lines.indexOf(MARKER_START, from);
+  if (startIdx === -1) return null;
+
+  const next = lines.indexOf(MARKER_START, startIdx + 1);
+  const bound = next === -1 ? lines.length : next;
+
+  // Last end marker *within the bound* — consumes stray/duplicate end markers
+  // that belong to this damaged block without reaching into the next one.
+  let endIdx = -1;
+  for (let i = startIdx + 1; i < bound; i += 1) {
+    if (lines[i] === MARKER_END) endIdx = i;
+  }
+
+  const terminated = endIdx !== -1;
+  return { startIdx, endIdx: terminated ? endIdx : bound - 1, terminated };
+}
+
 export async function ensureGitignore(projectRoot) {
   const gitignorePath = path.join(projectRoot, '.gitignore');
 
@@ -30,48 +100,60 @@ export async function ensureGitignore(projectRoot) {
     // no .gitignore yet
   }
 
-  const newBlock = [
-    MARKER_START,
-    ...UKIT_ENTRIES,
-    MARKER_END,
-  ].join('\n');
-
-  if (content.includes(MARKER_START)) {
-    // Replace existing UKit block with current entries
-    const blockPattern = new RegExp(
-      `${escapeRegExp(MARKER_START)}[\\s\\S]*?${escapeRegExp(MARKER_END)}`,
-    );
-    const existingBlock = content.match(blockPattern)?.[0];
-    if (existingBlock === newBlock) {
-      return false; // already up to date
+  const { eol, lines } = parseGitignore(content);
+  const blockLines = [MARKER_START, ...UKIT_ENTRIES, MARKER_END];
+  const block = locateBlock(lines);
+
+  let nextLines;
+  if (block) {
+    // Splice the canonical block over the located one, in place. Well-formed,
+    // unterminated and stray-end-marker blocks all take this one path — a
+    // well-formed, current block simply splices to identical content and is
+    // caught by the `next === content` no-op check below, which is what makes
+    // repeated calls converge.
+    nextLines = [
+      ...lines.slice(0, block.startIdx),
+      ...blockLines,
+      ...lines.slice(block.endIdx + 1),
+    ];
+  } else {
+    // No marker block — check if entries are already present as active
+    // (non-comment) lines. Must filter out comment lines to avoid
+    // false-negatives like "# placeholder .claude/ukit/.ukit/" matching the
+    // entry check and incorrectly skipping the block insertion.
+    const activeLines = lines
+      .map((l) => l.trim())
+      .filter((trimmed) => trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('!'));
+    const missing = UKIT_ENTRIES.filter((e) => !activeLines.some((l) => l === e));
+    if (missing.length === 0) {
+      return false;
     }
-    const updated = content.replace(blockPattern, newBlock);
-    await writeFileAtomic(gitignorePath, updated);
-    return true;
-  }
 
-  // No marker block — check if entries are already present as active (non-comment) lines.
-  // Must filter out comment lines to avoid false-negatives like "# placeholder .claude/ukit/.ukit/"
-  // matching the entry check and incorrectly skipping the block insertion.
-  const activeLines = content
-    .split('\n')
-    .map((l) => l.trim())
-    .filter((trimmed) => trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('!'));
-  const missing = UKIT_ENTRIES.filter((e) => !activeLines.some((l) => l === e));
-  if (missing.length === 0) {
-    return false;
+    // Append the marker block after the existing content.
+    const head = [...lines];
+    while (head.length > 0 && head[head.length - 1].trim() === '') head.pop();
+    nextLines = head.length > 0
+      ? [...head, '', ...blockLines, '']
+      : [...blockLines, ''];
   }
 
-  // Append marker block with missing entries
-  const block = ['', newBlock, ''].join('\n');
-  await writeFileAtomic(gitignorePath, content.trimEnd() + '\n' + block);
+  const next = nextLines.join(eol);
+  if (next === content) {
+    return false; // already up to date
+  }
+  await writeFileAtomic(gitignorePath, next);
   return true;
 }
 
 /**
- * Remove the UKit-managed block from .gitignore.
+ * Remove the UKit-managed block(s) from .gitignore.
  * Called by uninstall to leave the project in a clean state.
- * @returns {boolean} true if the block was found and removed
+ *
+ * Uses the same detection helpers as `ensureGitignore`, so anything
+ * `ensureGitignore` can write (including a CRLF-joined block) is removable, and
+ * a line that merely contains marker-like text is never matched.
+ *
+ * @returns {boolean} true if a block was found and removed
  */
 export async function removeGitignoreBlock(projectRoot) {
   const gitignorePath = path.join(projectRoot, '.gitignore');
@@ -83,35 +165,29 @@ export async function removeGitignoreBlock(projectRoot) {
     return false; // no .gitignore — nothing to remove
   }
 
-  if (!content.includes(MARKER_START)) {
-    return false; // no UKit block present
+  const { eol, lines } = parseGitignore(content);
+
+  let result = lines;
+  let cursor = 0;
+  let removed = false;
+  for (;;) {
+    const block = locateBlock(result, cursor);
+    if (!block) break;
+    removed = true;
+
+    // Drop the blank separator line that ensureGitignore prepended.
+    let from = block.startIdx;
+    if (from > 0 && result[from - 1] === '') from -= 1;
+
+    result = [...result.slice(0, from), ...result.slice(block.endIdx + 1)];
+    cursor = from;
   }
 
-  // Walk lines and excise the block plus any leading blank line that
-  // ensureGitignore appended before the marker.
-  const lines = content.split('\n');
-  const result = [];
-  let inBlock = false;
-
-  for (const line of lines) {
-    if (line === MARKER_START) {
-      inBlock = true;
-      // Remove the blank separator line that ensureGitignore prepended.
-      if (result.length > 0 && result[result.length - 1] === '') {
-        result.pop();
-      }
-      continue;
-    }
-    if (inBlock) {
-      if (line === MARKER_END) {
-        inBlock = false;
-      }
-      continue;
-    }
-    result.push(line);
+  if (!removed) {
+    return false; // no UKit block present
   }
 
-  const joined = result.join('\n').trimEnd();
-  await writeFileAtomic(gitignorePath, joined ? joined + '\n' : '');
+  const joined = result.join(eol).trimEnd();
+  await writeFileAtomic(gitignorePath, joined ? joined + eol : '');
   return true;
 }

package/src/core/runInstallPipeline.js

@@ -53,6 +53,19 @@ function buildTrackedManagedRelativePathSet(plan, projectRoot) {
   );
 }
 
+export function adjustSummaryForSkips(plannedSummary, skippedByAction, skippedUpdates) {
+  if (!skippedUpdates) {
+    return plannedSummary;
+  }
+
+  return {
+    ...plannedSummary,
+    create: plannedSummary.create - (skippedByAction?.create ?? 0),
+    update: plannedSummary.update - (skippedByAction?.update ?? 0),
+    skip: plannedSummary.skip + skippedUpdates,
+  };
+}
+
 function shouldAutoPruneObsoletePath(relativePath) {
   return AUTO_PRUNE_OBSOLETE_PATHS.has(relativePath)
     || AUTO_PRUNE_OBSOLETE_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
@@ -271,7 +284,7 @@ export async function runInstallPipeline({
   const plannedSummary = summarizeDiff(diffResults);
 
   if (!dryRun) {
-    const { writes, skippedUpdates } = await applyDiffResults(diffResults, {
+    const { writes, skippedUpdates, skippedByAction } = await applyDiffResults(diffResults, {
       backupRoot: pathConfig.backupRoot,
       projectRoot: pathConfig.projectRoot,
     });
@@ -291,16 +304,11 @@ export async function runInstallPipeline({
       managedLinkRelativePaths,
     });
 
-    // Adjust summary to reflect link updates that were skipped for safety
-    // (the planned diff counted them as 'update', but apply skipped them).
-    const summary =
-      skippedUpdates > 0
-        ? {
-            ...plannedSummary,
-            update: plannedSummary.update - skippedUpdates,
-            skip: plannedSummary.skip + skippedUpdates,
-          }
-        : plannedSummary;
+    // Adjust summary to reflect entries that were skipped for safety
+    // (the planned diff counted them as 'create'/'update', but apply skipped them).
+    // Subtract from the bucket the skipped entry was actually planned as, so the
+    // adjusted counts never go negative.
+    const summary = adjustSummaryForSkips(plannedSummary, skippedByAction, skippedUpdates);
 
     await writeInstallMetadata({
       installMetaPath: pathConfig.installMetaPath,

package/src/core/runtimeConfig.js

@@ -1,9 +1,15 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { buildRuntimePaths } from './runtimePaths.js';
 
+const require = createRequire(import.meta.url);
+const { version: PACKAGE_VERSION } = require('../../package.json');
+
 const VALID_AGENTS = new Set(['claude-code', 'codex', 'antigravity', 'opencode']);
 
+const BLOCKED_MERGE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
 function isPlainObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -15,6 +21,10 @@ function mergeObjects(base, override) {
 
   const merged = { ...base };
   for (const [key, value] of Object.entries(override)) {
+    if (BLOCKED_MERGE_KEYS.has(key)) {
+      continue;
+    }
+
     const current = merged[key];
     if (isPlainObject(current) && isPlainObject(value)) {
       merged[key] = mergeObjects(current, value);
@@ -49,7 +59,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.5.2',
+    version: PACKAGE_VERSION,
     agent: 'claude-code',
     autonomy: {
       level: 'balanced',
@@ -164,6 +174,24 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
           delegationPolicy: 'allow-review-sidecar',
         },
       },
+      modelTiers: {
+        lite: { claudeModel: 'claude-haiku-4-5', genericModel: 'unic-lite' },
+        code: { claudeModel: 'claude-sonnet-4-6', genericModel: 'unic-code' },
+        smart: { claudeModel: 'claude-opus-4-6', genericModel: 'unic-smart' },
+        vision: {
+          claudeModel: 'unic-vision',
+          genericModel: 'unic-vision',
+          fallbackModel: 'claude-sonnet-4-6',
+          capabilityTier: true,
+          note: 'Capability tier, not a cost tier. Orthogonal to lite/code/smart — never insert into escalation.tierOrder. fallbackModel is used when unicMode is off.',
+        },
+      },
+      escalation: {
+        enabled: true,
+        debugLoopThreshold: 2,
+        tierOrder: ['lite', 'code', 'smart'],
+        cap: 'smart',
+      },
     },
     memory: {
       enabled: true,
@@ -196,6 +224,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       enabled: true,
       smallTaskModel: 'unic-lite',
       smallTaskAgent: 'ukit-small-task-maintainer',
+      visionEnabled: true,
+      visionModel: 'unic-vision',
+      visionAgent: 'ukit-vision-analyst',
+      visionCacheDir: '.ukit/storage/cache/vision',
+      visionMaxImages: 3,
+      visionMaxBytes: 10_485_760,
+      visionRetain: 20,
+      visionSessionTtlHours: 24,
       smallTaskUseCases: [
         'task-cleanup',
         'compact-decision',

package/src/core/uninstall.js

@@ -124,7 +124,12 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     regularPaths = [stateDir]; // always delete state dir — it's always UKit-owned
     linkPaths = [];
 
-    const skipped = [];
+    // Two arrays for two unrelated meanings: invalidPaths are suspicious (forged
+    // or corrupt metadata pointing outside managed prefixes) and always worth a
+    // warning; linkChildPaths are routine (a tracked file under a tracked link
+    // that gets removed along with its parent) and must never warn.
+    const invalidPaths = [];
+    const linkChildPaths = [];
     const trackedEntries = [];
 
     for (const entry of installData.files) {
@@ -137,7 +142,7 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
 
       const normalizedRelative = normalizeToProjectRelative(projectRoot, absolutePath);
       if (!isAllowedProjectPath(normalizedRelative)) {
-        skipped.push(relPath ?? normalizedRelative ?? absolutePath);
+        invalidPaths.push(relPath ?? normalizedRelative ?? absolutePath);
         continue;
       }
 
@@ -159,15 +164,15 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
       );
 
       if (isUnderTrackedLinkPath) {
-        skipped.push(entry.normalizedRelative);
+        linkChildPaths.push(entry.normalizedRelative);
         continue;
       }
 
       regularPaths.push(entry.absolutePath);
     }
 
-    if (skipped.length > 0 && dryRun) {
-      console.warn('[UKit] Skipping invalid uninstall paths from install metadata:', skipped);
+    if (invalidPaths.length > 0) {
+      console.warn('[UKit] Skipping invalid uninstall paths from install metadata:', invalidPaths);
     }
   } else {
     // Old format (no files list): fall back to hardcoded managed paths.