@lyupro/codex-bridge 0.6.8 → 0.6.10

package/cli/purge-live-runs.mjs

@@ -0,0 +1,98 @@
+/**
+ * Answers whether any recorded Codex run may still be executing, failing closed on anything unreadable.
+ *
+ * Plan_65 D22 item 5: purge removes the home image a live run executes from. The hook scanner's
+ * skipped read errors and fresh-heartbeat requirement cannot prove that image is unused: a hung
+ * run still holds it. Purge therefore keeps uncertainty visible and uses the single liveness judge.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
+import { runLiveness } from '../src/home/lib/meta/run-liveness.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+import { STOP_COMMAND } from '../src/home/lib/stop-contract.mjs';
+
+function recordError(unknown, file, error) {
+  unknown.push({ path: file, reason: error.code || error.message });
+}
+
+// ENOENT is the only proof of absence: a root never created holds no runs, and a project folder
+// pruned between the root listing and its own is gone too. Every other code stays a finding.
+function readEntries(directory, unknown) {
+  try {
+    return fs.readdirSync(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code !== 'ENOENT') recordError(unknown, directory, error);
+    return [];
+  }
+}
+
+function isDirectory(entry, file, unknown) {
+  if (entry.isDirectory()) return true;
+  if (!entry.isSymbolicLink()) return false;
+  try {
+    // Plan_65 D4 forbids deleting through links, not reading their run records.
+    return fs.statSync(file).isDirectory();
+  } catch (error) {
+    if (error.code !== 'ENOENT') recordError(unknown, file, error);
+    return false;
+  }
+}
+
+function inspectRun(runDir, identityOptions, blocked, unknown) {
+  const statusPath = path.join(runDir, 'status.json');
+  let status;
+  try {
+    status = readJsonFileSync(statusPath);
+  } catch (error) {
+    // Lifecycle step 10 writes status first; old folders without it are not recorded runs.
+    if (error.cause instanceof SyntaxError) {
+      unknown.push({ path: statusPath, reason: 'invalid JSON' });
+    } else if (error.code !== 'ENOENT') {
+      recordError(unknown, statusPath, error);
+    }
+    return;
+  }
+  if (!status || typeof status !== 'object' || Array.isArray(status)) {
+    unknown.push({ path: statusPath, reason: 'status.json is not a plain object' });
+    return;
+  }
+  if (status.state !== 'running') return;
+  try {
+    if (runLiveness({ ...identityOptions, runDir, status }).processMayBeAlive === true) {
+      blocked.push({
+        runDir,
+        agent: status.agent,
+        slug: status.slug,
+        stop: `${STOP_COMMAND} "${runDir}"`,
+      });
+    }
+  } catch (error) {
+    recordError(unknown, statusPath, error);
+  }
+}
+
+export function inspectLiveRuns({ root = runsRoot(), ...identityOptions } = {}) {
+  const blocked = [];
+  const unknown = [];
+  for (const project of readEntries(root, unknown)) {
+    const projectDir = path.join(root, project.name);
+    if (!isDirectory(project, projectDir, unknown)) continue;
+    for (const run of readEntries(projectDir, unknown)) {
+      const runDir = path.join(projectDir, run.name);
+      if (isDirectory(run, runDir, unknown)) inspectRun(runDir, identityOptions, blocked, unknown);
+    }
+  }
+  const verdict = blocked.length ? 'blocked' : unknown.length ? 'unknown' : 'clear';
+  return { verdict, blocked, unknown };
+}
+
+export function liveRunLines(result) {
+  if (result.verdict === 'clear') return [];
+  return [
+    ...result.blocked.map(({ runDir, stop }) => `Live run ${path.basename(runDir)}: ${stop}`),
+    ...result.unknown.map(({ path: file, reason }) =>
+      `Could not read ${file} (${reason}): purge cannot prove no run is live.`),
+  ];
+}
+

package/cli/purge-preflight.mjs

@@ -0,0 +1,103 @@
+/**
+ * Holds purge's one set of refusal checks: under a live ticket it asks both consents and mints
+ * the executor's authorization; for a dry run it only reports.
+ *
+ * Plan_65 D12 items 5-6 and D14 require one ordered check inside the lifecycle transaction:
+ * live runs, installation inventory, inventory consent, then separate data consent. The executor
+ * consumes its result instead of checking again, so permission cannot outlive or change its plan.
+ */
+import path from 'node:path';
+import { assertLiveTicket } from './lifecycle-transaction.mjs';
+import { askPurgeConsent } from './inventory-removal.mjs';
+import { inspectLiveRuns, liveRunLines } from './purge-live-runs.mjs';
+import { buildHomeRemovalPlan } from './home-removal-plan.mjs';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+
+const authorizations = new WeakMap();
+
+// D14 item 2: this is THE live-run step, reached only as the default liveRunCheck of
+// runPurgePreflight and diagnosePurge. Plan_74 replaces it alone with the admission gate.
+export function checkLiveRuns() {
+  return inspectLiveRuns();
+}
+
+function freezePlan(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) freezePlan(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+const refused = (line) => ({ verdict: 'refused', lines: [line] });
+
+export function planRefusals(plan, host) {
+  if (plan.homeRoot === 'error') {
+    return [`Could not read ${host.brandRoot}: purge cannot inventory the home.`];
+  }
+  if (plan.recordState === 'corrupt') {
+    return [`The installation record of ${host.brandRoot} is unreadable: purge cannot tell who uses this home.`];
+  }
+
+  const ownerKey = normalizeRepoPath(host.root);
+  const otherOwners = plan.recordState === 'valid'
+    ? Object.keys(plan.format2.owners).filter((root) => root !== ownerKey)
+    : [];
+  return otherOwners.map((root) => `${root} is recorded as using ${host.brandRoot}; uninstall it first.`);
+}
+
+export function purgeDataFiles(plan) {
+  return plan.rows.filter((row) => row.removal === 'purge-only' && row.action === 'remove')
+    .map((row) => row.relative).sort();
+}
+
+export async function diagnosePurge({ host, packageRoot, liveRunCheck = checkLiveRuns }) {
+  const liveRuns = await liveRunCheck();
+  const plan = await buildHomeRemovalPlan({
+    command: 'purge', host, packageRoot, imagePolicy: { remove: true, reason: 'purge' },
+  });
+  return {
+    refusals: [...liveRunLines(liveRuns), ...planRefusals(plan, host)], plan, dataFiles: purgeDataFiles(plan),
+  };
+}
+
+export async function runPurgePreflight({ host, ticket, packageRoot, options = {}, liveRunCheck = checkLiveRuns }) {
+  assertLiveTicket(ticket, host);
+  const liveRuns = await liveRunCheck();
+  if (liveRuns.verdict !== 'clear') return { verdict: 'refused', lines: liveRunLines(liveRuns) };
+
+  const plan = await buildHomeRemovalPlan({
+    command: 'purge', host, packageRoot, imagePolicy: { remove: true, reason: 'purge' },
+  });
+  const lines = planRefusals(plan, host);
+  if (lines.length) return { verdict: 'refused', lines };
+
+  const ownerKey = normalizeRepoPath(host.root);
+  const inventoryConsent = await askPurgeConsent(host, 'inventory', options);
+  if (inventoryConsent === 'cancel') return { verdict: 'cancelled' };
+  if (inventoryConsent === 'no') {
+    return refused(`Purge needs your confirmation that no other host uses ${host.brandRoot}.`);
+  }
+
+  const dataFiles = purgeDataFiles(plan);
+  const dataConsent = await askPurgeConsent(host, 'data', options, dataFiles);
+  if (dataConsent === 'cancel') return { verdict: 'cancelled' };
+  if (dataConsent === 'no') {
+    return refused(`Purge needs your consent to delete your data in ${host.brandRoot}.`);
+  }
+
+  freezePlan(plan);
+  const authorization = Object.freeze({});
+  authorizations.set(authorization, { home: path.resolve(host.brandRoot), ownerKey, ticket, plan });
+  return { verdict: 'authorized', plan, authorization };
+}
+
+export function consumePurgeAuthorization(authorization, host, plan) {
+  const entry = authorizations.get(authorization);
+  if (!entry) throw new Error('purge requires its preflight authorization (Plan_65 D12 item 6)');
+  // D14: every attempt consumes the capability, including a stale ticket or wrong plan/home.
+  authorizations.delete(authorization);
+  assertLiveTicket(entry.ticket, host);
+  if (path.resolve(host.brandRoot) !== entry.home) throw new Error('purge authorization belongs to a different home');
+  if (entry.plan !== plan) throw new Error('purge authorization was granted for a different plan');
+}

package/cli/read.mjs

@@ -1,12 +1,15 @@
 /** Renders a run's structured Codex transport as a readable event-by-event report. */
+import path from 'node:path';
+import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
 import { readEvents } from '../src/home/lib/meta/events.mjs';
+import { safeSlice } from '../src/home/lib/meta/paths.mjs';
 import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 import { resolveRunFolder } from './run-lookup.mjs';
 
 const result = (exitCode, output) => ({ exitCode, output });
 const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
 
-const inline = (value, max = 300) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+const inline = (value, max = 300) => safeSlice(String(value ?? '').replace(/\s+/g, ' ').trim(), max);
 
 function compactJson(value, max = 300) {
   let text;
@@ -91,6 +94,24 @@ export function read({ run, cwd = process.cwd(), runsRootPath = runsRoot() } = {
   // run from before the event stream existed has no file, while a run killed before the CLI
   // spoke has an empty one. Reporting both as "predates this change" would hide the second.
   if (!eventData.hasStream) {
+    let state;
+    try {
+      state = readJsonFileSync(path.join(lookup.runDir, 'status.json'))?.state;
+    } catch {
+      // The 2026-09-06 refusal needs its state; unreadable status keeps the legacy explanation.
+    }
+    if (state === 'aborted_pre_start') {
+      return result(
+        1,
+        `Run ${lookup.runDir} was refused before Codex started (state aborted_pre_start), so it has no events.jsonl.`,
+      );
+    }
+    if (state === 'running') {
+      return result(
+        1,
+        `Run ${lookup.runDir} has no events.jsonl yet: Codex has not started; repeat the command shortly.`,
+      );
+    }
     return result(1, `Run ${lookup.runDir} has no events.jsonl; it predates the event stream.`);
   }
   if (!eventData.hasEvents) {

package/cli/record-removal.mjs

@@ -0,0 +1,43 @@
+/**
+ * Removes files listed in an installation record through the home adapter, so uninstall and update
+ * cannot remove an unregistered path from the package home.
+ */
+import fs from 'node:fs/promises';
+import { createHomeWriter } from '../src/home/lib/home-write.mjs';
+import { recordTarget } from './install-record.mjs';
+import { claudeBoundary, removeEmptyParents, removeEmptyHomeParents } from './remove-layout.mjs';
+import { inspectSegments } from './link-segments.mjs';
+
+export function recordHomeWriter(host, files) {
+  const imageMembers = files.filter((entry) => entry.root === 'brand').map((entry) => entry.path);
+  return createHomeWriter({ root: host.brandRoot, imageMembers });
+}
+
+export async function removeRecordedFile(host, writer, entry) {
+  const target = recordTarget(host, entry);
+  if (entry.root === 'brand') {
+    // Plan_65 D4 item 4 covers unlink too: a real file can sit beneath a junction.
+    const finding = inspectSegments(target, host.brandRoot);
+    if (finding.kind !== 'clear' && finding.kind !== 'missing') return { kept: finding };
+    if (finding.kind === 'clear') {
+      try {
+        await writer.unlink('install-image', target);
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err;
+      }
+    }
+    // A file already gone still gets its emptied parents taken down: a repeated uninstall after a
+    // partial one must finish the folders the first run left. The segments were just checked, so a
+    // link the walk finds now is a race; it stops the walk, and the file's own outcome is reported.
+    await removeEmptyHomeParents(writer, 'install-image', target, host.brandRoot);
+  } else {
+    await removeOutside(writer, target);
+    await removeEmptyParents(target, claudeBoundary(host, target));
+  }
+  return { kept: null };
+}
+
+export async function removeOutside(writer, target) {
+  writer.assertOutside(target);
+  await fs.rm(target, { force: true });
+}

package/cli/removal-outcomes.mjs

@@ -0,0 +1,115 @@
+/**
+ * Turns home removal outcomes, or a plan for a dry run, into the lines and exit code the operator sees.
+ *
+ * Plan_65 D12 item 7 requires actual counts and named keeps: planned removal must not claim
+ * that edited image files disappeared, or confuse removing an owner with deleting its record.
+ */
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+
+const unsafeReason = (reason) => reason.startsWith('link') || reason.startsWith('unreadable');
+// An image file kept by content evidence is named; one kept by policy (another owner, an incomplete
+// inventory) is not — that would print ~90 lines the caller explains in one sentence.
+const EVIDENCE_KEEP = new Set(['changed', 'link']);
+const namedKeep = (entry) => unsafeReason(entry.reason) || entry.id === null
+  || (entry.id === 'install-image' && EVIDENCE_KEEP.has(entry.reason));
+const artifactsLine = () => `Run artifacts in ${runsRoot()} are outside uninstall and stay.`;
+
+function fileLines(files, host, dryRun) {
+  const lines = [];
+  const removing = dryRun ? 'remove' : 'removed';
+  const verb = dryRun ? 'Would remove' : 'Removed';
+  const removed = files.filter((entry) => entry.result === removing);
+  const images = removed.filter((entry) => entry.id === 'install-image').length;
+  const data = removed.length - images;
+  if (images > 0) lines.push(`${verb} ${images} image file(s) from ${host.brandRoot}.`);
+  if (data > 0) lines.push(`${verb} ${data} data file(s) from ${host.brandRoot}.`);
+  for (const entry of files) {
+    if ((entry.result === 'kept' || entry.result === 'blocked') && namedKeep(entry)) {
+      lines.push(`${dryRun ? 'Would leave' : 'Left'} brand/${entry.relative} (${entry.reason})`);
+    }
+  }
+  const retained = files.filter((entry) => entry.result === 'kept' && entry.reason === 'purge-only');
+  if (retained.length > 0) {
+    const paths = retained.map((entry) => entry.relative).sort().join(', ');
+    const location = `in ${host.brandRoot} for --purge: ${paths}`;
+    lines.push(`${dryRun ? 'Would keep' : 'Kept'} ${retained.length} operator file(s) ${location}`);
+  }
+  for (const entry of files) {
+    if (entry.result === 'failed') lines.push(`Could not remove brand/${entry.relative}: ${entry.reason}`);
+  }
+  return lines;
+}
+
+function recordLines(record, host) {
+  if (record.result === 'removed') return [`Removed the installation record of ${host.brandRoot}.`];
+  if (record.result === 'failed') return [`Could not remove brand/${record.relative}: ${record.reason}`];
+  if (record.result !== 'kept') return [];
+  if (record.reason === 'this host removed from the record') {
+    return [`Removed ${host.root} from the installation record of ${host.brandRoot}; the shared image stays.`];
+  }
+  if (record.reason === 'this host is still attached') {
+    return [`Kept ${host.root} in the installation record because its hooks could not be removed.`];
+  }
+  return [`Kept the installation record of ${host.brandRoot} (${record.reason}).`];
+}
+
+export function outcomeLines(outcomes, { host }) {
+  const files = outcomes.filter((entry) => entry.kind === 'file');
+  const record = outcomes.find((entry) => entry.kind === 'record');
+  const lines = fileLines(files, host, false);
+  if (record) lines.push(...recordLines(record, host));
+  for (const entry of outcomes.filter((candidate) => candidate.kind === 'directory')) {
+    if (entry.relative === '' && entry.result === 'removed') {
+      lines.push(`Removed ${host.brandRoot}.`);
+    } else if (entry.result === 'kept') {
+      lines.push(`Left brand/${entry.relative}/ (${entry.reason})`);
+    } else if (entry.result === 'failed') {
+      lines.push(`Could not remove brand/${entry.relative}/: ${entry.reason}`);
+    }
+  }
+  lines.push(artifactsLine());
+  return lines;
+}
+
+export function outcomeExitCode(outcomes) {
+  return outcomes.some((entry) => entry.result === 'blocked' || entry.result === 'failed'
+    || (entry.result === 'kept' && unsafeReason(entry.reason))) ? 1 : 0;
+}
+
+export function planExitCode(plan) {
+  return plan.blocked || plan.rows.some((row) => (row.action === 'keep' || row.action === 'blocked')
+    && unsafeReason(row.reason)) ? 1 : 0;
+}
+
+export function planLines(plan, { host, detached = true }) {
+  const files = plan.rows.map((row) => ({ ...row, result: row.action === 'keep' ? 'kept' : row.action }));
+  const lines = fileLines(files, host, true);
+  if (plan.record.dependsOnDetach && detached === false) {
+    lines.push(`Would keep ${host.root} in the installation record because its hooks could not be removed.`);
+  } else if (plan.record.operation === 'delete') {
+    lines.push(`Would remove the installation record of ${host.brandRoot}.`);
+  } else if (plan.record.operation === 'remove-current-owner') {
+    lines.push(`Would remove ${host.root} from the installation record of ${host.brandRoot}; the shared image stays.`);
+  } else if (plan.record.operation === 'retain') {
+    lines.push(`Would keep the installation record of ${host.brandRoot} (${plan.record.reason})`);
+  }
+  lines.push(artifactsLine());
+  return lines;
+}
+
+export function purgeDryRunLines({ refusals, plan, dataFiles }, { host }) {
+  if (plan.homeRoot === 'missing' && refusals.length === 0) {
+    return [`Nothing to purge: ${host.brandRoot} does not exist.`, artifactsLine()];
+  }
+  const lines = [];
+  if (refusals.length) lines.push('A real purge would refuse:', ...refusals.map((line) => `  ${line}`));
+  const question = `A real purge would ask two questions: whether any other host uses ${host.brandRoot}`;
+  lines.push(`${question}, and whether to delete your data in it.`);
+  if (dataFiles.length) lines.push(`Your data it would ask about: ${dataFiles.join(', ')}`);
+  lines.push('If you confirm both questions:', ...planLines(plan, { host }));
+  return lines;
+}
+
+export function purgeDryRunExitCode({ refusals, plan }) {
+  return refusals.length ? 1 : planExitCode(plan);
+}

package/cli/removal-plan.mjs

@@ -0,0 +1,187 @@
+/**
+ * Decides, from gathered facts, what happens to every file of the package home.
+ *
+ * Plan_65 D12 uses one plan for uninstall and purge: decisions precede any deletion,
+ * so edited images and entries the inspection could not read stay visible to the caller.
+ * The record has its own operation because removing one owner can preserve the shared record.
+ */
+import {
+  HOME_ARTIFACTS,
+  HOME_DIRECTORIES,
+  classifyHomePath,
+  homeArtifact,
+} from '../src/home/lib/home-registry.mjs';
+
+const byRelative = (left, right) => (
+  left.relative < right.relative ? -1 : left.relative > right.relative ? 1 : 0
+);
+
+// The record changes only after the host is detached (cli/uninstall.mjs, hostSide.detached), so
+// every operation that changes it carries that dependency and nothing else does.
+function recordOutcome(operation, reason, blocked = false) {
+  const dependsOnDetach = operation === 'delete' || operation === 'remove-current-owner';
+  return { operation, reason, dependsOnDetach, blocked };
+}
+
+// The command that asked for the plan. Not "mode": that word already meant six things in this
+// package, and a guard (tests/mode-is-not-a-name.test.mjs) keeps it from meaning a seventh.
+function assertCommand(command) {
+  if (command !== 'uninstall' && command !== 'purge') throw new TypeError(`Invalid removal command: ${command}`);
+}
+
+function metadata(relative, imageMembers) {
+  const match = classifyHomePath(relative, { imageMembers });
+  return match
+    ? { ...match, removal: homeArtifact(match.id).removal }
+    : { id: null, role: null, removal: null };
+}
+
+function fileDecision(file, command, imageEvidence, imagePolicy) {
+  if (file.id === 'install-image') {
+    if (!imagePolicy.remove) return { action: 'keep', reason: imagePolicy.reason };
+    if (file.role !== 'primary') return { action: 'remove', reason: imagePolicy.reason };
+    const evidence = imageEvidence.get(file.relative);
+    if (!evidence) throw new TypeError(`Missing image evidence for ${file.relative}`);
+    if (!['remove', 'keep', 'missing'].includes(evidence.verdict)) {
+      throw new TypeError(`Invalid image evidence for ${file.relative}`);
+    }
+    return {
+      action: evidence.verdict,
+      reason: evidence.verdict === 'remove' ? `evidence: ${evidence.reason}` : evidence.reason,
+    };
+  }
+  if (file.id === 'install-record') {
+    // D12 item 2 reserves the record operation for B16c; D8/D11 keep its lifecycle sides.
+    if (file.role === 'primary' || file.role === 'atomic-temporary') return null;
+    if (file.role === 'lock') return { action: 'keep', reason: 'lifecycle lock' };
+    if (file.role === 'clear-gate') return { action: 'keep', reason: 'clear queue' };
+  }
+  if (file.removal === 'purge-only') {
+    return command === 'purge'
+      ? { action: 'remove', reason: 'purge' }
+      : { action: 'keep', reason: 'purge-only' };
+  }
+  if (file.removal === 'protected') return { action: 'keep', reason: 'protected' };
+  throw new TypeError(`Unsupported home file classification for ${file.relative}`);
+}
+
+function ancestorDecision(relative, inspection) {
+  const isAncestor = (entry) => entry.relative === '' || relative.startsWith(`${entry.relative}/`);
+  // D12 item 1: a path hidden by an ancestor is uninspected, not absent.
+  for (const [entries, reason] of [
+    [inspection.links, 'link at'],
+    [inspection.errors, 'unreadable ancestor'],
+    [inspection.unknown, 'unknown ancestor'],
+  ]) {
+    const ancestor = entries.find(isAncestor);
+    if (ancestor) return { action: 'blocked', reason: `${reason} ${ancestor.relative}` };
+  }
+  return { action: 'missing', reason: 'missing' };
+}
+
+export function planHomeFiles({ command, inspection, imageMembers, imageEvidence, imagePolicy }) {
+  assertCommand(command);
+  if (inspection.root === 'missing') return { rows: [], blocked: false };
+  if (inspection.root === 'error') return { rows: [], blocked: true };
+  if (inspection.root !== 'present') throw new TypeError(`Invalid home root state: ${inspection.root}`);
+
+  const rowsByPath = new Map();
+  const add = (relative, classification, decision) => {
+    if (!rowsByPath.has(relative)) rowsByPath.set(relative, { relative, ...classification, ...decision });
+  };
+  for (const entry of inspection.links) {
+    add(entry.relative, metadata(entry.relative, imageMembers), { action: 'blocked', reason: 'link' });
+  }
+  for (const entry of inspection.errors) {
+    add(entry.relative, metadata(entry.relative, imageMembers), {
+      action: 'blocked', reason: `unreadable: ${entry.code}`,
+    });
+  }
+  for (const entry of inspection.unknown) {
+    add(entry.relative, { id: null, role: null, removal: null }, {
+      action: 'keep', reason: entry.kind === 'directory' ? 'unknown directory' : 'unknown',
+    });
+  }
+  for (const file of inspection.files) {
+    if (rowsByPath.has(file.relative)) continue;
+    const decision = fileDecision(file, command, imageEvidence, imagePolicy);
+    if (decision) add(file.relative, { id: file.id, role: file.role, removal: file.removal }, decision);
+  }
+
+  const expected = new Set(imageMembers);
+  for (const artifact of HOME_ARTIFACTS) {
+    if (artifact.id === 'install-image' || artifact.id === 'install-record') continue;
+    if (Array.isArray(artifact.primary)) {
+      for (const relative of artifact.primary) expected.add(relative);
+    }
+  }
+  const inspected = new Set([
+    ...inspection.files, ...inspection.links, ...inspection.errors,
+    ...inspection.unknown, ...inspection.directories,
+  ].map((entry) => entry.relative));
+  for (const relative of expected) {
+    if (!inspected.has(relative)) {
+      add(relative, metadata(relative, imageMembers), ancestorDecision(relative, inspection));
+    }
+  }
+  const rows = [...rowsByPath.values()].sort(byRelative);
+  return { rows, blocked: rows.some((row) => row.action === 'blocked') };
+}
+
+export function planRecordOperation({ command, recordState, format2, ownerKey, imagePolicy }) {
+  assertCommand(command);
+  if (!['missing', 'corrupt', 'valid'].includes(recordState)) {
+    throw new TypeError(`Invalid installation record state: ${recordState}`);
+  }
+  if (recordState === 'missing') {
+    return recordOutcome('none', 'no installation record');
+  }
+  // D12 item 4: an unreadable record blocks removal rather than becoming an absent record.
+  if (recordState === 'corrupt') {
+    return recordOutcome('retain', 'unreadable installation record', true);
+  }
+  if (command === 'purge' || imagePolicy.remove) {
+    return recordOutcome('delete', command === 'purge' ? 'purge' : 'last owner');
+  }
+  if (Object.keys(format2.owners).length === 0) {
+    return recordOutcome('retain', 'no host is recorded as using it');
+  }
+  if (Object.hasOwn(format2.owners, ownerKey)) {
+    return recordOutcome('remove-current-owner', imagePolicy.reason);
+  }
+  return recordOutcome('retain', 'not an owner of this home');
+}
+
+export function planHomeDirectories({ command, inspection, imageMembers, imagePolicy }) {
+  if (inspection.root !== 'present') return [];
+  const decide = (relative) => {
+    if (command === 'purge') return { relative, action: 'remove-if-empty', reason: 'purge' };
+    if (!imagePolicy.remove) return { relative, action: 'keep', reason: imagePolicy.reason };
+    const imageDirectory = relative === '' || (
+      !HOME_DIRECTORIES.includes(relative)
+      && imageMembers.some((member) => member.startsWith(`${relative}/`))
+    );
+    // D12 item 1: even image ancestors can only be removed once they are empty.
+    return imageDirectory
+      ? { relative, action: 'remove-if-empty', reason: 'image' }
+      : { relative, action: 'keep', reason: 'holds purge-only data' };
+  };
+  return [...inspection.directories.map((entry) => decide(entry.relative)), decide('')];
+}
+
+export function planHomeRemoval(facts) {
+  const files = planHomeFiles(facts);
+  const record = planRecordOperation(facts);
+  const directories = planHomeDirectories(facts);
+  const rowsByPath = new Map(files.rows.map((row) => [row.relative, row]));
+  for (const file of facts.inspection.files) {
+    if (file.id !== 'install-record' || file.role !== 'atomic-temporary' || rowsByPath.has(file.relative)) continue;
+    rowsByPath.set(file.relative, {
+      relative: file.relative, id: file.id, role: file.role, removal: file.removal,
+      action: record.operation === 'delete' ? 'remove' : 'keep',
+      reason: record.operation === 'delete' ? 'record deleted' : 'record in use',
+    });
+  }
+  const rows = [...rowsByPath.values()].sort(byRelative);
+  return { rows, directories, record, blocked: files.blocked || record.blocked };
+}

package/cli/remove-layout.mjs

@@ -1,6 +1,10 @@
-/** Removes emptied directories of an installed layout without walking out of the package's own. */
+/**
+ * Removes emptied directories of an installed layout without walking out of the package's own.
+ * Home folders use the adapter and link check (Plan_65 D3, D4 item 4); host folders keep the raw route.
+ */
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { inspectSegments } from './link-segments.mjs';
 
 /**
  * These four helpers existed as two copies — one in uninstall.mjs, one in update.mjs — and the
@@ -57,3 +61,38 @@ export function claudeBoundary(host, target) {
 export async function removeEmptyLayout(directory) {
   await removeEmpty(directory);
 }
+
+// The segment check runs before every rmdir, not once per walk: on Windows rmdir on a junction
+// removes the junction itself, and a folder above the target may be a link even when the target's
+// own folder is not. A folder already gone keeps the walk going — its parent may still be empty.
+export async function removeEmptyHomeParents(writer, id, target, homeRoot) {
+  const root = path.resolve(homeRoot);
+  let current = path.dirname(path.resolve(target));
+  for (;;) {
+    const relative = path.relative(root, current);
+    if (!relative || path.isAbsolute(relative) || relative === '..'
+      || relative.startsWith(`..${path.sep}`)) break;
+
+    const finding = inspectSegments(current, root);
+    if (finding.kind !== 'missing') {
+      if (finding.kind !== 'clear') return { kept: finding };
+      try {
+        if ((await fs.readdir(current)).length !== 0) break;
+        await writer.rmdir(id, current);
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+    }
+    current = path.dirname(current);
+  }
+  return { kept: null };
+}
+
+export async function removeEmptyHome(writer, id, homeRoot) {
+  // Plan_65 D4 item 1 trusts the root as written, including a deliberately relocated home.
+  try {
+    if ((await fs.readdir(homeRoot)).length === 0) await writer.rmdir(id, homeRoot);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}

package/cli/rules-owners.mjs

@@ -4,7 +4,8 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
 import { readJsonFile } from '../src/home/lib/json-file.mjs';
-import { withFileLock } from '../src/home/lib/file-lock.mjs';
+import { withOutsideFileLock } from '../src/home/lib/file-lock.mjs';
+import { createHomeWriter } from '../src/home/lib/home-write.mjs';
 export { isLockTaken } from '../src/home/lib/file-lock.mjs';
 
 export const RULES_REGISTRY_NAME = '.codex-bridge-rules.json';
@@ -76,7 +77,8 @@ function registryLockPath(host) {
 }
 
 async function withRegistryLock(host, action) {
-  return withFileLock(registryLockPath(host), action, { description: 'rules ownership registry' });
+  const writer = createHomeWriter({ root: host.brandRoot });
+  return withOutsideFileLock(writer, registryLockPath(host), action, { description: 'rules ownership registry' });
 }
 
 export async function readRulesRegistry(host) {