@lyupro/codex-bridge 0.6.8 → 0.6.10

package/cli/inventory-removal.mjs

@@ -0,0 +1,84 @@
+/**
+ * Asks the operator's permission for removals the installation record cannot prove safe: uninstall's
+ * shared image under an incomplete inventory (Plan_65 D9) and purge's two consents (D6, D12 item 5).
+ *
+ * An old installation record never named every host of the home, so leaving the last KNOWN owner
+ * behind, or finding no owner at all, is not proof that nobody else runs from the image. Only the
+ * operator can say so; "yes" is that permission, anything else keeps the image with a hint how to
+ * come back to the question.
+ */
+import { askYesNo, isInteractive } from './terminal-question.mjs';
+import { readRulesRegistry } from './rules-owners.mjs';
+import { registryHintLines } from './inventory-transition.mjs';
+
+const KEPT_DATA = 'config.json, conventions.md and run data stay.';
+
+export function lastOwnerQuestion(host, candidates) {
+  return [
+    `Home: ${host.brandRoot}`,
+    `Known owners: only this host (${host.root}), which is leaving.`,
+    'The installation inventory is incomplete: an old installation record did not name every host that used this home.',
+    ...registryHintLines(host, candidates),
+    `Is ${host.root} the last host using this home? Yes removes the shared image and the installation record; ${KEPT_DATA}`,
+  ].join('\n');
+}
+
+export function orphanQuestion(host, candidates) {
+  return [
+    `Home: ${host.brandRoot}`,
+    'No host is recorded as using this home, and the inventory is incomplete.',
+    ...registryHintLines(host, candidates),
+    `Remove the shared image and the installation record of this home? The package's files and hooks in ${host.root} are removed either way; ${KEPT_DATA}`,
+  ].join('\n');
+}
+
+const QUESTIONS = { 'last-owner': lastOwnerQuestion, orphan: orphanQuestion };
+
+export async function askRemoval(host, kind, options) {
+  const question = QUESTIONS[kind];
+  if (!question) throw new TypeError(`Unknown inventory removal kind: ${kind}`);
+  if (!isInteractive(options)) return 'keep';
+  const candidates = options.candidates ?? (await readRulesRegistry(host))?.owners ?? [];
+  const answer = await askYesNo(question(host, candidates), options);
+  if (answer === 'yes') return 'remove';
+  if (answer === 'no') return 'keep';
+  return 'cancel';
+}
+
+// Plan_65 D6/D12 item 5: purge needs two separate consents, in this order. The first replaces the
+// inventory the record cannot prove; the second is the only permission to delete the operator's own data.
+export function purgeInventoryQuestion(host, candidates) {
+  return [
+    `Home: ${host.brandRoot}`,
+    `Purge removes this home for good, including what you edited in it. Leaving host: ${host.root}.`,
+    ...registryHintLines(host, candidates),
+    'Is the inventory complete — does no other host use this home?',
+  ].join('\n');
+}
+
+export function purgeDataQuestion(host, dataFiles) {
+  const listed = dataFiles.length ? dataFiles.map((file) => `  ${file}`) : ['  none found'];
+  return [
+    `Your data in ${host.brandRoot}:`,
+    ...listed,
+    'Delete it? This cannot be undone; run artifacts outside the home stay.',
+  ].join('\n');
+}
+
+/**
+ * Asks one purge consent. Unlike askRemoval, "no terminal" is answered here as 'no': purge without
+ * a person at the keyboard has no consent to rely on, and the caller refuses rather than keeping.
+ */
+export async function askPurgeConsent(host, kind, options, detail = []) {
+  if (kind !== 'inventory' && kind !== 'data') throw new TypeError(`Unknown purge consent: ${kind}`);
+  if (!isInteractive(options)) return 'no';
+  const question = kind === 'inventory'
+    ? purgeInventoryQuestion(host, options.candidates ?? (await readRulesRegistry(host))?.owners ?? [])
+    : purgeDataQuestion(host, detail);
+  return askYesNo(question, options);
+}
+
+export function removalHint(host) {
+  return `Run codex-bridge uninstall --host "${host.root}" again in a terminal to confirm that no other host uses `
+    + `${host.brandRoot} and remove it.`;
+}

