@lyupro/codex-bridge 0.6.8 → 0.6.9

package/cli/home-plan-execute.mjs

@@ -0,0 +1,140 @@
+/**
+ * Carries out a home removal plan and records what happened to every entry.
+ *
+ * Plan_65 D12 item 7 requires the final message to describe outcomes: claiming removal from
+ * intentions hid edited files that uninstall actually kept. D4 forbids following links and
+ * recursive removal; segment checks run immediately before each planned removal.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHomeWriter } from '../src/home/lib/home-write.mjs';
+import { directoryArtifact } from '../src/home/lib/home-registry.mjs';
+import { inspectSegments } from './link-segments.mjs';
+import { installRecordPath, removeInstallOwner } from './install-record.mjs';
+import { removeEmptyHome } from './remove-layout.mjs';
+import { consumePurgeAuthorization } from './purge-preflight.mjs';
+
+function findingReason(finding, root) {
+  if (finding.kind === 'link') {
+    const relative = path.relative(root, finding.at).split(path.sep).join('/');
+    return `link at ${relative}`;
+  }
+  if (finding.kind === 'error') return `unreadable: ${finding.code}`;
+  return finding.kind;
+}
+
+const failure = (error) => error.code ?? error.message;
+
+async function executeFiles(host, plan, writer, add) {
+  for (const row of plan.rows) {
+    if (row.action === 'keep' || row.action === 'blocked' || row.action === 'missing') {
+      add(row.relative, row.action === 'keep' ? 'kept' : row.action, row.reason, row.id);
+      continue;
+    }
+    if (row.action !== 'remove') throw new TypeError(`Invalid home file action: ${row.action}`);
+    const target = path.join(host.brandRoot, row.relative);
+    const finding = inspectSegments(target, host.brandRoot);
+    if (finding.kind !== 'clear') {
+      add(row.relative, finding.kind === 'missing' ? 'missing' : 'kept',
+        findingReason(finding, host.brandRoot), row.id);
+      continue;
+    }
+    try {
+      await writer.unlink(row.id, target);
+      add(row.relative, 'removed', row.reason, row.id);
+    } catch (error) {
+      // One failed file does not stop the rest: each is reported, and a repeat run retries it.
+      add(row.relative, error.code === 'ENOENT' ? 'missing' : 'failed', failure(error), row.id);
+    }
+  }
+}
+
+// After the files, even when one failed: the record is the inventory a repeat run needs, and
+// it changes only for a detached host (cli/uninstall.mjs, D10 item 4).
+async function executeRecord(host, record, writer, detached, add) {
+  const recordRelative = '.installed.json';
+  if (record.dependsOnDetach && !detached) {
+    add(recordRelative, 'kept', 'this host is still attached');
+    return;
+  }
+  if (record.operation === 'retain' || record.operation === 'none') {
+    add(recordRelative, record.operation === 'retain' ? 'kept' : 'missing', record.reason);
+    return;
+  }
+  if (record.operation !== 'delete' && record.operation !== 'remove-current-owner') {
+    throw new TypeError(`Invalid home record operation: ${record.operation}`);
+  }
+  const target = installRecordPath(host);
+  // D4 also guards the owner update, which reads the existing record before publishing it.
+  const finding = inspectSegments(target, host.brandRoot);
+  if (finding.kind !== 'clear') {
+    add(recordRelative, finding.kind === 'missing' ? 'missing' : 'kept', findingReason(finding, host.brandRoot));
+    return;
+  }
+  try {
+    if (record.operation === 'delete') {
+      await writer.unlink('install-record', target);
+      add(recordRelative, 'removed', record.reason);
+      return;
+    }
+    const updated = await removeInstallOwner(host);
+    add(recordRelative, updated === null ? 'missing' : 'kept',
+      updated === null ? 'missing' : 'this host removed from the record');
+  } catch (error) {
+    add(recordRelative, error.code === 'ENOENT' ? 'missing' : 'failed', failure(error));
+  }
+}
+
+async function executeDirectories(host, directories, writer, imageMembers, add) {
+  for (const directory of directories) {
+    if (directory.action === 'keep') continue;
+    if (directory.action !== 'remove-if-empty') {
+      throw new TypeError(`Invalid home directory action: ${directory.action}`);
+    }
+    const target = path.join(host.brandRoot, directory.relative);
+    if (directory.relative !== '') {
+      const finding = inspectSegments(target, host.brandRoot);
+      if (finding.kind === 'missing') continue;
+      if (finding.kind !== 'clear') {
+        add(directory.relative, 'kept', findingReason(finding, host.brandRoot));
+        continue;
+      }
+    }
+    try {
+      if ((await fs.readdir(target)).length !== 0) continue;
+      if (directory.relative === '') {
+        await removeEmptyHome(writer, 'install-image', host.brandRoot);
+        // The helper tolerates absence and a newly non-empty root; only absence proves removal.
+        try {
+          await fs.lstat(target);
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+          add('', 'removed', directory.reason);
+        }
+      } else {
+        await writer.rmdir(directoryArtifact(directory.relative, { imageMembers }), target);
+        add(directory.relative, 'removed', directory.reason);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') add(directory.relative, 'failed', failure(error));
+    }
+  }
+}
+
+export async function executeHomePlan(host, plan, { detached, imageMembers, authorization }) {
+  if (plan.command === 'purge') {
+    consumePurgeAuthorization(authorization, host, plan);
+  } else if (plan.command !== 'uninstall') {
+    throw new TypeError(`Invalid removal command: ${plan.command}`);
+  }
+
+  const writer = createHomeWriter({ root: host.brandRoot, imageMembers });
+  const outcomes = [];
+  // Each step tags its own outcomes: the renderer must not infer a folder from its position.
+  const adder = (kind, fixedId) => (relative, result, reason, id = fixedId) => (
+    outcomes.push({ lane: 'home', kind, id, relative, result, reason }));
+  await executeFiles(host, plan, writer, adder('file', null));
+  await executeRecord(host, plan.record, writer, detached, adder('record', 'install-record'));
+  await executeDirectories(host, plan.directories, writer, imageMembers, adder('directory', null));
+  return { outcomes };
+}

package/cli/home-removal-plan.mjs

@@ -0,0 +1,61 @@
+/**
+ * Gathers what the removal plan of the home needs and builds it, without changing anything.
+ *
+ * Plan_65 D12 item 1 combines the registry's fixed paths, recorded image members, and the
+ * current package's members: a missing record must remain cleanable, and a member dropped
+ * from a newer package must still be found. D12 item 4 keeps corrupt records distinct from
+ * missing records so an unreadable installation record blocks removal.
+ */
+import { asFormat2, imageMembers, readInstallRecordFile } from './install-record.mjs';
+import { validateFormat2 } from './install-owners.mjs';
+import { imagePackageIndex, judgeImageFile } from './image-evidence.mjs';
+import { inspectHome } from './home-inspection.mjs';
+import { planHomeRemoval } from './removal-plan.mjs';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+
+export async function buildHomeRemovalPlan({ command, host, packageRoot, imagePolicy }) {
+  let recordState;
+  let format2;
+  try {
+    const parsed = await readInstallRecordFile(host);
+    if (parsed === null) {
+      recordState = 'missing';
+    } else {
+      const candidate = asFormat2(parsed, host);
+      validateFormat2(candidate);
+      format2 = candidate;
+      recordState = 'valid';
+    }
+  } catch {
+    recordState = 'corrupt';
+  }
+
+  const packageIndex = await imagePackageIndex(host, packageRoot);
+  const recordedMembers = recordState === 'valid'
+    ? imageMembers(format2, host).filter((entry) => entry.root === 'brand').map((entry) => entry.path)
+    : [];
+  const members = [...new Set([...recordedMembers, ...packageIndex.keys()])].sort();
+  const inspection = inspectHome(host.brandRoot, { imageMembers: members });
+  const fingerprints = recordState === 'valid'
+    ? { brand: format2.image.fingerprints?.brand }
+    : undefined;
+  const imageEvidence = new Map();
+  for (const file of inspection.files) {
+    if (file.id !== 'install-image' || file.role !== 'primary') continue;
+    imageEvidence.set(file.relative, await judgeImageFile(
+      host, { root: 'brand', path: file.relative }, fingerprints, packageIndex,
+    ));
+  }
+
+  return {
+    command,
+    ...planHomeRemoval({
+      command, inspection, imageMembers: members, imageEvidence, imagePolicy,
+      recordState, format2, ownerKey: normalizeRepoPath(host.root),
+    }),
+    recordState,
+    homeRoot: inspection.root,
+    format2,
+    imageMembers: members,
+  };
+}

