@lyupro/codex-bridge 0.6.8 → 0.6.10

package/cli/install-owners.mjs

@@ -0,0 +1,244 @@
+/**
+ * Keeps one installation record for a package home that several hosts share: one image part, and
+ * one owner per host root (format 2, Plan_65 D5).
+ *
+ * The format-1 record was written whole by whichever host installed last and named no host at all:
+ * `install --host A`, then `install --host B` into one home left B's record alone (reproduced
+ * 2026-09-25), and uninstalling either would have removed the image under the other. Owners are
+ * keyed by the lexically normalized host root, never a resolved one. An old record migrates with
+ * only the migrating host as owner and the inventory marked incomplete (D6): it never recorded who
+ * else used the home, and the last writer is not proof of being the only one.
+ */
+import { createHash } from 'node:crypto';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+import {
+  fileEntry,
+  INSTALL_METHOD_COPY,
+  INSTALL_METHOD_KEY,
+  validateInstallRecord,
+} from './install-record.mjs';
+
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+export function isFormat2(parsed) {
+  return isObject(parsed) && parsed.format === 2;
+}
+
+export function imageFingerprint(image) {
+  const brand = image.fingerprints?.brand;
+  if (brand === undefined) return null;
+  const canonical = Object.keys(brand).sort()
+    .map((path) => `${path}\0${brand[path]}\n`).join('');
+  return createHash('sha256').update(canonical).digest('hex');
+}
+
+export function ownImageStampCurrent(rawRecord, host) {
+  if (!isFormat2(rawRecord)) return false;
+  const owner = rawRecord.owners?.[normalizeRepoPath(host.root)];
+  if (!owner) return false;
+  const fingerprint = imageFingerprint(rawRecord.image);
+  return fingerprint !== null && owner.imageFingerprint === fingerprint;
+}
+
+function filesFor(record, root) {
+  return record.files.map(fileEntry).filter((file) => file.root === root)
+    .map((file) => ({ root, path: file.path }));
+}
+
+function fingerprintsFor(record, root, files) {
+  if (record.fingerprints === undefined) return undefined;
+  const values = record.fingerprints[root]
+    ?? (root === 'claude' ? record.fingerprints : undefined)
+    ?? {};
+  const selected = {};
+  for (const file of files) {
+    if (values[file.path] !== undefined) selected[file.path] = values[file.path];
+  }
+  return { [root]: selected };
+}
+
+function ownerFrom(record, host) {
+  const files = filesFor(record, 'claude');
+  const fingerprints = fingerprintsFor(record, 'claude', files);
+  return {
+    root: host.root,
+    scope: host.scope,
+    version: record.version,
+    installedAt: record.installedAt,
+    files,
+    ...(fingerprints === undefined ? {} : { fingerprints }),
+    ...(record.rules === undefined ? {} : { rules: record.rules }),
+    hooks: (record.hooks ?? (record.hook === undefined ? [] : [record.hook])).map((hook) => (
+      hook.root ? { ...hook } : { ...hook, root: 'claude' }
+    )),
+  };
+}
+
+function imageFrom(record) {
+  const files = filesFor(record, 'brand');
+  const fingerprints = fingerprintsFor(record, 'brand', files);
+  return {
+    version: record.version,
+    installedAt: record.installedAt,
+    files,
+    ...(fingerprints === undefined ? {} : { fingerprints }),
+  };
+}
+
+function mergeFingerprints(image, owner) {
+  if (image.fingerprints === undefined && owner.fingerprints === undefined) return undefined;
+  return { ...(image.fingerprints ?? {}), ...(owner.fingerprints ?? {}) };
+}
+
+export function ownerView(record2, host) {
+  if (!isFormat2(record2)) return null;
+  const key = normalizeRepoPath(host.root);
+  const owner = record2.owners?.[key];
+  if (!owner) return null;
+  const view = {
+    name: record2.name,
+    [INSTALL_METHOD_KEY]: record2[INSTALL_METHOD_KEY],
+    version: owner.version,
+    installedAt: owner.installedAt,
+    files: [...record2.image.files, ...owner.files],
+    hooks: owner.hooks,
+  };
+  const fingerprints = mergeFingerprints(record2.image, owner);
+  if (fingerprints !== undefined) view.fingerprints = fingerprints;
+  if (owner.rules !== undefined) view.rules = owner.rules;
+  return view;
+}
+
+/** Decides whether the departing owner may remove the shared image using only inventory facts. */
+export function imageRemoval(record2, host) {
+  validateFormat2(record2);
+  const key = normalizeRepoPath(host.root);
+  const isOwner = Object.hasOwn(record2.owners, key);
+  const remaining = Object.keys(record2.owners).length - Number(isOwner);
+  if (remaining > 0) return { removeImage: false, reason: 'other-owners', remaining };
+  if (record2.legacy !== undefined || record2.inventory !== 'complete') {
+    return { removeImage: false, reason: 'incomplete-inventory' };
+  }
+  if (isOwner) return { removeImage: true };
+  return { removeImage: false, reason: 'incomplete-inventory' };
+}
+
+/** Removes one host from the shared inventory while preserving its image and inventory facts. */
+export function withoutOwner(record2, host) {
+  validateFormat2(record2);
+  const key = normalizeRepoPath(host.root);
+  if (!Object.hasOwn(record2.owners, key)) return record2;
+  const owners = { ...record2.owners };
+  delete owners[key];
+  return validateFormat2({ ...record2, owners });
+}
+
+export function withOwner(existing, host, record1, options) {
+  validateInstallRecord(record1);
+  const key = normalizeRepoPath(host.root);
+  const image = imageFrom(record1);
+  const owner = ownerFrom(record1, host);
+  const fingerprint = imageFingerprint(image);
+  if (fingerprint !== null) owner.imageFingerprint = fingerprint;
+
+  if (existing === null) {
+    // Only an explicit false proves no earlier installation used this home; unknown is incomplete.
+    const confirmedNoPriorImage = options?.homeHadImage === false;
+    const created = {
+      format: 2,
+      name: record1.name,
+      [INSTALL_METHOD_KEY]: record1[INSTALL_METHOD_KEY],
+      image,
+      inventory: options?.inventory === 'complete' || confirmedNoPriorImage ? 'complete' : 'incomplete',
+      owners: { [key]: owner },
+    };
+    return validateFormat2(created);
+  }
+
+  let previous;
+  if (isFormat2(existing)) {
+    previous = validateFormat2(existing);
+  } else {
+    if (Object.hasOwn(existing ?? {}, 'format')) {
+      throw new Error(`unknown installation record format: ${existing.format}`);
+    }
+    validateInstallRecord(existing);
+    previous = {
+      format: 2,
+      name: record1.name,
+      [INSTALL_METHOD_KEY]: record1[INSTALL_METHOD_KEY],
+      image,
+      inventory: 'incomplete',
+      owners: {},
+      legacy: existing,
+    };
+  }
+
+  // D9: the operator's "this host is the only one" answers what the legacy record could not tell,
+  // so the old record goes in the same publish instead of lingering as a second opinion.
+  const { legacy: _answered, ...withoutLegacy } = previous;
+  const base = options?.inventory === 'complete' ? { ...withoutLegacy, inventory: 'complete' } : previous;
+  const next = {
+    ...base,
+    name: record1.name,
+    [INSTALL_METHOD_KEY]: record1[INSTALL_METHOD_KEY],
+    image,
+    owners: { ...previous.owners, [key]: owner },
+  };
+  return validateFormat2(next);
+}
+
+function validatePartition(part, root, label) {
+  if (!isObject(part)) throw new Error(`installation record ${label} must be an object`);
+  if (!Array.isArray(part.files)) throw new Error(`installation record ${label} files must be a list`);
+  if (part.files.some((file) => fileEntry(file)?.root !== root)) {
+    throw new Error(`installation record ${label} files must use the ${root} root`);
+  }
+  if (part.fingerprints !== undefined) {
+    if (!isObject(part.fingerprints)
+      || Object.keys(part.fingerprints).some((key) => key !== root)) {
+      throw new Error(`installation record ${label} fingerprints must use the ${root} root`);
+    }
+  }
+}
+
+export function validateFormat2(parsed) {
+  if (!isObject(parsed) || parsed.format !== 2) {
+    throw new Error('installation record format must be 2');
+  }
+  if (parsed.inventory !== 'complete' && parsed.inventory !== 'incomplete') {
+    throw new Error('installation record inventory must be complete or incomplete');
+  }
+  if (!isObject(parsed.owners)) throw new Error('installation record owners must be an object');
+  if (Object.keys(parsed.owners).length === 0 && parsed.inventory !== 'incomplete') {
+    throw new Error('installation record with no owners must have an incomplete inventory');
+  }
+  validatePartition(parsed.image, 'brand', 'image');
+
+  for (const [key, owner] of Object.entries(parsed.owners)) {
+    if (!isObject(owner) || typeof owner.root !== 'string' || !owner.root) {
+      throw new Error(`installation record owner ${key} must have a root`);
+    }
+    if (normalizeRepoPath(owner.root) !== key) {
+      throw new Error(`installation record owner root must normalize to its key: ${key}`);
+    }
+    if (typeof owner.scope !== 'string' || !owner.scope) {
+      throw new Error(`installation record owner ${key} has invalid scope`);
+    }
+    if (Object.hasOwn(owner, 'imageFingerprint')
+      && (typeof owner.imageFingerprint !== 'string' || !/^[a-f0-9]{64}$/.test(owner.imageFingerprint))) {
+      throw new Error(`installation record owner ${key} has invalid imageFingerprint`);
+    }
+    validatePartition(owner, 'claude', `owner ${key}`);
+    const view = ownerView(parsed, { root: owner.root });
+    validateInstallRecord(view);
+    validateInstallRecord({ ...view, version: parsed.image.version, installedAt: parsed.image.installedAt });
+  }
+
+  if (typeof parsed.name !== 'string' || !parsed.name) throw new Error('installation record has invalid name');
+  if (parsed.legacy !== undefined) validateInstallRecord(parsed.legacy);
+  if (parsed[INSTALL_METHOD_KEY] !== INSTALL_METHOD_COPY) {
+    throw new Error(`installation record ${INSTALL_METHOD_KEY} must be ${INSTALL_METHOD_COPY}`);
+  }
+  return parsed;
+}