package/cli/inventory-transition.mjs

@@ -0,0 +1,66 @@
+/**
+ * D9: The inventory becomes incomplete in one transition known before any write; ask then and
+ * store nothing about a refusal.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { askYesNo, isInteractive } from './terminal-question.mjs';
+import { isFormat2 } from './install-owners.mjs';
+import { readInstallRecordFile } from './install-record.mjs';
+import { normalizedRulesOwner, readRulesRegistry } from './rules-owners.mjs';
+
+async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+export async function detectTransition(host) {
+  const [record, homeHadImage] = await Promise.all([
+    readInstallRecordFile(host),
+    exists(path.join(host.brandRoot, 'lib')),
+  ]);
+  return {
+    transition: (record !== null && !isFormat2(record)) || (record === null && homeHadImage),
+    homeHadImage,
+  };
+}
+
+// The uninstall questions (cli/inventory-removal.mjs) show the same hint: one rendering, one wording.
+export function registryHintLines(host, candidates) {
+  const owner = normalizedRulesOwner(host);
+  const otherCandidates = candidates.filter((root) => root !== owner);
+  return [
+    'Codex rules registry host roots are a hint only; they may be stale or belong to another home:',
+    ...(otherCandidates.length ? otherCandidates.map((root) => `  ${root}`) : ['  none found']),
+  ];
+}
+
+export function transitionQuestion(host, candidates) {
+  return [
+    `Home: ${host.brandRoot}`,
+    `Known owners: none yet besides this host (${host.root}).`,
+    'The old installation record did not name every host that used this home.',
+    ...registryHintLines(host, candidates),
+    `Is ${host.root} the only host using this home?`,
+  ].join('\n');
+}
+
+export async function askTransition(host, options) {
+  if (!isInteractive(options)) return 'incomplete';
+  const candidates = options.candidates ?? (await readRulesRegistry(host))?.owners ?? [];
+  const answer = await askYesNo(transitionQuestion(host, candidates), options);
+  if (answer === 'yes') return 'complete';
+  if (answer === 'no') return 'incomplete';
+  return 'cancel';
+}
+/** What the operator is told after a transition: which answer was recorded and what it keeps. */
+export function transitionOutcome(host, inventory) {
+  return inventory === 'complete'
+    ? `Recorded this host as the only one using ${host.brandRoot}.`
+    : 'The inventory stays incomplete: the shared image is kept until an uninstall confirms no other host uses it.';
+}

package/cli/lifecycle-lock-clear.mjs