package/cli/hook-recognizer.mjs

@@ -0,0 +1,78 @@
+/**
+ * Recognizes the package's own hook entries in a host's settings by their exact spelling, without
+ * an installation record (Plan_65 D10 item 1).
+ *
+ * A format-1 record never named its host, so a host without an owner entry could only be cleaned
+ * through somebody else's record. What the package wrote into a host carries its name; this module
+ * reads that mark. Only exact commands count: a substring, another interpreter or an unknown file
+ * is a foreign hook, and `commandForm` (settings-merge) only classifies spelling, it proves nothing.
+ */
+import path from 'node:path';
+import { HOOK_DEFINITIONS } from './manifest.mjs';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+
+// Every directory a released version installed hook files into. Checked against git history:
+// agents/codex-bridge never held hooks — they moved into the brand home (7a43fa4, 2026-08-10) a
+// day before that directory existed (4eafc85).
+const HOOK_DIRECTORIES = Object.freeze([
+  Object.freeze({ root: 'brandRoot', segments: ['hooks'] }),
+  // Before 7a43fa4 the path form pointed into host.agentsDir/hooks, and agentsDir was agents/codex.
+  Object.freeze({ root: 'root', segments: ['agents', 'codex', 'hooks'] }),
+]);
+
+const DEFINITION_NAMES = new Set(HOOK_DEFINITIONS.map(({ name }) => name));
+const SHORT_COMMAND = /^codex-bridge hook (\S+)$/;
+const PATH_COMMAND = /^node "([^"\r\n]+)"$/;
+
+// Windows compares file names without case, like normalizeRepoPath does for the rest of the path.
+const sameFile = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+
+function inKnownDirectory(hookPath, host) {
+  const directory = normalizeRepoPath(path.dirname(hookPath));
+  return HOOK_DIRECTORIES.some(({ root, segments }) => typeof host?.[root] === 'string'
+    && directory === normalizeRepoPath(path.join(host[root], ...segments)));
+}
+
+// One file can serve several hooks (dispatcher-gate.mjs is three), so a path names its hook only
+// together with the event; without one, or with no match, the entry is still ours but unnamed.
+function nameForFile(file, event) {
+  const candidates = HOOK_DEFINITIONS.filter((definition) => sameFile(definition.file, file));
+  const matching = event === undefined ? candidates : candidates.filter((definition) => definition.event === event);
+  return matching.length === 1 ? matching[0].name : null;
+}
+
+export function isOwnHookCommand(command, host, event) {
+  if (typeof command !== 'string') return { own: false };
+  const short = SHORT_COMMAND.exec(command);
+  if (short && DEFINITION_NAMES.has(short[1])) return { own: true, name: short[1], form: 'short' };
+  const spelled = PATH_COMMAND.exec(command);
+  if (!spelled || !path.isAbsolute(spelled[1])) return { own: false };
+  const file = path.basename(spelled[1]);
+  if (!HOOK_DEFINITIONS.some((definition) => sameFile(definition.file, file)) || !inKnownDirectory(spelled[1], host)) {
+    return { own: false };
+  }
+  return { own: true, name: nameForFile(file, event), form: 'path' };
+}
+
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+/** Lists own hook entries across every event; unreadable settings throw, because unknown is not "none". */
+export function findOwnHooks(settings, host) {
+  if (!isObject(settings)) throw new TypeError('settings must be an object');
+  if (!isObject(settings.hooks)) return [];
+  const found = [];
+  for (const [event, groups] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    groups.forEach((group, groupIndex) => {
+      if (!isObject(group) || !Array.isArray(group.hooks)) return;
+      group.hooks.forEach((hook, hookIndex) => {
+        if (hook?.type !== 'command') return;
+        const recognized = isOwnHookCommand(hook.command, host, event);
+        if (!recognized.own) return;
+        const { name, form } = recognized;
+        found.push({ event, groupIndex, hookIndex, matcher: group.matcher, command: hook.command, name, form });
+      });
+    });
+  }
+  return found;
+}

