@lyupro/codex-bridge 0.6.8 → 0.6.10

package/cli/command-registry.mjs

@@ -0,0 +1,284 @@
+/**
+ * Lists commands and how each is invoked (Plan_71 D1, advice A1: registry-dispatch).
+ * model -h refused help and global help omitted its actions (2026-09-29) because
+ * dispatch and usage had separate sources. One registry keeps invocation and help together.
+ */
+import { diagnose, renderDoctor } from './doctor.mjs';
+import { probeContract } from './probe-contract.mjs';
+import { resolveProbeTarget } from './probe-target.mjs';
+import { brandStateDir } from '../src/home/lib/brand-home.mjs';
+import { hook } from './hook.mjs';
+import { resolveHost } from './hosts.mjs';
+import { install } from './install.mjs';
+import { model } from './model.mjs';
+import { projects } from './projects.mjs';
+import { read } from './read.mjs';
+import { runCodex } from './run-launcher.mjs';
+import { permissions } from './permissions.mjs';
+import { prune } from './prune.mjs';
+import { stop } from './stop.mjs';
+import { unlock } from './unlock.mjs';
+import { uninstall } from './uninstall.mjs';
+import { purge } from './uninstall-purge.mjs';
+import { update } from './update.mjs';
+
+export function commandOptions(command, argv) {
+  const options = {};
+  const booleanFlags = command === 'install' || command === 'update' ? new Set(['--dry-run', '--force'])
+    : command === 'uninstall' ? new Set(['--dry-run', '--purge'])
+      : command === 'doctor' ? new Set(['--probe-contract']) : new Set();
+  const flagNames = new Map([
+    ['--dry-run', 'dryRun'],
+    ['--purge', 'purge'],
+    ['--force', 'force'],
+    ['--probe-contract', 'probeContract'],
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (booleanFlags.has(arg)) {
+      options[flagNames.get(arg)] = true;
+      continue;
+    }
+    if (arg !== '--scope' && arg !== '--host' && !(command === 'doctor' && arg === '--probe-executable')) throw new Error(`unknown ${command} option "${arg}"`);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
+    options[arg === '--scope' ? 'scope' : arg === '--host' ? 'host' : 'probeExecutable'] = value;
+    index += 1;
+  }
+  return options;
+}
+
+export const COMMANDS = [
+  {
+    name: 'install',
+    summary: 'Install codex-bridge into the selected Claude Code host',
+    usage: ['codex-bridge install [--scope user|project] [--host <path>] [--dry-run] [--force]'],
+    section: 'public',
+    async handler(argv, io) {
+      const options = commandOptions('install', argv);
+      const host = resolveHost(options);
+      const result = await install({ host, dryRun: options.dryRun, force: options.force });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'update',
+    summary: 'Update a recorded codex-bridge installation',
+    usage: ['codex-bridge update [--scope user|project] [--host <path>] [--dry-run] [--force]'],
+    section: 'public',
+    async handler(argv, io) {
+      const options = commandOptions('update', argv);
+      const host = resolveHost(options);
+      const result = await update({ host, dryRun: options.dryRun, force: options.force });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'permissions',
+    summary: 'Show, add, or remove optional shell permission rules',
+    usage: ['codex-bridge permissions [add|remove] [--scope user|project] [--host <path>]'],
+    section: 'public',
+    actions: {
+      add: {
+        summary: 'Add optional shell permission rules',
+        usage: ['codex-bridge permissions add [--scope user|project] [--host <path>]'],
+      },
+      remove: {
+        summary: 'Remove optional shell permission rules',
+        usage: ['codex-bridge permissions remove [--scope user|project] [--host <path>]'],
+      },
+    },
+    async handler(argv, io) {
+      let action;
+      let optionArgs = argv;
+      if (argv[0] && !argv[0].startsWith('-')) {
+        action = argv[0];
+        optionArgs = argv.slice(1);
+      }
+      if (action && !['add', 'remove'].includes(action)) {
+        throw new Error(`unknown permissions action "${action}"`);
+      }
+      const options = commandOptions('permissions', optionArgs);
+      const host = resolveHost(options);
+      const result = await permissions({ host, action });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'uninstall',
+    summary: 'Remove installed files while preserving run artifacts',
+    usage: ['codex-bridge uninstall [--scope user|project] [--host <path>] [--dry-run] [--purge]'],
+    section: 'public',
+    async handler(argv, io) {
+      const options = commandOptions('uninstall', argv);
+      const host = resolveHost(options);
+      const result = options.purge
+        ? await purge({ host, dryRun: options.dryRun })
+        : await uninstall({ host, dryRun: options.dryRun });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'doctor',
+    summary: 'Diagnose the selected Claude Code host (--probe-contract measures on a live host)',
+    usage: ['codex-bridge doctor [--scope user|project] [--host <path>] [--probe-contract] [--probe-executable <path>]'],
+    section: 'public',
+    async handler(argv, io) {
+      const options = commandOptions('doctor', argv);
+      if (options.probeExecutable && !options.probeContract) throw new Error('--probe-executable requires --probe-contract');
+      const host = resolveHost(options);
+      // The probe runs BEFORE the diagnosis so the `hostContract` line below carries the verdict just
+      // measured. Printing the diagnosis first and the measurement after would answer one question
+      // twice in one output, with the older answer on top (Plan_52 D25).
+      let probe = null;
+      if (options.probeContract) {
+        const target = resolveProbeTarget({ stateDir: brandStateDir(host.brandRoot), executable: options.probeExecutable });
+        if (!target.error) io.log(`probe: target ${target.version} at ${target.executable} (${target.source})`);
+        probe = await probeContract({ host, target });
+        io.log(`probe: ${probe.message}`);
+        for (const [name, verdict] of Object.entries(probe.dispatcher ?? {})) {
+          io.log(`probe: ${name} ${verdict.result} — ${verdict.detail}`);
+        }
+      }
+      const result = await diagnose({ host });
+      io.log(renderDoctor(result));
+      // An inconclusive probe wrote nothing and measured nothing; exiting 0 would let a failed
+      // measurement pass silently in a script (Plan_52 D26).
+      return probe && probe.state === 'inconclusive' ? 2 : result.exitCode;
+    },
+  },
+  {
+    name: 'run',
+    summary: 'Start or attach to a delegated Codex run',
+    usage: ['codex-bridge run <runner options> --task-file <path>'],
+    section: 'public',
+    async handler(argv, io) {
+      return runCodex(argv);
+    },
+  },
+  {
+    name: 'model',
+    summary: 'Show, set or list the models delegated roles run on',
+    usage: ['codex-bridge model'],
+    section: 'public',
+    actions: {
+      list: {
+        summary: 'List the live model catalogue',
+        usage: ['codex-bridge model list'],
+      },
+      set: {
+        summary: 'Set the model and optional effort for a role',
+        usage: [
+          'codex-bridge model set <role> <model> [effort]',
+          'codex-bridge model set <role> --model <model> [--effort <effort>]',
+        ],
+      },
+      unset: {
+        summary: 'Unset the model override for a role',
+        usage: ['codex-bridge model unset <role>'],
+      },
+      speed: {
+        summary: 'Preview, pin (confirm) or unpin the accelerated speed tier of a role',
+        usage: [
+          'codex-bridge model speed <role> <tier>',
+          'codex-bridge model speed <role> <tier> confirm',
+          'codex-bridge model speed <role> unset',
+        ],
+      },
+    },
+    async handler(argv, io) {
+      const result = await model(argv);
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'projects',
+    summary: 'List projects or runs from the run store',
+    usage: ['codex-bridge projects [<name>] [--json]'],
+    section: 'public',
+    async handler(argv, io) {
+      const result = projects(argv);
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'prune',
+    summary: 'Remove archived transport, or purge selected run folders',
+    usage: [
+      'codex-bridge prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]',
+      'codex-bridge prune --all-projects [--older-than <age>] [-f] [--json]',
+    ],
+    section: 'public',
+    async handler(argv, io) {
+      const result = await prune(argv);
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'unlock',
+    summary: 'Close running records whose runner is gone, or show the lifecycle lock',
+    usage: ['codex-bridge unlock [<project>|--all]', 'codex-bridge unlock --lifecycle [--clear]'],
+    section: 'public',
+    async handler(argv, io) {
+      const result = await unlock(argv);
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'read',
+    summary: "Render a run's structured event stream",
+    usage: ['codex-bridge read <run>'],
+    section: 'public',
+    async handler(argv, io) {
+      if (argv.length !== 1) {
+        io.error('codex-bridge read requires exactly one run folder (full path or bare name).');
+        return 2;
+      }
+      const result = read({ run: argv[0] });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'stop',
+    summary: 'Stop a running Codex run and record FAIL',
+    usage: ['codex-bridge stop <run>'],
+    section: 'public',
+    async handler(argv, io) {
+      if (argv.length !== 1) {
+        io.error('codex-bridge stop requires exactly one run folder (full path or bare name).');
+        return 2;
+      }
+      const result = await stop({ run: argv[0] });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'hook',
+    summary: 'Dispatch a registered guard with stdin unchanged',
+    usage: ['codex-bridge hook <name>'],
+    section: 'machine',
+    async handler(argv, io) {
+      return hook(argv, io);
+    },
+  },
+  {
+    name: 'sweep',
+    summary: 'Renamed to codex-bridge unlock',
+    usage: [],
+    section: 'renamed',
+    async handler(argv, io) {
+      io.error('codex-bridge sweep was renamed to codex-bridge unlock; use the new command.');
+      return 2;
+    },
+  },
+];

package/cli/copy.mjs

@@ -2,6 +2,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { classifyHomePath } from '../src/home/lib/home-registry.mjs';
+import { createHomeWriter } from '../src/home/lib/home-write.mjs';
 import { replacePlaceholders } from './manifest.mjs';
 
 export async function plannedContent(item, installationRoot) {
@@ -25,15 +27,50 @@ export async function targetMatches(item, installationRoot) {
   }
 }
 
-export async function copyPlannedFile(item, installationRoot) {
+/**
+ * Plan_65 D3: the install image is one registry entry whose exact members come from the plan, and
+ * seeds keep their own ids. One place decides which id a planned item writes under, so the
+ * installer and every fixture that copies a plan cannot disagree about it.
+ */
+export function planHomeWriter(brandRoot, plan) {
+  const imageMembers = plan.filter((item) => item.root === 'brand').map((item) => item.relativeToRoot);
+  const writer = createHomeWriter({ root: brandRoot, imageMembers });
+  const idFor = (item) => {
+    if (item.root !== 'brand') return undefined;
+    const id = classifyHomePath(item.relativeToRoot, { imageMembers })?.id;
+    if (!id) throw new Error(`brand install plan item is not a registered home artifact: ${item.relativeToRoot}`);
+    return id;
+  };
+  return { writer, idFor };
+}
+
+export async function copyPlannedFile(item, installationRoot, options = {}) {
+  const { writer, id } = options ?? {};
+  if (!writer) throw new Error('copyPlannedFile requires a home writer');
+  if (id !== undefined) await writer.assertArtifact(id, item.target);
+  else await writer.assertOutside(item.target);
+
   const content = await plannedContent(item, installationRoot);
-  await fs.mkdir(path.dirname(item.target), { recursive: true });
+  const operations = id === undefined
+    ? {
+      mkdir: (...args) => fs.mkdir(...args),
+      writeFile: (...args) => fs.writeFile(...args),
+      rename: (...args) => fs.rename(...args),
+      cleanup: (temporary) => fs.rm(temporary, { force: true }),
+    }
+    : {
+      mkdir: (...args) => writer.mkdir(id, ...args),
+      writeFile: (...args) => writer.writeFile(id, ...args),
+      rename: (...args) => writer.rename(id, ...args),
+      cleanup: (temporary) => writer.unlink(id, temporary),
+    };
+  await operations.mkdir(path.dirname(item.target), { recursive: true });
   const temporary = path.join(path.dirname(item.target), `.${path.basename(item.target)}.${randomUUID()}.tmp`);
   try {
-    await fs.writeFile(temporary, content, { flag: 'wx' });
-    await fs.rename(temporary, item.target);
+    await operations.writeFile(temporary, content, { flag: 'wx' });
+    await operations.rename(temporary, item.target);
   } catch (err) {
-    await fs.rm(temporary, { force: true }).catch(() => {});
+    await Promise.resolve().then(() => operations.cleanup(temporary)).catch(() => {});
     throw err;
   }
 }

package/cli/dispatcher-contract-record.mjs

@@ -6,7 +6,8 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { writeJsonAtomic } from '../src/home/lib/atomic-json.mjs';
+import { writeHomeJsonAtomic } from '../src/home/lib/atomic-json.mjs';
+import { stateDirWriter } from '../src/home/lib/home-write.mjs';
 import { parseJsonText } from '../src/home/lib/json-file.mjs';
 import { DISPATCHER_CONTRACTS } from './dispatcher-contract.mjs';
 
@@ -46,6 +47,6 @@ export function writeDispatcherContract({ stateDir, version, verdicts, now = new
     }
   }
   const record = { hosts: { ...(previous?.hosts ?? {}), [version]: { contracts } } };
-  writeJsonAtomic(file, record);
+  writeHomeJsonAtomic(stateDirWriter(stateDir), 'dispatcher-contract', file, record);
   return record;
 }

package/cli/doctor-host-side.mjs

@@ -0,0 +1,110 @@
+/**
+ * Reports host marks separately from home ownership (Plan_65 D10 item 6): WHAT lies in a host
+ * comes from its marks, while WHO uses the home comes only from its owner rows. A single
+ * "installation: not installed" line hid a host that plainly carried our agents and hooks, and it
+ * never said which hosts the home record names or whether its inventory is complete.
+ * Owners in sync keeps lagging hosts visible because install/update named them only once (Plan_65 D11 item 3).
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+import { check } from './doctor-format.mjs';
+import { hasPackageMarks } from './host-inspection.mjs';
+import { imageFingerprint, isFormat2 } from './install-owners.mjs';
+
+// Format 1 is not migrated here: asFormat2 would record this host as the owner, and doctor only reads.
+export function ownerEntry(rawRecord, host) {
+  if (rawRecord === null || !isFormat2(rawRecord)) return null;
+  return rawRecord.owners[normalizeRepoPath(host.root)] ?? null;
+}
+
+export function hostSideCheck(host, inspection) {
+  if (inspection.settingsError) {
+    return check('host files', 'fail', `settings could not be read: ${inspection.settingsError}`);
+  }
+  if (!hasPackageMarks(inspection)) {
+    return check('host files', 'warn', `no codex-bridge files or hooks in ${host.root}`);
+  }
+
+  const kept = inspection.files.filter((file) => file.disposition === 'keep'
+    && ['changed', 'unknown'].includes(file.reason));
+  const counts = `${inspection.files.length} package file(s) and ${inspection.hooks.length} own hook(s) in ${host.root}`;
+  const keptText = kept.map((file) => `${file.relativeToHost} (${file.reason})`).join(', ');
+  return kept.length
+    ? check('host files', 'warn', `${counts}; kept by uninstall: ${keptText}`)
+    : check('host files', 'ok', counts);
+}
+
+async function homeImageExists(host) {
+  try {
+    await fs.access(path.join(host.brandRoot, 'lib'));
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function homeOwnersCheck(host, rawRecord, inspection) {
+  if (rawRecord === null) {
+    return await homeImageExists(host)
+      ? check('home owners', 'warn', `no installation record in ${host.brandRoot}; the image has no record`)
+      : check('home owners', 'ok', `no installation record in ${host.brandRoot}`);
+  }
+  if (!isFormat2(rawRecord)) {
+    return check(
+      'home owners',
+      'warn',
+      'old record format; the hosts using this home are unknown until the next install or update',
+    );
+  }
+
+  const roots = Object.values(rawRecord.owners).map((owner) => owner.root);
+  const inventoryComplete = rawRecord.inventory === 'complete' && rawRecord.legacy === undefined;
+  const hostRecorded = Object.hasOwn(rawRecord.owners, normalizeRepoPath(host.root));
+  const unrecordedMarks = hasPackageMarks(inspection) && !hostRecorded;
+  const parts = [
+    `recorded: ${roots.length ? roots.join(', ') : 'none'}`,
+    inventoryComplete ? 'inventory complete' : 'inventory incomplete: an old record did not name every host',
+    ...(unrecordedMarks
+      ? [`${host.root} has package files or hooks but is not recorded: run codex-bridge install --host "${host.root}"`]
+      : []),
+  ];
+  return check('home owners', inventoryComplete && !unrecordedMarks ? 'ok' : 'warn', parts.join('; '));
+}
+
+export function ownersInSyncCheck(rawRecord) {
+  if (rawRecord === null || !isFormat2(rawRecord)) {
+    return check('owners in sync', 'ok', 'no format-2 record; nothing to compare');
+  }
+
+  const owners = Object.values(rawRecord.owners);
+  const inventoryComplete = rawRecord.inventory === 'complete' && rawRecord.legacy === undefined;
+  if (!owners.length) {
+    return check('owners in sync', 'warn',
+      `no recorded owners${inventoryComplete ? '' : '; inventory incomplete'}`);
+  }
+
+  const fingerprint = imageFingerprint(rawRecord.image);
+  const parts = [];
+  const unstamped = [];
+  for (const owner of owners) {
+    if (owner.imageFingerprint != null) {
+      if (owner.imageFingerprint === fingerprint) continue;
+    } else if (owner.version === rawRecord.image.version) {
+      unstamped.push(owner.root);
+      continue;
+    }
+    // The same version on both sides is the clone case the stamp exists for; say so instead of "0.6.9, image 0.6.9".
+    const why = owner.version === rawRecord.image.version
+      ? `verified against an earlier image of ${owner.version}`
+      : `recorded ${owner.version}, image ${rawRecord.image.version}`;
+    parts.push(`${owner.root} (${why}): run codex-bridge update --host "${owner.root}"`);
+  }
+  if (unstamped.length) parts.push(`not yet verified by image fingerprint: ${unstamped.join(', ')}`);
+  if (!inventoryComplete) parts.push('inventory incomplete');
+  const warning = parts.length > 0;
+  if (!warning) parts.push(`all ${owners.length} owner(s) verified against the current image`);
+  return check('owners in sync', warning ? 'warn' : 'ok',
+    `${parts.join('; ')} (recorded verification; host files and reachability not inspected)`);
+}

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,
@@ -108,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) {

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