@@ -0,0 +1,104 @@
+/**
+ * Removes a crashed holder's file lock, and only that (Plan_65 D11). D8 forbids ever removing a live
+ * holder's lock; advice A14 showed two clearers that both read dead holder X can remove the lock a new
+ * holder Y created in between, so clearers queue on a gate file taken before the authoritative read.
+ * Rename-then-verify is forbidden: moving a replacement live lock already frees its name.
+ */
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { createHomeWriter } from '../src/home/lib/home-write.mjs';
+import { holderLiveness, lifecycleLockStrategy, parseHolder } from './lifecycle-lock.mjs';
+
+const ARTIFACT_ID = 'install-record';
+const errorReason = (error) => error?.code || error?.message || String(error);
+
+async function clearHeldGate(lockPath, identity, writer) {
+  let before;
+  try {
+    before = await fsp.lstat(lockPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { outcome: 'free' };
+    throw error;
+  }
+  if (!before.isFile()) return { outcome: 'refused', reason: 'not a regular file' };
+  const content = await fsp.readFile(lockPath);
+  const holder = parseHolder(content.toString('utf8').split(/\r?\n/, 1)[0]);
+  if (!holder) return { outcome: 'refused', reason: 'holder record is unreadable or incomplete' };
+  const liveness = holderLiveness(holder, identity);
+  if (liveness !== 'dead') return { outcome: 'refused', reason: `the holder process is ${liveness}`, holder };
+
+  let current;
+  let after;
+  try {
+    current = await fsp.readFile(lockPath);
+    after = await fsp.lstat(lockPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return { outcome: 'refused', reason: 'the lock changed while clearing', holder };
+    }
+    return { outcome: 'refused', reason: errorReason(error), holder };
+  }
+  if (!after.isFile() || !content.equals(current)
+    || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+    return { outcome: 'refused', reason: 'the lock changed while clearing', holder };
+  }
+  try {
+    await writer.unlink(ARTIFACT_ID, lockPath);
+  } catch (error) {
+    return { outcome: 'refused', reason: errorReason(error), holder };
+  }
+  try {
+    await fsp.lstat(lockPath);
+    return { outcome: 'refused', reason: 'the lock is still present after clearing', holder };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { outcome: 'cleared', holder };
+    return { outcome: 'refused', reason: errorReason(error), holder };
+  }
+}
+
+export async function clearLifecycleLock(homeRoot, {
+  platform = process.platform,
+  identity = {},
+  writer,
+} = {}) {
+  const strategy = lifecycleLockStrategy(platform);
+  const lockPath = strategy === 'file' ? path.join(homeRoot, '.installed.json.lock') : undefined;
+  const base = { homeRoot, strategy, ...(lockPath === undefined ? {} : { lockPath }) };
+  const gatePath = lockPath === undefined ? undefined : `${lockPath}.clear`;
+  let handle;
+  let result;
+  try {
+    let home;
+    try {
+      home = await fsp.stat(homeRoot);
+    } catch (error) {
+      if (error?.code === 'ENOENT') return { ...base, outcome: 'no-home' };
+      throw error;
+    }
+    if (!home.isDirectory()) return { ...base, outcome: 'refused', reason: 'home is not a directory' };
+    if (strategy !== 'file') return { ...base, outcome: 'kernel-managed' };
+    writer ??= createHomeWriter({ root: homeRoot });
+    try {
+      handle = await writer.open(ARTIFACT_ID, gatePath, 'wx');
+    } catch (error) {
+      if (error?.code === 'EEXIST') return { ...base, outcome: 'gate-busy', gatePath };
+      throw error;
+    }
+    await handle.writeFile(`${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })}\n`);
+    result = { ...base, ...await clearHeldGate(lockPath, identity, writer) };
+  } catch (error) {
+    result = { ...base, outcome: 'refused', reason: errorReason(error) };
+  } finally {
+    if (handle) {
+      // The outcome already happened: a gate that cannot be closed must not turn a removed lock into
+      // "nothing was removed". If it also cannot be unlinked, gateLeft below names it.
+      await handle.close().catch(() => {});
+      try {
+        await writer.unlink(ARTIFACT_ID, gatePath);
+      } catch (error) {
+        if (error?.code !== 'ENOENT') result = { ...result, gateLeft: gatePath };
+      }
+    }
+  }
+  return result;
+}

package/cli/lifecycle-lock-inspect.mjs

@@ -0,0 +1,92 @@
+/**
+ * Inspects a lifecycle lock without changing its home or lock file for unlock diagnosis (Plan_65 D11).
+ * A14: a silent holder cannot prove freedom; only a refused connection followed by an exclusive
+ * trial hold can, and a dead file-lock holder still owns the present file until explicit clearing.
+ */
+import fsp from 'node:fs/promises';
+import net from 'node:net';
+import { tryHoldSocket } from '../src/home/lib/kernel-lock.mjs';
+import {
+  holderLiveness, lifecycleLockAddress, lifecycleLockStrategy, parseHolder,
+} from './lifecycle-lock.mjs';
+
+const refusedCodes = new Set(['ECONNREFUSED', 'ENOENT']);
+const errorReason = (error) => error?.code || error?.message || String(error);
+
+function readSocketAnswer(address, timeoutMs, createConnection) {
+  return new Promise((resolve) => {
+    let socket;
+    let timer;
+    let data = '';
+    let settled = false;
+    const finish = (outcome) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket?.destroy();
+      resolve(outcome);
+    };
+    const failed = (error) => finish({
+      kind: refusedCodes.has(error?.code) ? 'refused' : 'error',
+      reason: errorReason(error),
+    });
+    const answered = (line) => {
+      const holder = parseHolder(line);
+      finish(holder ? { kind: 'answer', holder } : { kind: 'malformed', reason: 'malformed holder answer' });
+    };
+    try {
+      socket = createConnection(address);
+      timer = setTimeout(() => finish({ kind: 'timeout', reason: 'holder answer timed out' }), timeoutMs);
+      socket.on('data', (chunk) => {
+        data += chunk.toString('utf8');
+        const newline = data.indexOf('\n');
+        if (newline !== -1) answered(data.slice(0, newline));
+      });
+      socket.once('end', () => answered(data));
+      socket.once('error', failed);
+      socket.once('close', () => finish({ kind: 'error', reason: 'connection closed without a holder answer' }));
+    } catch (error) {
+      failed(error);
+    }
+  });
+}
+
+export async function inspectLifecycleLock(homeRoot, {
+  platform = process.platform,
+  createServer = net.createServer,
+  answerTimeoutMs = 1_000,
+  identity = {},
+  createConnection = net.createConnection,
+} = {}) {
+  const observation = {
+    strategy: lifecycleLockStrategy(platform),
+    homeRoot,
+    observedAt: new Date().toISOString(),
+  };
+  const result = (value) => ({ ...observation, ...value });
+  try {
+    const target = lifecycleLockAddress(homeRoot, { platform });
+    if (target === null) return result({ state: 'no-home' });
+    if (target.strategy === 'file') {
+      let content;
+      try {
+        content = await fsp.readFile(target.address, 'utf8');
+      } catch (error) {
+        if (error?.code === 'ENOENT') return result({ state: 'free' });
+        return result({ state: 'unverified', reason: errorReason(error) });
+      }
+      const holder = parseHolder(content.split(/\r?\n/, 1)[0]);
+      if (!holder) return result({ state: 'unverified', reason: 'malformed holder file' });
+      return result({ state: 'held', holder, liveness: holderLiveness(holder, identity) });
+    }
+    const answer = await readSocketAnswer(target.address, answerTimeoutMs, createConnection);
+    if (answer.kind === 'answer') return result({ state: 'held', holder: answer.holder });
+    if (answer.kind !== 'refused') return result({ state: 'unverified', reason: answer.reason });
+    const release = await tryHoldSocket(target.address, createServer, 'lifecycle lock');
+    if (release === 'in-use') return result({ state: 'held', holder: null });
+    await release();
+    return result({ state: 'free' });
+  } catch (error) {
+    return result({ state: 'unverified', reason: errorReason(error) });
+  }
+}