package/cli/host-contract.mjs

@@ -12,10 +12,10 @@
  */
 import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import fs from 'node:fs/promises';
 import path from 'node:path';
 import { CLI_NAMES } from '../src/home/lib/cli-names.mjs';
 import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
+import { createHomeWriter } from '../src/home/lib/home-write.mjs';
 import { readJsonFile } from '../src/home/lib/json-file.mjs';
 
 export const HOST_CONTRACT_RECORD_NAME = '.host-contract.json';
@@ -69,12 +69,18 @@ export async function writeHostContract(host, { version, result, now = new Date(
     Number.isFinite(Date.parse(entry?.checkedAt)) && Date.parse(entry.checkedAt) >= cutoff));
   hosts[version] = { result, checkedAt: now.toISOString() };
   const record = { hosts };
-  await fs.mkdir(host.brandRoot, { recursive: true });
+  const writer = createHomeWriter({ root: host.brandRoot });
+  writer.assertArtifact('host-contract', target);
+  await writer.mkdir('host-contract', host.brandRoot, { recursive: true });
   try {
-    await fs.writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
-    await fs.rename(temporary, target);
+    await writer.writeFile('host-contract', temporary, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    await writer.rename('host-contract', temporary, target);
   } finally {
-    await fs.rm(temporary, { force: true });
+    try {
+      await writer.unlink('host-contract', temporary);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
   }
 }
 

package/cli/host-inspection.mjs

@@ -0,0 +1,156 @@
+/**
+ * Inspects what the package left in one host and which of it may be deleted, without changing
+ * anything (Plan_65 D10 items 1 and 3).
+ *
+ * What lies in a host is read from the package's marks there, not from the home record: a format-1
+ * record never named its host. Deletion needs content evidence — the host's own recorded
+ * fingerprint or the current package's bytes — because uninstall used to delete recorded files
+ * without comparing anything, and an operator-edited agent file was lost with them.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  buildInstallPlan,
+  contentFingerprint,
+  legacyInstallRecordPath,
+} from './manifest.mjs';
+import { plannedContent } from './copy.mjs';
+import { findOwnHooks } from './hook-recognizer.mjs';
+import { readSettings } from './settings-merge.mjs';
+import { inspectPermissions } from './permissions.mjs';
+
+const SEED_NAMES = new Set(['config.json', 'conventions.md']);
+const posix = (value) => value.split(path.sep).join('/');
+
+function result(context, target, disposition, reason) {
+  const relativeToHost = posix(path.relative(context.host.root, target));
+  return { target, relativeToHost, disposition, reason };
+}
+
+const unreadable = (context, target, error) => result(context, target, 'keep', `unreadable: ${error.code ?? 'UNKNOWN'}`);
+
+function isWithin(directory, target) {
+  const relative = path.relative(directory, target);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+async function judgeFile(context, target, item) {
+  const { host, owner } = context;
+  let bytes;
+  try {
+    bytes = await fs.readFile(target);
+  } catch (error) {
+    return unreadable(context, target, error);
+  }
+  const relative = posix(path.relative(host.root, target));
+  const recorded = owner?.fingerprints?.claude?.[relative];
+  if (typeof recorded === 'string' && contentFingerprint(bytes) === recorded) {
+    return result(context, target, 'remove', "matches this host's record");
+  }
+  if (item && bytes.equals(await plannedContent(item, host.brandRoot))) {
+    return result(context, target, 'remove', 'matches the package');
+  }
+  return result(context, target, 'keep', item ? 'changed' : 'unknown');
+}
+
+// Links are never followed (Plan_65 D4): a junction inside a package folder points somewhere else.
+async function lstatOrReport(context, target) {
+  try {
+    return await fs.lstat(target);
+  } catch (error) {
+    if (error.code !== 'ENOENT') context.files.push(unreadable(context, target, error));
+    return null;
+  }
+}
+
+async function walk(context, target) {
+  const stat = await lstatOrReport(context, target);
+  if (!stat) return;
+  if (stat.isSymbolicLink()) {
+    context.files.push(result(context, target, 'keep', 'link'));
+    return;
+  }
+  if (stat.isDirectory()) {
+    let entries;
+    try {
+      entries = await fs.readdir(target);
+    } catch (error) {
+      context.files.push(unreadable(context, target, error));
+      return;
+    }
+    for (const entry of entries) await walk(context, path.join(target, entry));
+    return;
+  }
+  const { host, planByTarget } = context;
+  if (SEED_NAMES.has(path.basename(target)) && [host.agentsDir, host.commandsDir].includes(path.dirname(target))) {
+    context.files.push(result(context, target, 'keep', 'seed'));
+    return;
+  }
+  context.files.push(await judgeFile(context, target, planByTarget.get(path.resolve(target))));
+}
+
+// The pre-0.6 folder name is not unique to the package: only the names the package installs are
+// looked at, never the folder as a whole. Each is judged against the package file of the same name.
+async function inspectLegacyDirectory(context, directory, items) {
+  const stat = await lstatOrReport(context, directory);
+  if (!stat) return;
+  if (stat.isSymbolicLink()) {
+    context.files.push(result(context, directory, 'keep', 'link'));
+    return;
+  }
+  if (!stat.isDirectory()) return;
+  for (const item of items) {
+    const target = path.join(directory, path.basename(item.target));
+    const entry = await lstatOrReport(context, target);
+    if (!entry) continue;
+    if (entry.isSymbolicLink()) context.files.push(result(context, target, 'keep', 'link'));
+    else if (entry.isFile()) context.files.push(await judgeFile(context, target, item));
+  }
+}
+
+async function inspectLegacyRecord(context) {
+  const target = legacyInstallRecordPath(context.host);
+  const stat = await lstatOrReport(context, target);
+  if (stat?.isFile()) context.files.push(result(context, target, 'remove', 'old installation record'));
+  else if (stat?.isSymbolicLink()) context.files.push(result(context, target, 'keep', 'link'));
+}
+
+async function inspectSettings(host) {
+  try {
+    const state = await readSettings(host.settingsPath);
+    return { hooks: state.exists ? findOwnHooks(state.settings, host) : [], settingsError: null };
+  } catch (error) {
+    return { hooks: [], settingsError: error.message };
+  }
+}
+
+// Own permission strings are reported, not counted as an installation: `codex-bridge permissions
+// add` sets them alone. An unparseable settings file is already named by settingsError.
+async function inspectOwnPermissions(host) {
+  try {
+    return { present: (await inspectPermissions(host.settingsPath)).present };
+  } catch {
+    return { present: null };
+  }
+}
+
+export async function inspectHost(host, { owner = null, packageRoot } = {}) {
+  const plan = await buildInstallPlan(host, packageRoot);
+  const context = {
+    host,
+    owner,
+    planByTarget: new Map(plan.map((item) => [path.resolve(item.target), item])),
+    files: [],
+  };
+  await walk(context, host.agentsDir);
+  await walk(context, host.commandsDir);
+  await inspectLegacyDirectory(context, host.legacyAgentsDir, plan.filter((item) => isWithin(host.agentsDir, item.target)));
+  await inspectLegacyDirectory(context, host.legacyCommandsDir, plan.filter((item) => isWithin(host.commandsDir, item.target)));
+  await inspectLegacyRecord(context);
+  const files = context.files.sort((a, b) => a.relativeToHost.localeCompare(b.relativeToHost));
+  return { files, ...(await inspectSettings(host)), permissions: await inspectOwnPermissions(host) };
+}
+
+export function hasPackageMarks(inspection) {
+  return inspection.files.length > 0 || inspection.hooks.length > 0;
+}

package/cli/host-removal.mjs

@@ -0,0 +1,91 @@
+/**
+ * Applies a host inspection by removing eligible host files and this package's hooks (Plan_65 D10
+ * items 3 and 4). The shared image is left for uninstall, which may remove it only after the host
+ * has no hook pointing to it.
+ */
+import { recordHomeWriter, removeOutside } from './record-removal.mjs';
+import { claudeBoundary, removeEmptyParents } from './remove-layout.mjs';
+import { recordTarget } from './install-record.mjs';
+import { commandFor, removeHook, shortCommandFor } from './settings-merge.mjs';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+
+// Plan_65 D10 item 5: only the host's own owner entry proves we created a group; legacy never does.
+function recordedCreation(owner, host, found) {
+  if (!owner || !found.name || normalizeRepoPath(owner.root) !== normalizeRepoPath(host.root)) return false;
+  return (owner.hooks ?? []).some((hook) => {
+    if (hook?.event !== found.event || hook.createdGroup !== true) return false;
+    let command = hook.command;
+    if (typeof command !== 'string') {
+      try {
+        command = commandFor(recordTarget(host, hook));
+      } catch {
+        return false;
+      }
+    }
+    return command === found.command || command === shortCommandFor(found.name);
+  });
+}
+
+// Decided per group before anything is removed: with two own hooks in one group and evidence on
+// only one, a per-hook flag made the outcome depend on removal order. removeHook drops a group
+// only once it is empty, so an emptied group we created goes and a shared one stays.
+function createdGroups(owner, host, hooks) {
+  const created = new Set();
+  for (const hook of hooks) {
+    if (recordedCreation(owner, host, hook)) created.add(`${hook.event}#${hook.groupIndex}`);
+  }
+  return created;
+}
+
+// Hooks go first and files only once the host is detached. Removing files ahead of a failed hook
+// took the old per-host installation record with them (acceptance of H3b, 2026-09-28): the host kept
+// hooks into an image that no longer had any inventory, so no later uninstall could remove it. Either
+// the host is detached, or its files are exactly as they were and a repeat run finishes the job.
+async function removeOwnHooks(host, inspection, owner, dryRun, lines) {
+  if (inspection.settingsError != null) {
+    lines.push(`Left the hooks in ${host.settingsPath}: ${inspection.settingsError}`);
+    return false;
+  }
+  let detached = true;
+  const created = createdGroups(owner, host, inspection.hooks);
+  for (const hook of inspection.hooks) {
+    const identity = hook.name ?? hook.command;
+    if (dryRun) {
+      lines.push(`Would remove the ${hook.event} hook ${identity}`);
+      continue;
+    }
+    try {
+      await removeHook(host.settingsPath, {
+        event: hook.event,
+        matcher: hook.matcher,
+        command: hook.command,
+        alternateCommands: [],
+      }, { createdGroup: created.has(`${hook.event}#${hook.groupIndex}`) });
+      lines.push(`Removed the ${hook.event} hook ${identity}`);
+    } catch (error) {
+      detached = false;
+      lines.push(`Failed to remove the ${hook.event} hook ${identity}: ${error?.message ?? String(error)}`);
+    }
+  }
+  return detached;
+}
+
+export async function removeHostSide(host, inspection, { owner = null, dryRun = false } = {}) {
+  const lines = [];
+  const detached = await removeOwnHooks(host, inspection, owner, dryRun, lines);
+  const writer = dryRun ? null : recordHomeWriter(host, []);
+  for (const file of inspection.files) {
+    if (file.disposition !== 'remove') {
+      lines.push(`Left ${file.relativeToHost} (${file.reason})`);
+    } else if (!detached) {
+      lines.push(`${dryRun ? 'Would leave' : 'Left'} ${file.relativeToHost} (this host's hooks could not be removed)`);
+    } else {
+      if (!dryRun) {
+        await removeOutside(writer, file.target);
+        await removeEmptyParents(file.target, claudeBoundary(host, file.target));
+      }
+      lines.push(`${dryRun ? 'Would remove' : 'Removed'} ${file.relativeToHost}`);
+    }
+  }
+  return { lines, detached };
+}

package/cli/image-evidence.mjs

@@ -0,0 +1,44 @@
+/**
+ * Judges whether an image file may be removed by content evidence (D10 item 3).
+ * Plan_65 D12 requires uninstall and the home removal plan to share this read-only judgment,
+ * so their protection of operator edits cannot drift into two different implementations.
+ */
+import fs from 'node:fs/promises';
+import { buildInstallPlan, contentFingerprint } from './manifest.mjs';
+import { plannedContent } from './copy.mjs';
+import { fingerprintFor, recordTarget } from './install-record.mjs';
+
+export async function imagePackageIndex(host, packageRoot) {
+  const plan = await buildInstallPlan(host, packageRoot);
+  return new Map(plan
+    .filter((item) => item.root === 'brand')
+    .map((item) => [item.relativeToRoot, item]));
+}
+
+export async function judgeImageFile(host, file, fingerprints, packageIndex) {
+  const target = recordTarget(host, file);
+  let stat;
+  try {
+    stat = await fs.lstat(target);
+  } catch (error) {
+    if (error.code === 'ENOENT') return { verdict: 'missing', reason: 'missing' };
+    return { verdict: 'keep', reason: `unreadable: ${error.code ?? 'UNKNOWN'}` };
+  }
+  if (stat.isSymbolicLink()) return { verdict: 'keep', reason: 'link' };
+
+  let bytes;
+  try {
+    bytes = await fs.readFile(target);
+  } catch (error) {
+    if (error.code === 'ENOENT') return { verdict: 'missing', reason: 'missing' };
+    return { verdict: 'keep', reason: `unreadable: ${error.code ?? 'UNKNOWN'}` };
+  }
+
+  const recorded = fingerprintFor({ fingerprints }, file);
+  const matchesRecord = typeof recorded === 'string' && contentFingerprint(bytes) === recorded;
+  if (matchesRecord) return { verdict: 'remove', reason: 'recorded' };
+  const item = packageIndex.get(file.path);
+  const matchesPackage = item ? bytes.equals(await plannedContent(item, host.brandRoot)) : false;
+  if (matchesPackage) return { verdict: 'remove', reason: 'package' };
+  return { verdict: 'keep', reason: 'changed' };
+}