package/cli/install-record.mjs

@@ -1,8 +1,10 @@
 /** Reads, validates, and writes the installation record shared by installer commands. */
-import fs from 'node:fs/promises';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { createHomeWriter } from '../src/home/lib/home-write.mjs';
 import { readJsonFile } from '../src/home/lib/json-file.mjs';
 import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
+import { isFormat2, ownerView, validateFormat2, withOwner, withoutOwner } from './install-owners.mjs';
 
 /**
  * The record's own spelling of the field saying how the package was installed, and its one value.
@@ -244,6 +246,12 @@ function withoutSeededFiles(host, record) {
   return record;
 }
 
+// Plan_65 H4 removes image files while preserving the seeded operator data through the shared filter.
+export function imageMembers(record2, host) {
+  const image = withoutSeededFiles(host, { files: [...record2.image.files] });
+  return image.files;
+}
+
 async function readAt(recordPath) {
   try {
     return await readJsonFile(recordPath);
@@ -264,18 +272,72 @@ export function legacyInstallRecordPath(host) {
   return path.join(host.legacyAgentsDir, LEGACY_INSTALL_RECORD_NAME);
 }
 
+/**
+ * Reads the view owned by this host. Plan_65 D10 item 5: format-2 legacy only marks an
+ * incomplete inventory; it is never another host's view, enrollment template, fingerprint base,
+ * or source of createdGroup. Format-1 and older per-host records remain readable for migration.
+ */
 export async function readInstallRecord(host) {
-  const parsed = await readAt(installRecordPath(host));
-  const legacy = parsed === null ? await readAt(legacyInstallRecordPath(host)) : null;
-  if (parsed === null && legacy === null) return null;
-  return withoutSeededFiles(host, normalizeInstallRecord(parsed ?? legacy));
+  const parsed = await readInstallRecordFile(host);
+  if (parsed !== null) {
+    if (isFormat2(parsed)) {
+      validateFormat2(parsed);
+      const owned = ownerView(parsed, host);
+      return owned === null ? null : withoutSeededFiles(host, normalizeInstallRecord(owned));
+    }
+    return withoutSeededFiles(host, normalizeInstallRecord(parsed));
+  }
+  const legacy = await readAt(legacyInstallRecordPath(host));
+  return legacy === null ? null : withoutSeededFiles(host, normalizeInstallRecord(legacy));
 }
 