package/cli/lifecycle-lock.mjs

@@ -0,0 +1,222 @@
+/**
+ * Serializes install, update and uninstall of one shared package home, which several Claude Code
+ * hosts may use at once (Plan_65 D5).
+ *
+ * The shared file lock deletes a lock older than its window, which would steal from an install
+ * paused by sleep or an antivirus scan. Deleting a lock whose holder looks dead is no safer: two
+ * waiters both see holder X gone, A deletes X's lock and takes it, B deletes A's on its stale
+ * observation, and both write (advice A5). So nothing here ever deletes another holder's lock, and
+ * where the kernel can release a lock on the holder's death, the lock is a kernel object: a named
+ * pipe on Windows, an abstract socket on Linux — both reproduced on real machines (hard kill, name
+ * free at once, nothing on disk), which matters on a machine that lost power six times in two weeks.
+ * macOS has no abstract namespace, so it gets an exclusively created file that only its own holder
+ * removes, and a crash leaves it for `codex-bridge unlock --lifecycle` (D8).
+ *
+ * The name comes from the home directory's `dev`+`ino`, not its path: a junction, another letter
+ * case or forward slashes reach the same home and must reach the same lock. A second listen inside
+ * the holder must fail, or the platform did not give exclusivity and the call refuses rather than
+ * switch protocols. What the holder answers a waiter is diagnosis only — it never grants anything.
+ */
+import { randomUUID } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import net from 'node:net';
+import path from 'node:path';
+import { createHomeWriter } from '../src/home/lib/home-write.mjs';
+import {
+  acquireKernelLock, directoryDigest, kernelLockAddress, kernelLockStrategy,
+} from '../src/home/lib/kernel-lock.mjs';
+import { parseJsonText } from '../src/home/lib/json-file.mjs';
+import { processIdentity } from '../src/home/lib/process-identity.mjs';
+
+const ARTIFACT_ID = 'install-record';
+const LOCK_NAME = '.installed.json.lock';
+const TAKEN_CODES = new Set(['EEXIST', 'EPERM', 'EBUSY']);
+const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+function validateOptions(homeRoot, { command, hostRoot, waitMs, retryMs, answerTimeoutMs }) {
+  if (typeof homeRoot !== 'string' || homeRoot.length === 0) throw new TypeError('homeRoot must be a non-empty path');
+  if (typeof command !== 'string' || command.length === 0) throw new TypeError('command must be a non-empty string');
+  if (typeof hostRoot !== 'string' || hostRoot.length === 0) throw new TypeError('hostRoot must be a non-empty path');
+  for (const [name, value, allowZero] of [
+    ['waitMs', waitMs, true], ['retryMs', retryMs, false], ['answerTimeoutMs', answerTimeoutMs, true],
+  ]) {
+    if (!Number.isFinite(value) || value < (allowZero ? 0 : 1)) {
+      throw new TypeError(`${name} must be a ${allowZero ? 'non-negative' : 'positive'} number`);
+    }
+  }
+}
+
+function statIdentity(homeRoot) {
+  try {
+    return directoryDigest(homeRoot);
+  } catch (error) {
+    if (error.message === `${homeRoot} is not a directory`) {
+      throw new Error(`lifecycle lock home is not a directory: ${homeRoot}`);
+    }
+    throw error;
+  }
+}
+
+export function lifecycleLockStrategy(platform = process.platform) {
+  return kernelLockStrategy(platform) ?? 'file';
+}
+
+function lockAddress(homeRoot, digest, platform) {
+  const strategy = lifecycleLockStrategy(platform);
+  const address = kernelLockAddress('lifecycle', digest, platform);
+  return { strategy, address: address ?? path.join(homeRoot, LOCK_NAME) };
+}
+
+export function lifecycleLockAddress(homeRoot, { platform = process.platform } = {}) {
+  const digest = statIdentity(homeRoot);
+  return digest === null ? null : lockAddress(homeRoot, digest, platform);
+}
+
+async function prepareHome(homeRoot) {
+  const writer = createHomeWriter({ root: homeRoot });
+  let digest = statIdentity(homeRoot);
+  if (digest === null) {
+    try {
+      await writer.mkdir(ARTIFACT_ID, homeRoot, { recursive: true });
+    } catch (error) {
+      throw new Error(`could not create lifecycle lock home through the home adapter: ${error.message}`, { cause: error });
+    }
+    digest = statIdentity(homeRoot);
+    if (digest === null) throw new Error(`home adapter did not create lifecycle lock home: ${homeRoot}`);
+  }
+  return { writer, digest };
+}
+
+function validHolder(value) {
+  return value && Number.isInteger(value.pid) && value.pid > 0
+    && typeof value.command === 'string' && value.command.length > 0
+    && typeof value.hostRoot === 'string' && value.hostRoot.length > 0
+    && typeof value.acquiredAt === 'string' && value.acquiredAt.length > 0
+    && typeof value.token === 'string' && value.token.length > 0;
+}
+
+export function parseHolder(line) {
+  try {
+    const holder = parseJsonText('<lifecycle lock holder>', line);
+    return validHolder(holder) ? holder : null;
+  } catch { return null; }
+}
+
+export function holderLiveness(holder, options = {}) {
+  // A14: acquisition is a run-style timestamp, not the holder process's exact start time.
+  return processIdentity({
+    pid: holder.pid,
+    started_at: holder.acquiredAt,
+    ignoreHeartbeat: true,
+    kill: options.kill,
+    probe: options.probe,
+    now: options.now,
+  });
+}
+
+function busyMessage(homeRoot, holder, hint = '') {
+  const details = validHolder(holder)
+    ? `held by ${holder.command} for ${holder.hostRoot}, pid ${holder.pid}, since ${holder.acquiredAt}`
+    : 'the holder did not answer (unverified)';
+  return new Error(`lifecycle lock busy for ${homeRoot}: ${details}; nothing was changed${hint}`);
+}
+
+function lockResult(token, strategy, releaseAction) {
+  let releasePromise;
+  return {
+    token,
+    strategy,
+    release() {
+      if (!releasePromise) releasePromise = releaseAction();
+      return releasePromise;
+    },
+  };
+}
+
+async function acquireSocketLock(homeRoot, holder, {
+  address, strategy, waitMs, retryMs, answerTimeoutMs, createServer,
+}) {
+  const result = await acquireKernelLock({
+    address, holder, waitMs, retryMs, answerTimeoutMs, createServer,
+    parseAnswer: parseHolder,
+    label: 'lifecycle lock',
+  });
+  if (!result.held) throw busyMessage(homeRoot, result.holder);
+  return lockResult(holder.token, strategy, result.release);
+}
+
+async function acquireFileLock(homeRoot, writer, holder, { waitMs, retryMs }) {
+  const lockPath = path.join(homeRoot, LOCK_NAME);
+  const deadline = Date.now() + waitMs;
+  let handle;
+  for (;;) {
+    try {
+      handle = await writer.open(ARTIFACT_ID, lockPath, 'wx');
+      break;
+    } catch (error) {
+      if (!error || !TAKEN_CODES.has(error.code)) throw error;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        let current = null;
+        try { current = parseHolder((await fsp.readFile(lockPath, 'utf8')).split(/\r?\n/, 1)[0]); } catch { /* Diagnosis only. */ }
+        throw busyMessage(
+          homeRoot,
+          current,
+          '. If no install, update or uninstall is running, the lock was left by a crash: codex-bridge unlock --lifecycle',
+        );
+      }
+      await wait(Math.min(retryMs, remaining));
+    }
+  }
+
+  holder.acquiredAt = new Date().toISOString();
+  try {
+    await handle.writeFile(`${JSON.stringify(holder)}\n`);
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await writer.unlink(ARTIFACT_ID, lockPath).catch(() => {});
+    throw error;
+  }
+  return lockResult(holder.token, 'file', async () => {
+    let closeError;
+    try { await handle.close(); } catch (error) { closeError = error; }
+    try {
+      await writer.unlink(ARTIFACT_ID, lockPath);
+    } catch (error) {
+      if (!error || error.code !== 'ENOENT') throw error;
+    }
+    if (closeError) throw closeError;
+  });
+}
+
+export async function acquireLifecycleLock(homeRoot, {
+  command,
+  hostRoot,
+  waitMs = 15_000,
+  retryMs = 100,
+  platform = process.platform,
+  answerTimeoutMs = 1_000,
+  createServer = net.createServer,
+} = {}) {
+  validateOptions(homeRoot, { command, hostRoot, waitMs, retryMs, answerTimeoutMs });
+  const { writer, digest } = await prepareHome(homeRoot);
+  const holder = {
+    pid: process.pid,
+    command,
+    hostRoot,
+    token: randomUUID(),
+  };
+
+  if (platform === 'win32' || platform === 'linux') {
+    const { address, strategy } = lockAddress(homeRoot, digest, platform);
+    return acquireSocketLock(homeRoot, holder, {
+      address,
+      strategy,
+      waitMs,
+      retryMs,
+      answerTimeoutMs,
+      createServer,
+    });
+  }
+  return acquireFileLock(homeRoot, writer, holder, { waitMs, retryMs });
+}

