@lyupro/codex-bridge 0.6.8 → 0.6.9

package/cli/uninstall.mjs

@@ -1,33 +1,27 @@
-/** Uninstalls only recorded files from both roots while preserving host data and foreign files. */
-import fs from 'node:fs/promises';
-import path from 'node:path';
+/**
+ * Uninstalls one host: its side from an inspection of the package's marks, the shared image only from
+ * the record and only once the host is detached, preserving host data and foreign files (Plan_65 D10).
+ */
 import {
-  definitionForRecordedHook,
-  fileFingerprint,
-  installRecordPath,
   legacyInstallRecordPath,
   readInstallRecord,
-  recordTarget,
 } from './manifest.mjs';
+import { imageRemoval } from './install-owners.mjs';
+import { asFormat2, readInstallRecordFile } from './install-record.mjs';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
 import { removePermissionRules } from './permissions.mjs';
-import { hostContractPath } from './host-contract.mjs';
-import { brandStateDir } from '../src/home/lib/brand-home.mjs';
-import {
-  commandFor,
-  removeHook,
-  withSettingsRun,
-} from './settings-merge.mjs';
-import { readRulesRegistry, removeRulesOwner, remainingRulesOwners } from './rules-owners.mjs';
-import {
-  claudeBoundary,
-  removeEmpty,
-  removeEmptyLayout,
-  removeEmptyParents,
-} from './remove-layout.mjs';
-
-function remainingOwnersText(count) {
-  return `${count} other owner${count === 1 ? '' : 's'} ${count === 1 ? 'remains' : 'remain'}`;
-}
+import { inspectHost, hasPackageMarks } from './host-inspection.mjs';
+import { removeHostSide } from './host-removal.mjs';
+import { askRemoval, removalHint } from './inventory-removal.mjs';
+import { withSettingsRun } from './settings-merge.mjs';
+import { withLifecycle } from './lifecycle-transaction.mjs';
+import { readRulesRegistry } from './rules-owners.mjs';
+import { rulesDryRunLines, removeRulesForHost, remainingOwnersText } from './uninstall-rules.mjs';
+import { removeEmpty, removeEmptyLayout } from './remove-layout.mjs';
+import { recordHomeWriter, removeOutside } from './record-removal.mjs';
+import { buildHomeRemovalPlan } from './home-removal-plan.mjs';
+import { executeHomePlan } from './home-plan-execute.mjs';
+import { outcomeLines, outcomeExitCode, planLines, planExitCode } from './removal-outcomes.mjs';
 
 function permissionOutput(host, removed, dryRun) {
   const verb = dryRun ? 'Would remove' : 'Removed';
@@ -35,36 +29,116 @@ function permissionOutput(host, removed, dryRun) {
   return `${verb} ${removed} permission rule ${plural} from ${host.settingsPath}.`;
 }
 
-// Plan_62 D22: uninstall removes only recorded files, and the message used to name only runs and
-// config.json — state/, the host measurement and conventions.md stayed behind unmentioned. Until
-// Plan_65 derives this from a registry, the sentence names every kind the package writes while working.
-function preservationText(host) {
-  return `Run artifacts in ${path.join(host.root, 'codex-runs')} are preserved, and so is what the package `
-    + `wrote into ${host.brandRoot} while working: the run configuration ${host.brandConfigPath}, the conventions `
-    + `${host.brandConventionsPath}, the host measurement ${hostContractPath(host)} and runtime state in `
-    + `${brandStateDir(host.brandRoot)} (dispatcher state, guard counters, the handback witness, the host `
-    + 'observations, dispatcher contract verdicts, and hook diagnostics that hold the full hook input). Delete them by '
-    + 'hand for a complete removal.';
+// Permission strings live in the same settings.json as the hooks; an unreadable file is left untouched
+// and named rather than rewritten, like the hooks themselves (Plan_65 D10 item 4).
+export async function removePermissions(host, inspection, dryRun) {
+  if (inspection.settingsError !== null) {
+    return `Left permission rules in ${host.settingsPath} because \
+settings could not be read: ${inspection.settingsError}`;
+  }
+  const { removed } = await removePermissionRules(host.settingsPath, { dryRun });
+  return permissionOutput(host, removed, dryRun);
+}
+
+export function stillAttachedLine(host) {
+  return `Did not finish uninstalling codex-bridge: ${host.root} still has its hooks; fix \
+${host.settingsPath} and run uninstall again.`;
+}
+
+// Plan_65 D6: uninstalling one host removed the shared image from under every other host of the
+// home. Only a record at the old per-host path (no home record at all) keeps the old behavior.
+function imageDecision(rawRecord, host) {
+  if (rawRecord === null) return { removeImage: true };
+  return imageRemoval(asFormat2(rawRecord, host), host);
 }
 
-function displayFile(file) {
-  return `${file.root}/${file.path}`;
+// Plan_65 D12: only a detached last owner permits the plan to remove the shared image.
+function imagePolicyFor(decision, hostSide) {
+  if (!decision.removeImage) return { remove: false, reason: decision.reason };
+  return hostSide.detached
+    ? { remove: true, reason: 'last owner' }
+    : { remove: false, reason: 'this host is still attached' };
 }
 
-function hookRemovalSpec(host, hook) {
-  const definition = definitionForRecordedHook(hook);
-  const target = recordTarget(host, hook);
-  const full = commandFor(target);
-  const short = `codex-bridge hook ${definition.name}`;
+function imageDispositionLine(host, decision, dryRun) {
+  if (decision.removeImage) return null;
+  const verb = dryRun ? 'Would leave' : 'Left';
+  if (decision.reason === 'no-record') {
+    return `${verb} the shared image in ${host.brandRoot} because \
+this host has no installation record; its members are unknown.`;
+  }
+  if (decision.reason === 'other-owners') {
+    return `${verb} the shared image in ${host.brandRoot} because ${remainingOwnersText(decision.remaining)}.`;
+  }
+  return `${verb} the shared image in ${host.brandRoot} because \
+the installation inventory is incomplete: other installations may use this home.`;
+}
+
+// Plan_65 D9 item 3 as amended by D10 item 4: after the last known owner answered "no", a repeat uninstall
+// of ANY host of the home promised a question and printed "not installed" instead. The branch decides from
+// the raw record and the inspection only — `legacy` is nobody's host view (D10 item 5) — removes the named
+// host's side either way, and removes the image only on "yes" for a detached host.
+async function uninstallOrphan(options, inspection, registry) {
+  const { host, dryRun = false } = options;
+  const promptOptions = { ...options, candidates: options.candidates ?? registry?.owners ?? [] };
+  if (dryRun) {
+    const permissionLine = await removePermissions(host, inspection, true);
+    const hostSide = await removeHostSide(host, inspection, { owner: null, dryRun: true });
+    const imagePolicy = { remove: hostSide.detached,
+      reason: hostSide.detached ? 'operator confirmed' : 'this host is still attached' };
+    const plan = await buildHomeRemovalPlan({ command: 'uninstall', host, packageRoot: options.packageRoot,
+      imagePolicy });
+    return {
+      exitCode: 1,
+      output: [permissionLine, ...hostSide.lines,
+        `A real run would ask whether to remove the shared image of ${host.brandRoot}: \
+no host is recorded as using it.`,
+        'If the answer is yes:', ...planLines(plan, { host, detached: hostSide.detached })].join('\n'),
+    };
+  }
+
+  const answer = await askRemoval(host, 'orphan', promptOptions);
+  if (answer === 'cancel') return { exitCode: 130, output: 'Cancelled; nothing was changed.' };
+
+  const permissionLine = await removePermissions(host, inspection, false);
+  const hostSide = await removeHostSide(host, inspection, { owner: null });
+  const imagePolicy = answer === 'remove'
+    ? { remove: hostSide.detached,
+      reason: hostSide.detached ? 'operator confirmed' : 'this host is still attached' }
+    : { remove: false, reason: 'no host is recorded as using it' };
+  const plan = await buildHomeRemovalPlan({ command: 'uninstall', host, packageRoot: options.packageRoot,
+    imagePolicy });
+  await removeEmpty(host.commandsDir);
+  await removeEmpty(host.agentsDir);
+  await removeEmptyLayout(host.legacyAgentsDir);
+  await removeEmptyLayout(host.legacyCommandsDir);
+  const { outcomes } = await executeHomePlan(host, plan,
+    { detached: hostSide.detached, imageMembers: plan.imageMembers });
+
+  let imageLine = null;
+  let hint = null;
+  if (answer === 'remove' && !hostSide.detached) {
+    imageLine = `Left the shared image in ${host.brandRoot} because this host's hooks could not be removed.`;
+  } else if (answer !== 'remove') {
+    imageLine = `Left the shared image in ${host.brandRoot} because no host is recorded as using it \
+and the inventory is incomplete.`;
+    hint = removalHint(host);
+  }
+
+  const hasMarks = hasPackageMarks(inspection);
+  const heading = !hostSide.detached
+    ? stillAttachedLine(host)
+    : hasMarks ? 'Uninstalled codex-bridge.'
+      : `No codex-bridge files or hooks were found in ${host.root}.`;
   return {
-    event: hook.event,
-    matcher: definition.matcher,
-    command: hook.command || full,
-    alternateCommands: [full, short],
+    exitCode: answer === 'remove' && hostSide.detached ? outcomeExitCode(outcomes) : 1,
+    output: [heading, permissionLine, ...hostSide.lines, imageLine, hint, ...outcomeLines(outcomes, { host })]
+      .filter(Boolean).join('\n'),
   };
 }
 
-async function uninstallInRun({ host, dryRun = false } = {}) {
+async function uninstallInRun(options = {}) {
+  const { host, dryRun = false } = options;
   // Preflight before removing the hook: package removal on a broken registry left the host without its watchdog.
   let registry = null;
   let registryError = null;
@@ -73,101 +147,108 @@ async function uninstallInRun({ host, dryRun = false } = {}) {
   } catch (err) {
     registryError = err;
   }
-  const permissionResult = await removePermissionRules(host.settingsPath, { dryRun });
-  const permissionLine = permissionOutput(host, permissionResult.removed, dryRun);
+  // Plan_65 D9: the question precedes the first change, so the record is read before the permission rules go;
+  // a cancel then leaves the host exactly as it was.
+  const rawRecord = await readInstallRecordFile(host);
+  const ownerKey = normalizeRepoPath(host.root);
+  const format2 = rawRecord === null ? null : asFormat2(rawRecord, host);
+  const orphaned = format2 !== null && Object.keys(format2.owners).length === 0;
+  const owner = format2?.owners[ownerKey] ?? null;
+  // Plan_65 D10: inspect marks and content before permission edits or any other host mutation.
+  const inspection = await inspectHost(host, { owner });
+  if (orphaned) return uninstallOrphan(options, inspection, registry);
+
   const record = await readInstallRecord(host);
-  const preservation = preservationText(host);
-  if (!record) {
-    return { exitCode: 1, output: `${permissionLine}\ncodex-bridge is not installed.\n${preservation}` };
+  let decision = rawRecord === null
+    ? (record ? { removeImage: true } : { removeImage: false, reason: 'no-record' })
+    : imageDecision(rawRecord, host);
+  if (!record && decision.removeImage) decision = { removeImage: false, reason: 'no-record' };
+  const lastKnownOwner = decision.reason === 'incomplete-inventory'
+    && Object.hasOwn(format2.owners, ownerKey);
+  let lastOwnerHint = null;
+  if (lastKnownOwner && !dryRun) {
+    const answer = await askRemoval(host, 'last-owner', options);
+    if (answer === 'cancel') return { exitCode: 130, output: 'Cancelled; nothing was changed.' };
+    if (answer === 'remove') decision = { removeImage: true };
+    else lastOwnerHint = removalHint(host);
   }
+  const permissionLine = await removePermissions(host, inspection, dryRun);
+  const hostMarks = hasPackageMarks(inspection);
+  if (!record && !hostMarks) {
+    return {
+      exitCode: 1,
+      output: [permissionLine, 'codex-bridge is not installed.', ...outcomeLines([], { host })].join('\n'),
+    };
+  }
+  const writer = record ? recordHomeWriter(host, record.files) : null;
 
   if (dryRun) {
-    const lines = [permissionLine, ...record.files.map((file) => `Would remove ${displayFile(file)}`)];
-    if (record.rules) {
-      if (registryError) {
-        lines.push(`Would leave ${record.rules.path} because the rules ownership registry is invalid; ownership is unknown.`);
-      } else {
-        const remainingOwners = remainingRulesOwners(registry, host);
-        const currentFingerprint = await fileFingerprint(record.rules.path);
-        if (remainingOwners?.length) {
-          lines.push(`Would leave ${record.rules.path} because ${remainingOwnersText(remainingOwners.length)}.`);
-        } else if (currentFingerprint === record.rules.fingerprint) {
-          lines.push(`Would remove ${record.rules.path}; no other owners remain and its fingerprint is unchanged.`);
-        } else if (currentFingerprint !== null) {
-          lines.push(`Would leave ${record.rules.path} because its contents changed after installation.`);
-        } else {
-          lines.push(`Would leave ${record.rules.path} because it is already absent.`);
-        }
-        if (!registry) {
-          lines.push(`Warning: the rules ownership registry was missing; other installations may use ${record.rules.path}.`);
-        }
-      }
-    }
-    for (const hook of record.hooks) {
-      const definition = definitionForRecordedHook(hook);
-      lines.push(`Would remove the ${hook.event} hook ${definition.name} for matcher ${definition.matcher}.`);
-    }
-    lines.push('Would remove the installation record from the brand root.');
-    lines.push(preservation);
-    return { exitCode: 0, output: lines.join('\n') };
+    const hostSide = await removeHostSide(host, inspection, { owner, dryRun: true });
+    const imagePolicy = imagePolicyFor(decision, hostSide);
+    const plan = await buildHomeRemovalPlan({ command: 'uninstall', host, packageRoot: options.packageRoot,
+      imagePolicy });
+    const lines = [permissionLine, ...hostSide.lines];
+    const blockedImageLine = decision.removeImage && !hostSide.detached
+      ? `Would leave the shared image in ${host.brandRoot} because this host's hooks could not be removed.`
+      : null;
+    const imageLine = blockedImageLine || (!decision.removeImage
+      ? imageDispositionLine(host, decision, true) : null);
+    if (imageLine) lines.push(imageLine);
+    if (lastKnownOwner) lines.push(`A real run would ask whether ${host.root} is the last host \
+using ${host.brandRoot}.`);
+    lines.push(...await rulesDryRunLines({
+      host, record, registry, registryError, detached: hostSide.detached,
+    }));
+    lines.push(...planLines(plan, { host, detached: hostSide.detached }));
+    return {
+      exitCode: decision.reason === 'incomplete-inventory' || !hostSide.detached ? 1 : planExitCode(plan),
+      output: lines.join('\n'),
+    };
   }
 
-  for (const hook of record.hooks) {
-    await removeHook(host.settingsPath, hookRemovalSpec(host, hook), {
-      createdGroup: hook.createdGroup === true,
-    });
-  }
-  let ownership = null;
-  if (!registryError) {
-    try {
-      ownership = await removeRulesOwner(host);
-    } catch (err) {
-      registryError = err;
-    }
-  }
-  const rulesOutput = [];
-  if (record.rules) {
-    if (registryError) {
-      rulesOutput.push(`Left ${record.rules.path} because the rules ownership registry is invalid; ownership is unknown.`);
-    } else {
-      if (ownership?.owners.length) {
-        rulesOutput.push(`Left ${record.rules.path} because ${remainingOwnersText(ownership.owners.length)}.`);
-      } else {
-        const currentFingerprint = await fileFingerprint(record.rules.path);
-        if (currentFingerprint === record.rules.fingerprint) {
-          await fs.rm(record.rules.path, { force: true });
-        } else if (currentFingerprint !== null) {
-          rulesOutput.push(`Left ${record.rules.path} because its contents changed after installation.`);
-        }
-      }
-      if (!registry) {
-        rulesOutput.push(`Warning: the rules ownership registry was missing; other installations may use ${record.rules.path}.`);
-      }
-    }
-  }
-  for (const file of record.files) {
-    const target = recordTarget(host, file);
-    await fs.rm(target, { force: true });
-    const boundary = file.root === 'brand'
-      ? host.brandRoot
-      : claudeBoundary(host, target);
-    await removeEmptyParents(target, boundary);
-  }
+  const hostSide = await removeHostSide(host, inspection, { owner });
+  const imagePolicy = imagePolicyFor(decision, hostSide);
+  const plan = await buildHomeRemovalPlan({ command: 'uninstall', host, packageRoot: options.packageRoot,
+    imagePolicy });
+  // Plan_65 D10 item 4: a host still attached keeps everything it shares — its rules ownership, its
+  // place in the record, the old per-host record — so a repeat run after the fix finds it whole.
+  const detachedRecord = record && hostSide.detached ? record : null;
+  const rulesResult = await removeRulesForHost({
+    host, record, registry, registryError, detached: hostSide.detached, writer,
+  });
+  const rulesOutput = rulesResult.lines;
+  registryError = rulesResult.registryError;
+  const { outcomes } = await executeHomePlan(host, plan,
+    { detached: hostSide.detached, imageMembers: plan.imageMembers });
   await removeEmpty(host.commandsDir);
-  await fs.rm(installRecordPath(host), { force: true });
-  await fs.rm(legacyInstallRecordPath(host), { force: true });
+  if (detachedRecord) await removeOutside(writer, legacyInstallRecordPath(host));
   await removeEmpty(host.agentsDir);
   await removeEmptyLayout(host.legacyAgentsDir);
   await removeEmptyLayout(host.legacyCommandsDir);
-  await removeEmpty(host.brandRoot);
+  const blockedImageLine = decision.removeImage && !hostSide.detached
+    ? `Left the shared image in ${host.brandRoot} because this host's hooks could not be removed.`
+    : null;
+  const imageLine = blockedImageLine || (!decision.removeImage
+    ? imageDispositionLine(host, decision, false) : null);
+  const heading = hostSide.detached
+    ? 'Uninstalled codex-bridge.'
+    : stillAttachedLine(host);
   return {
-    exitCode: 0,
-    output: ['Uninstalled codex-bridge.', permissionLine, ...rulesOutput, preservation].join('\n'),
+    exitCode: decision.reason === 'incomplete-inventory' || !hostSide.detached ? 1 : outcomeExitCode(outcomes),
+    output: [heading, permissionLine, ...hostSide.lines, ...rulesOutput, imageLine, lastOwnerHint,
+      ...outcomeLines(outcomes, { host })].filter(Boolean).join('\n'),
   };
 }
 
 export async function uninstall(options = {}) {
   const host = options?.host;
   if (!host?.settingsPath) return uninstallInRun(options);
-  return withSettingsRun(host.settingsPath, () => uninstallInRun(options));
+  // A dry run only reads; like install's, it must not wait on or create anything.
+  if (options.dryRun === true) return withSettingsRun(host.settingsPath, () => uninstallInRun(options));
+  return withLifecycle(
+    host,
+    'uninstall',
+    () => withSettingsRun(host.settingsPath, () => uninstallInRun(options)),
+    { ticket: options.lifecycleTicket, waitMs: options.lifecycleWaitMs },
+  );
 }

package/cli/unlock-lifecycle.mjs

@@ -0,0 +1,102 @@
+/**
+ * Parses and renders `unlock --lifecycle [--clear]` (Plan_65 D11): the busy refusal of install, update
+ * and uninstall sends the operator here, so the command has to name the holder and clear a crash's lock.
+ */
+import { resolveBrandHome } from '../src/home/lib/brand-home.mjs';
+import { withCommandHelp } from './command-help.mjs';
+import { inspectLifecycleLock } from './lifecycle-lock-inspect.mjs';
+import { clearLifecycleLock } from './lifecycle-lock-clear.mjs';
+
+const heldLine = (holder) => (
+  `held by ${holder.command} for ${holder.hostRoot}, pid ${holder.pid}, since ${holder.acquiredAt}.`
+);
+
+function renderClear(observation) {
+  const { homeRoot, strategy, holder, lockPath, gatePath, gateLeft } = observation;
+  const lines = [`Lifecycle lock of ${homeRoot} (${strategy}), clearing:`];
+  let exitCode = 0;
+  switch (observation.outcome) {
+    case 'cleared':
+      lines.push(`Removed the lock left by ${holder.command} for ${holder.hostRoot}, pid ${holder.pid} (dead).`);
+      lines.push('The next install, update or uninstall may take it.');
+      break;
+    case 'free':
+      lines.push('Nothing to clear; the lock is free.');
+      break;
+    case 'kernel-managed':
+      lines.push('Kernel-managed lock; nothing to clear.');
+      lines.push('Run codex-bridge unlock --lifecycle to see its holder.');
+      break;
+    case 'refused':
+      lines.push(`Refused: ${observation.reason}. Nothing was removed.`);
+      if (holder) lines.push(heldLine(holder));
+      lines.push(`If you are sure no install, update or uninstall is running, delete ${lockPath} yourself.`);
+      exitCode = 1;
+      break;
+    case 'gate-busy':
+      lines.push(`Another clear is in progress or crashed: ${gatePath}.`);
+      lines.push('If none is running, delete that file yourself.');
+      exitCode = 1;
+      break;
+    case 'no-home':
+      lines.push(`codex-bridge unlock --lifecycle: no package home at ${homeRoot}; nothing to inspect.`);
+      exitCode = 1;
+      break;
+    default:
+      throw new Error(`Unknown lifecycle lock clear outcome: ${observation.outcome}`);
+  }
+  if (gateLeft) {
+    lines.push(`Could not remove the clear gate: ${gateLeft}.`);
+    lines.push('If no clear is running, delete that file yourself.');
+    exitCode = 1;
+  }
+  return { exitCode, output: lines.join('\n') };
+}
+
+export async function unlockLifecycle(argv, options = {}) {
+  const clearing = argv.length === 2 && argv[0] === '--lifecycle' && argv[1] === '--clear';
+  if (!clearing && (argv.length !== 1 || argv[0] !== '--lifecycle')) {
+    // Name the first argument past the longest accepted prefix, not always the second one.
+    const accepted = argv[0] === '--lifecycle' ? (argv[1] === '--clear' ? 2 : 1) : 0;
+    const argument = argv[accepted];
+    return {
+      exitCode: 2,
+      output: withCommandHelp('unlock', `codex-bridge unlock --lifecycle: unexpected argument "${argument}".`),
+    };
+  }
+  const homeRoot = options.homeRoot ?? resolveBrandHome().root;
+  if (clearing) return renderClear(await clearLifecycleLock(homeRoot, options.clear ?? {}));
+  const observation = await inspectLifecycleLock(homeRoot, options.inspect ?? {});
+  const { strategy, observedAt, holder, liveness } = observation;
+  const lines = [`Lifecycle lock of ${homeRoot} (${strategy}), observed ${observedAt}:`];
+  let exitCode = 0;
+  switch (observation.state) {
+    case 'free':
+      lines.push('free — no install, update or uninstall holds it.');
+      break;
+    case 'held':
+      if (holder === null) {
+        lines.push('held; the holder did not identify itself.');
+        break;
+      }
+      lines.push(heldLine(holder));
+      if (strategy === 'file') {
+        lines.push(`Holder process: ${liveness}.`);
+        if (liveness === 'dead') {
+          lines.push('The file was left by a crash. Clear it with codex-bridge unlock --lifecycle --clear');
+        }
+      }
+      break;
+    case 'unverified':
+      lines.push(`could not be verified: ${observation.reason}. Nothing was changed.`);
+      exitCode = 1;
+      break;
+    case 'no-home':
+      lines.push(`codex-bridge unlock --lifecycle: no package home at ${homeRoot}; nothing to inspect.`);
+      exitCode = 1;
+      break;
+    default:
+      throw new Error(`Unknown lifecycle lock state: ${observation.state}`);
+  }
+  return { exitCode, output: lines.join('\n') };
+}

package/cli/unlock.mjs

@@ -2,6 +2,7 @@
 /** Closes dead-pid running records without deleting any run artifacts. */
 import fs from 'node:fs';
 import path from 'node:path';
+import { withCommandHelp } from './command-help.mjs';
 import { formatSilence, heartbeatAge, HEARTBEAT_STALE_MS } from '../src/home/lib/heartbeat.mjs';
 import { runLiveness } from '../src/home/lib/meta/run-liveness.mjs';
 import { markAbandoned } from '../src/home/lib/meta/run-state.mjs';
@@ -14,6 +15,7 @@ import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
 import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 import { readJson } from '../src/home/lib/write-meta.mjs';
 import { renderTable } from './table.mjs';
+import { unlockLifecycle } from './unlock-lifecycle.mjs';
 
 const CLOSED_COLUMNS = [
   { key: 'project', label: 'project' },
@@ -38,20 +40,20 @@ function parseArgs(argv) {
   let all = false;
   for (const arg of argv) {
     if (arg === '--all') {
-      if (all) return { error: 'codex-bridge unlock accepts --all only once.' };
+      if (all) return { error: withCommandHelp('unlock', 'codex-bridge unlock accepts --all only once.') };
       all = true;
       continue;
     }
     if (typeof arg !== 'string' || arg.startsWith('-')) {
-      return { error: `codex-bridge unlock: unknown option "${arg}".` };
+      return { error: withCommandHelp('unlock', `codex-bridge unlock: unknown option "${arg}".`) };
     }
     positional.push(arg);
   }
   if (all && positional.length) {
-    return { error: 'codex-bridge unlock accepts either --all or one project name.' };
+    return { error: withCommandHelp('unlock', 'codex-bridge unlock accepts either --all or one project name.') };
   }
   if (positional.length > 1) {
-    return { error: 'codex-bridge unlock accepts at most one project name.' };
+    return { error: withCommandHelp('unlock', 'codex-bridge unlock accepts at most one project name.') };
   }
   const project = positional[0] || null;
   if (project && (path.isAbsolute(project) || path.dirname(project) !== '.')) {
@@ -228,6 +230,7 @@ function renderReport(plan, records, closed, failures, options) {
 }
 
 export function unlock(argv = [], options = {}) {
+  if (argv[0] === '--lifecycle') return unlockLifecycle(argv, options);
   const plan = unlockPlan(argv, options);
   if (plan.error) return result(2, plan.error);
   const records = plan.projects.flatMap((project) => inspectRuns(project, options));