-export async function writeInstallRecord(host, record) {
-  const normalized = normalizeInstallRecord(record);
+export async function readInstallRecordFile(host) {
+  return readAt(installRecordPath(host));
+}
+
+async function publishInstallRecord(host, next) {
   const target = installRecordPath(host);
-  await fs.mkdir(path.dirname(target), { recursive: true });
-  await fs.writeFile(target, `${JSON.stringify(normalized, null, 2)}\n`);
+  const writer = createHomeWriter({ root: host.brandRoot });
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  writer.assertArtifact('install-record', target);
+  writer.assertArtifact('install-record', temporary);
+  await writer.mkdir('install-record', path.dirname(target), { recursive: true });
+  await writer.writeFile('install-record', temporary, `${JSON.stringify(next, null, 2)}\n`);
+  await writer.rename('install-record', temporary, target);
+}
+
+/**
+ * Publishes the record whole through a temporary and a rename: a direct write left a half-written
+ * record for every host sharing the home if the process died mid-write (advice A3, risk r3).
+ * `homeHadImage: false` is the caller's proof that no earlier installation used this home; without
+ * it a new record starts with an incomplete inventory (D6).
+ * inventory: 'complete' records the operator's D9 confirmation and drops a migrated legacy record
+ * in the same publish.
+ */
+export async function writeInstallRecord(host, record, { homeHadImage, inventory } = {}) {
+  const normalized = normalizeInstallRecord(record);
+  const next = withOwner(await readAt(installRecordPath(host)), host, normalized, { homeHadImage, inventory });
+  await publishInstallRecord(host, next);
+}
+
+/**
+ * Reads a parsed record as format 2, migrating a format-1 one in memory with `host` as its only
+ * owner and an incomplete inventory (D6). Uninstall decides and records from this one view, so the
+ * dry run and the real run cannot migrate differently; an unknown format throws.
+ */
+export function asFormat2(parsed, host) {
+  return isFormat2(parsed) ? parsed : withOwner(parsed, host, normalizeInstallRecord(parsed));
+}
+
+/** Removes one host from the shared record so uninstall can decide what the inventory permits. */
+export async function removeInstallOwner(host) {
+  const parsed = await readAt(installRecordPath(host));
+  if (parsed === null) return null;
+  const record2 = asFormat2(parsed, host);
+  const next = withoutOwner(record2, host);
+  if (next === record2) return next;
+  await publishInstallRecord(host, next);
+  return next;
 }
 
 export function fingerprintFor(record, file) {

package/cli/install.mjs

@@ -14,15 +14,20 @@ import {
   seedPlan,
   writeInstallRecord,
 } from './manifest.mjs';
-import { copyPlannedFile, targetMatches } from './copy.mjs';
+import { copyPlannedFile, planHomeWriter, targetMatches } from './copy.mjs';
+import { removeOutside } from './record-removal.mjs';
 import { hookTargets, recordHasHooks } from './hook-targets.mjs';
-import { fingerprintFor, INSTALL_METHOD_COPY, INSTALL_METHOD_KEY } from './install-record.mjs';
+import { fingerprintFor, readInstallRecordFile } from './install-record.mjs';
+import { ownImageStampCurrent } from './install-owners.mjs';
+import { syncOtherOwners } from './owner-sync-apply.mjs';
+import { ownerRecord } from './owner-record.mjs';
 import {
   commandFor,
   inspectHook,
   mergeHook,
   withSettingsRun,
 } from './settings-merge.mjs';
+import { withLifecycle } from './lifecycle-transaction.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 import { addPermissionRules, inspectPermissions } from './permissions.mjs';
 import { contractStatus, readHostContract } from './host-contract.mjs';
@@ -30,6 +35,7 @@ import { readHostObservations } from '../src/home/lib/host-observations.mjs';
 import { brandStateDir } from '../src/home/lib/brand-home.mjs';
 import { sessionHostVersions } from './session-hosts.mjs';
 import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
+import { askTransition, detectTransition, transitionOutcome } from './inventory-transition.mjs';
 
 const WARNING = '\u001b[33m';
 const RESET = '\u001b[0m';
@@ -87,7 +93,7 @@ function permissionOutput(result, settingsPath) {
   return `All ${result.total} permission rules are already in place in ${settingsPath}, so the host runs the package command without asking.`;
 }
 
-async function migrateLegacySeed(host, seed) {
+async function migrateLegacySeed(host, seed, writer, id) {
   if (await targetExists(seed.target)) return;
   const legacyName = path.basename(seed.target) === 'config.json' ? 'run-config.json' : path.basename(seed.target);
   const legacy = path.join(host.legacyAgentsDir, legacyName);
@@ -98,22 +104,40 @@ async function migrateLegacySeed(host, seed) {
   // so the previous layout is never taken down and the operator goes on editing a file nothing
   // reads. If the comparison fails the old file stays: a half-copied config is the one case where
   // having two is better than having none.
-  await fs.mkdir(path.dirname(seed.target), { recursive: true });
-  await fs.copyFile(legacy, seed.target);
+  // Plan_65 B10: the seed lands in the home only by its registry id, and the old copy under the
+  // host agents directory is removed only after the adapter proves it lies outside the home.
+  await writer.mkdir(id, path.dirname(seed.target));
+  await writer.copyFile(id, legacy, seed.target);
   if (await fileFingerprint(legacy) !== await fileFingerprint(seed.target)) return;
-  await fs.rm(legacy, { force: true });
+  await removeOutside(writer, legacy);
 }
 
-async function installInRun({
-  host,
-  dryRun = false,
-  force = false,
-  packageRoot,
-  env = process.env,
-  contractRecord,
-  hostVersion,
-  observations,
-} = {}) {
+async function ownerSyncOutput(host, { packageRoot, env, dryRun }, output) {
+  const ownerSync = await syncOtherOwners(host, { packageRoot, env, dryRun });
+  // Update reads ownerSync to tell "another owner lags" from "this host failed" (Plan_65 B13e2d).
+  return {
+    exitCode: ownerSync.complete ? 0 : 1,
+    output: ownerSync.lines.length ? `${output}\n${ownerSync.lines.join('\n')}` : output,
+    ownerSync,
+  };
+}
+
+async function installInRun(options = {}) {
+  const {
+    host,
+    dryRun = false,
+    force = false,
+    packageRoot,
+    env = process.env,
+    contractRecord,
+    hostVersion,
+    observations,
+    inventoryTransition,
+  } = options;
+  const transitionState = inventoryTransition === undefined
+    ? await detectTransition(host) : inventoryTransition;
+  const { transition, homeHadImage, inventory: suppliedInventory } = transitionState;
+  let inventory = suppliedInventory;
   // Validate the shared registry before writes; package removal on a broken registry left the host without its watchdog.
   await readRulesRegistry(host);
   const configuredRetentionLine = retentionLine(host);
@@ -129,9 +153,11 @@ async function installInRun({
     ? 'Host contracts are judged once a session has run a shell command; then run codex-bridge doctor.' : null;
   if (noObservedHostMessage) hostContract = { ...hostContract, message: noObservedHostMessage };
   const plan = await buildInstallPlan(host, packageRoot);
+  const { writer, idFor: copyId } = planHomeWriter(host.brandRoot, plan);
   const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
   const currentPackage = await packageInfo(packageRoot);
   const record = await readInstallRecord(host);
+  const rawRecord = await readInstallRecordFile(host);
   const targets = hookTargets(host, env);
   for (const target of targets) {
     if (!plan.some((item) => item.root === 'brand' && item.relativeToRoot === target.relative)) {
@@ -167,33 +193,36 @@ async function installInRun({
     };
   }
 
+  if (inventoryTransition === undefined && transition && !dryRun) {
+    inventory = await askTransition(host, options);
+    if (inventory === 'cancel') {
+      return { exitCode: 130, output: 'Cancelled; nothing was changed.' };
+    }
+  }
+
   const changedFiles = states.filter((state) => !state.matches);
   const changedRule = !ruleState.matches;
   const sameRecord = recordMatchesPackage(record, plan, currentPackage,
     new Map(states.map((state) => [recordFileKey(state.item), state.fingerprint])),
     { path: rule.target, fingerprint: ruleState.fingerprint });
-  if (!changedFiles.length && !changedRule && inspectedHooks.every((state) => state.current)
-    && recordHasHooks(record, targets) && sameRecord) {
+  // D11: the command doctor recommends must clear its warning about this host's image stamp.
+  if (!transition && !changedFiles.length && !changedRule && inspectedHooks.every((state) => state.current)
+    && recordHasHooks(record, targets) && sameRecord && ownImageStampCurrent(rawRecord, host)) {
     if (!dryRun) {
       await addRulesOwner(host);
       // Read, never write: this branch's whole claim is that there is nothing to do, and a
       // sentence about permission rules must not be paid for by quietly restoring one.
       const permissionResult = await inspectPermissions(host.settingsPath);
-      return {
-        exitCode: 0,
-        output: contractOutput(
-          hostContract,
-          retentionOutput(
-            configuredRetentionLine,
-            `codex-bridge is already installed; nothing to do.\n${permissionOutput(permissionResult, host.settingsPath)}`,
-          ),
+      return ownerSyncOutput(host, { packageRoot, env, dryRun }, contractOutput(
+        hostContract,
+        retentionOutput(
+          configuredRetentionLine,
+          `codex-bridge is already installed; nothing to do.\n${permissionOutput(permissionResult, host.settingsPath)}`,
         ),
-      };
+      ));
     }
-    return {
-      exitCode: 0,
-      output: contractOutput(hostContract, retentionOutput(configuredRetentionLine, 'codex-bridge is already installed; nothing to do.')),
-    };
+    return ownerSyncOutput(host, { packageRoot, env, dryRun },
+      contractOutput(hostContract, retentionOutput(configuredRetentionLine, 'codex-bridge is already installed; nothing to do.')));
   }
 
   if (dryRun) {
@@ -210,22 +239,28 @@ async function installInRun({
           ? `${definition.event} hook is already registered (${registration.form} command).`
         : `Would register ${definition.event} hook ${definition.name} for matcher ${definition.matcher} with ${registration.form} command.`);
     });
+    if (transition) lines.push(`A real run would ask whether this host is the only one using ${host.brandRoot}.`);
     lines.push('Would write installation record in the brand root.');
-    return { exitCode: 0, output: contractOutput(hostContract, retentionOutput(configuredRetentionLine, lines.join('\n'))) };
+    return ownerSyncOutput(host, { packageRoot, env, dryRun },
+      contractOutput(hostContract, retentionOutput(configuredRetentionLine, lines.join('\n'))));
   }
 
   // Claim ownership of the shared rules file before writing anything. Claiming it last meant a
   // failure at that step left a fully installed host absent from the registry, and the next
   // uninstall elsewhere would then delete the rules out from under it.
   await addRulesOwner(host);
-  for (const { item } of changedFiles) await copyPlannedFile(item, host.brandRoot);
-  if (changedRule) await copyPlannedFile(rule, host.brandRoot);
+  for (const { item } of changedFiles) {
+    await copyPlannedFile(item, host.brandRoot, { writer, id: copyId(item) });
+  }
+  if (changedRule) await copyPlannedFile(rule, host.brandRoot, { writer, id: copyId(rule) });
   // Seeded files are written once and then belong to the operator: an existing one is left
   // exactly as it is, including under --force, because --force is about our files, not theirs.
   for (const seed of seedPlan(host, packageRoot)) {
     if (!(await targetExists(seed.target))) {
-      await migrateLegacySeed(host, seed);
-      if (!(await targetExists(seed.target))) await copyPlannedFile(seed, host.brandRoot);
+      await migrateLegacySeed(host, seed, writer, copyId(seed));
+      if (!(await targetExists(seed.target))) {
+        await copyPlannedFile(seed, host.brandRoot, { writer, id: copyId(seed) });
+      }
     }
   }
   const hookResults = [];
@@ -239,49 +274,27 @@ async function installInRun({
   const permissionResult = dryRun
     ? { dryRun: true, added: 0, present: 0, total: 0 }
     : await addPermissionRules(host.settingsPath);
-  const fingerprints = {};
-  for (const item of plan) {
-    fingerprints[item.root] ??= {};
-    fingerprints[item.root][item.relativeToRoot] = await fileFingerprint(item.target);
-  }
-  const hooks = targets.map(({ definition, relative, registration }, index) => {
-    const prior = record?.hooks?.find((hook) => hook.event === definition.event
-      && hook.root === 'brand' && hook.path === relative);
-    const createdGroup = hookResults[index].createdGroup || prior?.createdGroup === true;
-    const command = registration.command;
-    return {
-      event: definition.event,
-      root: 'brand',
-      path: relative,
-      command,
-      form: command.startsWith('codex-bridge hook ') ? 'short' : 'path',
-      ...(createdGroup ? { createdGroup: true } : {}),
-    };
-  });
-  await writeInstallRecord(host, {
-    ...currentPackage,
-    installedAt: new Date().toISOString(),
-    [INSTALL_METHOD_KEY]: INSTALL_METHOD_COPY,
-    files: plan.map((item) => ({ root: item.root, path: item.relativeToRoot })),
-    fingerprints,
-    rules: { path: rule.target, fingerprint: await fileFingerprint(rule.target) },
-    hooks,
-  });
-  return {
-    exitCode: 0,
-    output: contractOutput(
-      hostContract,
-      retentionOutput(
-        configuredRetentionLine,
-        `Installed ${plan.length} files and the Codex rules file, and registered ${hookSummary(targets)}.`
-          + `\n${permissionOutput(permissionResult, host.settingsPath)}`,
-      ),
+  const row = await ownerRecord({ plan, rule, targets, hookResults, prior: record, currentPackage });
+  await writeInstallRecord(host, row, { homeHadImage, inventory });
+  const transitionLine = transition ? `\n${transitionOutcome(host, inventory)}` : '';
+  return ownerSyncOutput(host, { packageRoot, env, dryRun }, contractOutput(
+    hostContract,
+    retentionOutput(
+      configuredRetentionLine,
+      `Installed ${plan.length} files and the Codex rules file, and registered ${hookSummary(targets)}.`
+        + `\n${permissionOutput(permissionResult, host.settingsPath)}${transitionLine}`,
     ),
-  };
+  ));
 }
 
 export async function install(options = {}) {
   const host = options?.host;
   if (!host?.settingsPath) return installInRun(options);
-  return withSettingsRun(host.settingsPath, () => installInRun(options));
+  if (options.dryRun === true) return withSettingsRun(host.settingsPath, () => installInRun(options));
+  return withLifecycle(
+    host,
+    'install',
+    () => withSettingsRun(host.settingsPath, () => installInRun(options)),
+    { ticket: options.lifecycleTicket, waitMs: options.lifecycleWaitMs, createHome: true },
+  );
 }