package/cli/lifecycle-transaction.mjs

@@ -0,0 +1,57 @@
+/**
+ * Runs one install, update or uninstall of a shared package home as a single transaction under
+ * the home's lifecycle lock (Plan_65 D8).
+ *
+ * Two installs into one home used to interleave their image copies and their record writes, and
+ * uninstall removed permission rules from settings.json before it had read anything — so a
+ * refused uninstall would already have changed the host. The lock is therefore taken before the
+ * first read, outside the settings backup scope (backup bookkeeping is not exclusion). `update`
+ * nests `install`, and a second acquire inside one process is refused by design (the lock's own
+ * self-check), so the outer transaction hands the nested call a ticket instead: live only while
+ * the transaction runs, and bound to its home.
+ *
+ * Only install may bring a home into existence: the lock needs the directory, and an update or an
+ * uninstall that created an empty home folder just to lock it would leave debris behind a removal.
+ * A home that does not exist has nothing shared to protect, so those run without the lock.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { acquireLifecycleLock } from './lifecycle-lock.mjs';
+
+const liveTickets = new WeakMap();
+
+/**
+ * Throws unless `ticket` belongs to a transaction still running on this host's home. The purge authorization
+ * (Plan_65 D14) binds itself to the ticket through this check, so the two can never disagree about "live".
+ */
+export function assertLiveTicket(ticket, host) {
+  if (!ticket || typeof ticket !== 'object' || !liveTickets.has(ticket)) {
+    throw new Error('lifecycle ticket is no longer active');
+  }
+  if (typeof host?.brandRoot !== 'string' || path.resolve(host.brandRoot) !== liveTickets.get(ticket)) {
+    throw new Error('lifecycle ticket belongs to a different home');
+  }
+}
+
+export async function withLifecycle(host, command, action, { ticket, waitMs, createHome = false } = {}) {
+  if (typeof action !== 'function') throw new TypeError('lifecycle action must be a function');
+
+  if (ticket !== undefined) {
+    assertLiveTicket(ticket, host);
+    return action(ticket);
+  }
+
+  if (!createHome && !fs.existsSync(host.brandRoot)) return action(undefined);
+
+  const lockOptions = { command, hostRoot: host.root };
+  if (waitMs !== undefined) lockOptions.waitMs = waitMs;
+  const lock = await acquireLifecycleLock(host.brandRoot, lockOptions);
+  const transactionTicket = Object.freeze({});
+  liveTickets.set(transactionTicket, path.resolve(host.brandRoot));
+  try {
+    return await action(transactionTicket);
+  } finally {
+    liveTickets.delete(transactionTicket);
+    await lock.release();
+  }
+}

