@lyupro/codex-bridge 0.6.7 → 0.6.9

package/cli/doctor-installation.mjs

@@ -1,111 +1,111 @@
-/** Reports whether what this package installed into the host still matches the package. */
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import {
-  buildInstallPlan,
-  contentFingerprint,
-  fileFingerprint,
-} from './manifest.mjs';
-import { plannedContent } from './copy.mjs';
-import { RULE_LIST_NAMES, inspectPermissions } from './permissions.mjs';
-import { readRulesRegistry } from './rules-owners.mjs';
-import { parseFrontmatter } from './frontmatter.mjs';
-import { check } from './doctor-format.mjs';
-
-export async function exists(target) {
-  try {
-    await fs.access(target);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export async function isFile(target) {
-  try {
-    return (await fs.stat(target)).isFile();
-  } catch {
-    return false;
-  }
-}
-
-export async function agentsCheck(host, record) {
-  if (!record) return check('agents', 'warn', 'Agent definitions were not checked; run codex-bridge install');
-  const plan = await buildInstallPlan(host);
-  const agents = plan.filter((item) => /[\\/]src[\\/]agents[\\/][^\\/]+\.md$/.test(item.source));
-  const mismatches = [];
-  const unreadable = [];
-  for (const item of agents) {
-    const expected = contentFingerprint(await plannedContent(item, host.brandRoot));
-    if (await fileFingerprint(item.target) !== expected) mismatches.push(path.basename(item.target));
-    const expectedName = path.basename(item.source, '.md');
-    try {
-      const frontmatter = parseFrontmatter(await fs.readFile(item.target, 'utf8'));
-      if (!frontmatter) throw new Error('frontmatter is missing');
-      if (frontmatter.name !== expectedName) {
-        throw new Error(`name is ${JSON.stringify(frontmatter.name)}, expected ${JSON.stringify(expectedName)}`);
-      }
-    } catch (err) {
-      unreadable.push(`${path.basename(item.target)} (${err.message})`);
-    }
-  }
-  // The 2026-08-10 registration failure left files present but unreadable by Claude Code. Drift was
-  // advisory until a 2026-08-16 checklist run planted the pre-Plan_41 invocation — a path instead of
-  // the package command — in an installed definition: doctor kept exit 0 while every delegation
-  // would stop on a permission prompt. A definition that is not this package's is not judged healthy.
-  if (unreadable.length) {
-    return check('agents', 'fail', `Installed agent definitions cannot be read: ${unreadable.join(', ')}; run codex-bridge update --force`);
-  }
-  return mismatches.length
-    ? check('agents', 'fail', `Installed agent definitions differ from this package: ${mismatches.join(', ')}; run codex-bridge update --force`)
-    : check('agents', 'ok', `${agents.length} installed agent definition(s) match this package`);
-}
-
-export async function conventionsCheck(host) {
-  const file = host.brandConventionsPath;
-  let content;
-  try {
-    content = await fs.readFile(file, 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') return check('conventions', 'ok', `${file} (not found; optional)`);
-    return check('conventions', 'fail', `cannot read ${file}: ${err.message}`);
-  }
-  return content.trim()
-    ? check('conventions', 'ok', `${file} (found)`)
-    : check('conventions', 'warn', `${file} (found but empty)`);
-}
-
-export async function rulesCheck(host, record) {
-  if (!record) return check('rules', 'warn', 'cannot check before installation');
-  if (!record.rules) {
-    return check('rules', 'warn', 'rules were not installed by this installation; install or update will add them');
-  }
-  let registry;
-  try {
-    registry = await readRulesRegistry(host);
-  } catch (err) {
-    // Keep every diagnostic visible: package removal on a broken registry left the host without its watchdog.
-    return check('rules', 'fail', err.message);
-  }
-  const ownerNote = registry?.owners.length > 1 ? `; ${registry.owners.length} owners` : '';
-  const fingerprint = await fileFingerprint(record.rules.path);
-  if (!fingerprint) return check('rules', 'fail', `${record.rules.path}${ownerNote ? ` (${registry.owners.length} owners)` : ''}`);
-  return fingerprint === record.rules.fingerprint
-    ? check('rules', 'ok', `${record.rules.path} (matches record${ownerNote})`)
-    : check('rules', 'warn', `${record.rules.path} (modified after installation${ownerNote})`);
-}
-
-export async function permissionsCheck(host) {
-  try {
-    const status = await inspectPermissions(host.settingsPath);
-    // Permission rules are an optional operator action; Plan_22 keeps their absence a warning so
-    // doctor does not turn a healthy installation red merely because hardening was not requested.
-    // The ask count is part of the line because a full set shadowed by `ask` reads as working and
-    // is not: the live run of Plan_22-1 found this line saying `installed (24/24)` over it.
-    const shadow = status.askCount ? `, ${status.askCount} shadowed by ask` : '';
-    return check('permissions', status.state === 'installed' ? 'ok' : 'warn',
-      `${status.state} (${status.present}/${status.total} own strings in ${RULE_LIST_NAMES}${shadow})`);
-  } catch (err) {
-    return check('permissions', 'warn', `cannot inspect permission rules: ${err.message}`);
-  }
-}
+/** Reports whether what this package installed into the host still matches the package. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  buildInstallPlan,
+  contentFingerprint,
+  fileFingerprint,
+} from './manifest.mjs';
+import { plannedContent } from './copy.mjs';
+import { RULE_LIST_NAMES, inspectPermissions } from './permissions.mjs';
+import { readRulesRegistry } from './rules-owners.mjs';
+import { parseFrontmatter } from './frontmatter.mjs';
+import { check } from './doctor-format.mjs';
+
+export async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isFile(target) {
+  try {
+    return (await fs.stat(target)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export async function agentsCheck(host, record) {
+  if (!record) return check('agents', 'warn', 'Agent definitions were not checked; run codex-bridge install');
+  const plan = await buildInstallPlan(host);
+  const agents = plan.filter((item) => /[\\/]src[\\/]agents[\\/][^\\/]+\.md$/.test(item.source));
+  const mismatches = [];
+  const unreadable = [];
+  for (const item of agents) {
+    const expected = contentFingerprint(await plannedContent(item, host.brandRoot));
+    if (await fileFingerprint(item.target) !== expected) mismatches.push(path.basename(item.target));
+    const expectedName = path.basename(item.source, '.md');
+    try {
+      const frontmatter = parseFrontmatter(await fs.readFile(item.target, 'utf8'));
+      if (!frontmatter) throw new Error('frontmatter is missing');
+      if (frontmatter.name !== expectedName) {
+        throw new Error(`name is ${JSON.stringify(frontmatter.name)}, expected ${JSON.stringify(expectedName)}`);
+      }
+    } catch (err) {
+      unreadable.push(`${path.basename(item.target)} (${err.message})`);
+    }
+  }
+  // The 2026-08-10 registration failure left files present but unreadable by Claude Code. Drift was
+  // advisory until a 2026-08-16 checklist run planted the pre-Plan_41 invocation — a path instead of
+  // the package command — in an installed definition: doctor kept exit 0 while every delegation
+  // would stop on a permission prompt. A definition that is not this package's is not judged healthy.
+  if (unreadable.length) {
+    return check('agents', 'fail', `Installed agent definitions cannot be read: ${unreadable.join(', ')}; run codex-bridge update --force`);
+  }
+  return mismatches.length
+    ? check('agents', 'fail', `Installed agent definitions differ from this package: ${mismatches.join(', ')}; run codex-bridge update --force`)
+    : check('agents', 'ok', `${agents.length} installed agent definition(s) match this package`);
+}
+
+export async function conventionsCheck(host) {
+  const file = host.brandConventionsPath;
+  let content;
+  try {
+    content = await fs.readFile(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return check('conventions', 'ok', `${file} (not found; optional)`);
+    return check('conventions', 'fail', `cannot read ${file}: ${err.message}`);
+  }
+  return content.trim()
+    ? check('conventions', 'ok', `${file} (found)`)
+    : check('conventions', 'warn', `${file} (found but empty)`);
+}
+
+export async function rulesCheck(host, record) {
+  if (!record) return check('rules', 'warn', 'cannot check before installation');
+  if (!record.rules) {
+    return check('rules', 'warn', 'rules were not installed by this installation; install or update will add them');
+  }
+  let registry;
+  try {
+    registry = await readRulesRegistry(host);
+  } catch (err) {
+    // Keep every diagnostic visible: package removal on a broken registry left the host without its watchdog.
+    return check('rules', 'fail', err.message);
+  }
+  const ownerNote = registry?.owners.length > 1 ? `; ${registry.owners.length} owners` : '';
+  const fingerprint = await fileFingerprint(record.rules.path);
+  if (!fingerprint) return check('rules', 'fail', `${record.rules.path}${ownerNote ? ` (${registry.owners.length} owners)` : ''}`);
+  return fingerprint === record.rules.fingerprint
+    ? check('rules', 'ok', `${record.rules.path} (matches record${ownerNote})`)
+    : check('rules', 'warn', `${record.rules.path} (modified after installation${ownerNote})`);
+}
+
+export async function permissionsCheck(host) {
+  try {
+    const status = await inspectPermissions(host.settingsPath);
+    // Permission rules are an optional operator action; Plan_22 keeps their absence a warning so
+    // doctor does not turn a healthy installation red merely because hardening was not requested.
+    // The ask count is part of the line because a full set shadowed by `ask` reads as working and
+    // is not: the live run of Plan_22-1 found this line saying `installed (24/24)` over it.
+    const shadow = status.askCount ? `, ${status.askCount} shadowed by ask` : '';
+    return check('permissions', status.state === 'installed' ? 'ok' : 'warn',
+      `${status.state} (${status.present}/${status.total} own strings in ${RULE_LIST_NAMES}${shadow})`);
+  } catch (err) {
+    return check('permissions', 'warn', `cannot inspect permission rules: ${err.message}`);
+  }
+}

package/cli/doctor.mjs

@@ -4,9 +4,11 @@ import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { packageSource } from './package-source.mjs';
 import { readInstallRecord, packageInfo } from './manifest.mjs';
-import { recordTarget } from './install-record.mjs';
+import { readInstallRecordFile, recordTarget } from './install-record.mjs';
 import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 import { check, renderDoctor } from './doctor-format.mjs';
+import { homeOwnersCheck, hostSideCheck, ownerEntry, ownersInSyncCheck } from './doctor-host-side.mjs';
+import { inspectHost } from './host-inspection.mjs';
 import {
   agentsCheck,
   conventionsCheck,
@@ -16,13 +18,15 @@ import {
   rulesCheck,
 } from './doctor-installation.mjs';
 import { hookChecks } from './doctor-hooks.mjs';
-import { contractStatus, detectHostVersion, readHostContract } from './host-contract.mjs';
+import { contractStatus, readHostContract } from './host-contract.mjs';
 import { handbackWitnessStatus } from './handback-witness-check.mjs';
 import { dispatcherContractStatus } from './dispatcher-contract.mjs';
 import { DISPATCHER_CONTRACT_FILE, readDispatcherContract } from './dispatcher-contract-record.mjs';
 import { PROBE_COMMAND } from './host-contract.mjs';
 import { readHandbackWitness } from '../src/home/lib/handback-witness.mjs';
 import { brandStateDir } from '../src/home/lib/brand-home.mjs';
+import { readHostObservations } from '../src/home/lib/host-observations.mjs';
+import { otherHostCheck, sessionHostCheck, sessionHostVersions } from './session-hosts.mjs';
 import { liveRunsCheck, projectRunsCheck, retentionCheck } from './doctor-runs.mjs';
 
 export { renderDoctor };
@@ -81,6 +85,7 @@ export async function diagnose({
   handbackWitnessRecord,
   dispatcherContractRecord,
   hostVersion,
+  observations,
 } = {}) {
   const checks = [sourceCheck()];
   const hostExists = await exists(host.root);
@@ -105,6 +110,20 @@ export async function diagnose({
     checks.push(check('installation', 'fail', `broken record: ${err.message}`));
   }
 
+  let rawRecord = null;
+  let rawRecordError = null;
+  try {
+    rawRecord = await readInstallRecordFile(host);
+  } catch (err) {
+    rawRecordError = err;
+  }
+  // The owner row goes into the inspection so "kept by uninstall" names exactly what uninstall would keep.
+  const inspection = await inspectHost(host, { owner: ownerEntry(rawRecord, host) });
+  checks.push(hostSideCheck(host, inspection));
+  checks.push(rawRecordError
+    ? check('home owners', 'fail', `broken record: ${rawRecordError.message}`)
+    : await homeOwnersCheck(host, rawRecord, inspection));
+  if (rawRecordError === null) checks.push(ownersInSyncCheck(rawRecord));
   const missingFiles = [];
   if (record) {
     for (const file of record.files) {
@@ -124,27 +143,35 @@ export async function diagnose({
   const bridge = bridgeProbe();
   checks.push(bridgeCommandCheck(bridge));
   checks.push(...await hookChecks(host, record, launcherProbe));
-  const detectedHostVersion = hostVersion === undefined ? detectHostVersion() : hostVersion;
+  const stateDir = brandStateDir(host.brandRoot);
+  const hostObservations = observations === undefined ? readHostObservations({ stateDir }) : observations;
+  const observedVersions = sessionHostVersions(hostObservations);
+  const detectedHostVersion = hostVersion === undefined ? observedVersions[0] ?? null : hostVersion;
+  checks.push(sessionHostCheck(observedVersions, hostObservations));
+  const refusalRecord = contractRecord === undefined ? await readHostContract(host) : contractRecord;
   const hostContract = contractStatus({
-    record: contractRecord === undefined ? await readHostContract(host) : contractRecord,
+    record: refusalRecord,
     version: detectedHostVersion,
   });
   const hostContractStatus = hostContract.state === 'verified'
     ? 'ok'
     : hostContract.state === 'ignored' ? 'fail' : 'warn';
   checks.push(check('hostContract', hostContractStatus, hostContract.message));
-  const stateDir = brandStateDir(host.brandRoot);
   const witness = handbackWitnessStatus({
     record: handbackWitnessRecord === undefined ? readHandbackWitness({ stateDir }) : handbackWitnessRecord,
     hostVersion: detectedHostVersion,
     stateDir,
   });
   checks.push(check('handbackWitness', ['seen', 'unobserved'].includes(witness.state) ? 'ok' : 'warn', witness.message));
+  const dispatcherRecord = dispatcherContractRecord === undefined ? readDispatcherContract({ stateDir }) : dispatcherContractRecord;
   checks.push(...dispatcherContractChecks({
-    record: dispatcherContractRecord === undefined ? readDispatcherContract({ stateDir }) : dispatcherContractRecord,
+    record: dispatcherRecord,
     version: detectedHostVersion,
     stateDir,
   }));
+  for (const version of observedVersions.filter((item) => item !== detectedHostVersion)) {
+    checks.push(otherHostCheck({ version, contractRecord: refusalRecord, dispatcherRecord }));
+  }
   const retention = retentionCheck(host);
   checks.push(retention);
   const conventions = await conventionsCheck(host);
@@ -163,7 +190,8 @@ export async function diagnose({
     exitCode: !record || recordBroken || missingFiles.length || agents.status === 'fail' || rules.status === 'fail'
       || hostContractStatus === 'fail' || retention.status === 'fail' || conventions.status === 'fail'
       || projectRuns.status === 'fail'
-      || checks.some((item) => /^(hook|dispatcherContract):/.test(item.key) && item.status === 'fail') ? 1 : 0,
+      || checks.some((item) => /^(hook|dispatcherContract):/.test(item.key) && item.status === 'fail')
+      || checks.some((item) => item.key.startsWith('otherHost:') && item.status === 'fail') ? 1 : 0,
     checks,
     record,
     missingFiles,

package/cli/handback-witness-check.mjs

@@ -1,13 +1,7 @@
-/** Surfaces handback drift because the 2026-09-17..24 contract break went unnoticed for a week. */
+/** Surfaces handback drift; 2026-09-25 established exact host transcript versions as identity. */
 import path from 'node:path';
 import { WITNESS_FILE } from '../src/home/lib/handback-witness.mjs';
 
-function versionParts(value) {
-  if (typeof value !== 'string') return null;
-  const match = value.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:\s|$)/);
-  return match ? { version: match[0].trim(), patch: match[3] } : null;
-}
-
 export function handbackWitnessStatus({ record, hostVersion, stateDir }) {
   if (record?.corrupt) {
     return { state: 'unreadable', message: `The handback witness is unreadable; delete ${path.join(stateDir, WITNESS_FILE)} to reset it.` };
@@ -16,24 +10,22 @@ export function handbackWitnessStatus({ record, hostVersion, stateDir }) {
     const alarm = record.alarms.at(-1);
     return {
       state: 'alarm',
-      message: `${record.alarms.length} dispatcher alarm(s); newest: ${alarm.detail} at ${alarm.at}; do not trust a dispatcher answer from that time; see Plan_62 D15.`,
+      message: `${record.alarms.length} dispatcher alarm(s); newest on ${alarm.hostVersion ?? 'unknown host'}: ${alarm.detail} at ${alarm.at}; do not trust a dispatcher answer from that time; see Plan_62 D15.`,
     };
   }
-  if (!record?.lastSeen) {
+  if (!record?.lastSeen || Object.keys(record.lastSeen).length === 0) {
     return { state: 'unobserved', message: 'Not observed yet — a handback is seen only when a dispatcher runs in an interactive session.' };
   }
 
-  const seen = versionParts(record.lastSeen.sdkVersion);
-  const host = versionParts(hostVersion);
-  // Plan_62 D9 pairs observed SDK 0.3.281 inside Claude Code 2.1.281 hooks; matching patches are current.
-  if (seen && host && seen.patch !== host.patch) {
+  if (record.lastSeen[hostVersion]) {
+    return { state: 'seen', message: `Handback contract last seen on host ${hostVersion} at ${record.lastSeen[hostVersion]}.` };
+  }
+  const [newest, iso] = Object.entries(record.lastSeen).sort((left, right) => right[1].localeCompare(left[1]))[0];
+  if (newest) {
     return {
       state: 'stale',
-      message: `Last seen on SDK ${record.lastSeen.sdkVersion} at ${record.lastSeen.at}; current host ${hostVersion}; run any dispatcher once in an interactive session to observe it again.`,
+      message: `Handback contract last seen on host ${newest} at ${iso}, not yet on host ${hostVersion}; it is recorded the next time a dispatcher runs in an interactive session on that host.`,
     };
   }
-  return {
-    state: 'seen',
-    message: `Handback contract last seen on SDK ${record.lastSeen.sdkVersion} (host ${hostVersion}) at ${record.lastSeen.at}.`,
-  };
+  return { state: 'unobserved', message: 'Not observed yet — a handback is seen only when a dispatcher runs in an interactive session.' };
 }

package/cli/home-inspection.mjs

@@ -0,0 +1,122 @@
+/**
+ * Lists what lies in the package home, classified by the home registry, without crossing a link.
+ *
+ * Plan_65 D4 trusts the root as written: a relocated home or CODEX_BRIDGE_HOME may legitimately
+ * reach it through a link. Below that root, links and junctions stay and are named, never read
+ * through or removed. Walking ancestors first prevents even an lstat below a discovered link.
+ * Only ENOENT means gone; every other read failure must stay visible to a later removal planner.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  HOME_ARTIFACTS,
+  HOME_DIRECTORIES,
+  classifyHomePath,
+  homeArtifact,
+} from '../src/home/lib/home-registry.mjs';
+
+function knownDirectories(imageMembers) {
+  const directories = new Set(HOME_DIRECTORIES);
+  const addAncestors = (relative) => {
+    let parent = path.posix.dirname(relative);
+    while (parent !== '.' && parent !== '/') {
+      directories.add(parent);
+      parent = path.posix.dirname(parent);
+    }
+  };
+  for (const artifact of HOME_ARTIFACTS) {
+    if (Array.isArray(artifact.primary)) {
+      for (const relative of artifact.primary) addAncestors(relative);
+    } else {
+      directories.add(artifact.primary.dir);
+      addAncestors(artifact.primary.dir);
+    }
+  }
+  for (const relative of imageMembers) addAncestors(relative);
+  return directories;
+}
+
+const byRelative = (left, right) => (
+  left.relative < right.relative ? -1 : left.relative > right.relative ? 1 : 0
+);
+
+export function inspectHome(brandRoot, {
+  imageMembers = [],
+  lstat = fs.lstatSync,
+  readdir = fs.readdirSync,
+} = {}) {
+  const result = {
+    root: 'present',
+    rootCode: null,
+    files: [],
+    unknown: [],
+    links: [],
+    errors: [],
+    directories: [],
+  };
+  try {
+    // D4 deliberately follows the root itself, unlike every entry below it.
+    if (!fs.statSync(brandRoot).isDirectory()) {
+      result.root = 'error';
+      result.rootCode = 'ENOTDIR';
+      return result;
+    }
+  } catch (error) {
+    result.root = error.code === 'ENOENT' ? 'missing' : 'error';
+    result.rootCode = error.code === 'ENOENT' ? null : error.code;
+    return result;
+  }
+
+  const known = knownDirectories(imageMembers);
+  const recordError = (relative, error) => {
+    if (error.code !== 'ENOENT') result.errors.push({ relative, code: error.code });
+  };
+  const walk = (relative) => {
+    const absolute = relative ? path.join(brandRoot, ...relative.split('/')) : brandRoot;
+    let names;
+    try {
+      names = readdir(absolute);
+    } catch (error) {
+      recordError(relative, error);
+      return error.code !== 'ENOENT';
+    }
+    for (const name of names) {
+      const child = relative ? `${relative}/${name}` : name;
+      let stats;
+      try {
+        stats = lstat(path.join(absolute, name));
+      } catch (error) {
+        recordError(child, error);
+        continue;
+      }
+      if (stats.isSymbolicLink()) {
+        result.links.push({ relative: child });
+      } else if (stats.isFile()) {
+        const match = classifyHomePath(child, { imageMembers });
+        if (match) {
+          result.files.push({ relative: child, ...match, removal: homeArtifact(match.id).removal });
+        } else {
+          result.unknown.push({ relative: child, kind: 'file' });
+        }
+      } else if (stats.isDirectory()) {
+        // An undeclared folder is unknown as a whole: its contents cannot be ours, and an
+        // operator's large folder (a backup, a checkout) must not be walked to say so.
+        if (known.has(child)) {
+          if (walk(child)) result.directories.push({ relative: child });
+        } else {
+          result.unknown.push({ relative: child, kind: 'directory' });
+        }
+      } else {
+        result.unknown.push({ relative: child, kind: 'other' });
+      }
+    }
+    return true;
+  };
+  walk('');
+  for (const list of [result.files, result.unknown, result.links, result.errors]) list.sort(byRelative);
+  // Deepest first: the order in which a later empty-folder removal can take them down.
+  result.directories.sort((left, right) => (
+    right.relative.split('/').length - left.relative.split('/').length || byRelative(left, right)
+  ));
+  return result;
+}

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 };
+}