package/cli/link-segments.mjs

@@ -0,0 +1,45 @@
+/**
+ * Says whether a delete target is reached only through real directories below a trusted root.
+ *
+ * Lexical containment alone is satisfiable: independent review replaced `<root>/<project>` with a
+ * junction to an outside directory, and a target that still spelled out as inside the root deleted
+ * what was outside it. Paths are deliberately never resolved (`realpath` returns `\\?\` and UNC
+ * forms on Windows and creates a new class of mismatch), so every segment is checked with lstat,
+ * top-down, right before deletion. Plan_65 D4 made this one module for prune and the coming purge
+ * after prune's own copy was found wrong twice: it walked from the leaf up, touching paths under a
+ * link before reaching the link, and it read every lstat error as a clear path. Only ENOENT means
+ * gone here; any other error is a finding, and the caller keeps the entry. The root itself is taken
+ * as written, because relocating the runs root or the home through a link is legitimate.
+ * Containment compares through normalizePath, which folds Windows case: a root spelled `C:\Users`
+ * against a target resolved as `c:\users` must not read as "outside".
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizePath } from '../src/home/hooks/live-runs.mjs';
+
+export function inspectSegments(target, root, { lstat = (file) => fs.lstatSync(file) } = {}) {
+  const normalizedRoot = normalizePath(root);
+  const normalizedTarget = normalizePath(target);
+  if (!normalizedRoot || !normalizedTarget) return { kind: 'outside' };
+
+  const rootPrefix = normalizedRoot.endsWith('/') ? normalizedRoot : `${normalizedRoot}/`;
+  if (normalizedTarget === normalizedRoot || !normalizedTarget.startsWith(rootPrefix)) {
+    return { kind: 'outside' };
+  }
+
+  const rootPath = path.resolve(root);
+  const relativeTarget = path.relative(rootPath, path.resolve(target));
+  let current = rootPath;
+  for (const segment of relativeTarget.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    let entry;
+    try {
+      entry = lstat(current);
+    } catch (error) {
+      if (error.code === 'ENOENT') return { kind: 'missing', at: current };
+      return { kind: 'error', at: current, code: error.code };
+    }
+    if (entry.isSymbolicLink()) return { kind: 'link', at: current };
+  }
+  return { kind: 'clear' };
+}