phronesis 1.0.0 → 1.1.0

package/src/launcher.js

@@ -0,0 +1,2105 @@
+// Shared launcher.env contract (change 0065 D1). Doctor consumes the read-only
+// inspector without executing a candidate; install/remove below reuse the same paths,
+// parser, serializer, and token rules for atomic no-follow writes.
+
+import { delimiter, dirname, isAbsolute, join, relative, resolve, basename } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { createHash, randomBytes } from 'node:crypto';
+import { constants, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import {
+  lstat,
+  link,
+  mkdir,
+  mkdtemp,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const LAUNCHER_FIELDS = Object.freeze([
+  'PHR_BACKEND',
+  'PHR_VERSION',
+  'PHR_TARGET',
+  'PHR_RUNTIME',
+  'PHR_GENERATION',
+]);
+export const LAUNCHER_BACKENDS = Object.freeze(['app', 'self-copy']);
+const TOKEN_RE = /^[A-Za-z0-9._+-]+$/;
+const STAGING_DIR_RE = /\.staging-[A-Za-z0-9]+$/;
+const CLI_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const DISPATCHER_TEMPLATE = join(CLI_PACKAGE_ROOT, 'templates', 'launcher', 'phronesis');
+export const LAUNCHER_PATH_LINE = 'export PATH="$PATH:$HOME/.phronesis/bin" # phronesis';
+export const FISH_LAUNCHER_PATH_LINE = 'fish_add_path ~/.phronesis/bin';
+
+export function launcherPaths({ home = homedir() } = {}) {
+  const managedDir = join(home, '.phronesis');
+  const binDir = join(managedDir, 'bin');
+  return {
+    managedDir,
+    binDir,
+    dispatcher: join(binDir, 'phronesis'),
+    manifest: join(binDir, 'launcher.env'),
+    lock: join(binDir, '.launcher.lock'),
+    generations: join(home, '.phronesis', 'cli'),
+  };
+}
+
+function decodeValue(raw, field, errors) {
+  if (raw.startsWith('"') || raw.endsWith('"')) {
+    if (!(raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2)) {
+      errors.push(`${field} has mismatched double quotes`);
+      return null;
+    }
+    const inner = raw.slice(1, -1);
+    let out = '';
+    for (let i = 0; i < inner.length; i += 1) {
+      const ch = inner[i];
+      if (ch === '$' || ch === '`') {
+        errors.push(`${field} contains an unescaped shell expansion character`);
+        return null;
+      }
+      if (ch !== '\\') {
+        out += ch;
+        continue;
+      }
+      const next = inner[i + 1];
+      if (!['\\', '"', '$', '`'].includes(next)) {
+        errors.push(`${field} has an invalid escape`);
+        return null;
+      }
+      out += next;
+      i += 1;
+    }
+    return out;
+  }
+  if (raw.startsWith("'") || raw.endsWith("'")) {
+    if (!(raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2)) {
+      errors.push(`${field} has mismatched single quotes`);
+      return null;
+    }
+    const inner = raw.slice(1, -1);
+    if (inner.includes("'")) {
+      errors.push(`${field} has an invalid single-quoted value`);
+      return null;
+    }
+    return inner;
+  }
+  if (/[\s;&|<>$`"']/.test(raw)) {
+    errors.push(`${field} must quote whitespace and shell metacharacters`);
+    return null;
+  }
+  return raw;
+}
+
+export function parseLauncherManifest(text) {
+  const errors = [];
+  const manifest = {};
+  const allowed = new Set(LAUNCHER_FIELDS);
+  for (const [index, line] of String(text ?? '').split(/\r?\n/).entries()) {
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) {
+      errors.push(`line ${index + 1} is not KEY=value`);
+      continue;
+    }
+    const key = line.slice(0, eq);
+    if (!allowed.has(key)) {
+      errors.push(`line ${index + 1} has unknown field ${key}`);
+      continue;
+    }
+    if (Object.hasOwn(manifest, key)) {
+      errors.push(`line ${index + 1} repeats ${key}`);
+      continue;
+    }
+    const value = decodeValue(line.slice(eq + 1), key, errors);
+    if (value !== null) manifest[key] = value;
+  }
+
+  for (const field of LAUNCHER_FIELDS) {
+    if (!Object.hasOwn(manifest, field) || manifest[field] === '') errors.push(`${field} is required`);
+  }
+  if (manifest.PHR_BACKEND && !LAUNCHER_BACKENDS.includes(manifest.PHR_BACKEND)) {
+    errors.push(`PHR_BACKEND must be ${LAUNCHER_BACKENDS.join(' | ')}`);
+  }
+  for (const field of ['PHR_VERSION', 'PHR_GENERATION']) {
+    if (manifest[field] && !TOKEN_RE.test(manifest[field])) {
+      errors.push(`${field} must be a non-empty version/generation token`);
+    }
+  }
+  if (manifest.PHR_GENERATION && /^\.+$/.test(manifest.PHR_GENERATION)) {
+    errors.push('PHR_GENERATION must not be a dot-only token');
+  }
+  for (const field of ['PHR_TARGET', 'PHR_RUNTIME']) {
+    if (manifest[field] && !isAbsolute(manifest[field])) errors.push(`${field} must be an absolute path`);
+  }
+  return { ok: errors.length === 0, manifest, errors };
+}
+
+function quoteValue(value) {
+  const raw = String(value);
+  if (raw && !/[\s;&|<>$`"']/.test(raw)) return raw;
+  return `"${raw.replace(/[\\"$`]/g, (ch) => `\\${ch}`)}"`;
+}
+
+export function serializeLauncherManifest(manifest) {
+  const validation = parseLauncherManifest(
+    LAUNCHER_FIELDS.map((field) => `${field}=${quoteValue(manifest?.[field] ?? '')}`).join('\n'),
+  );
+  if (!validation.ok) throw new Error(`invalid launcher manifest: ${validation.errors.join('; ')}`);
+  return `${LAUNCHER_FIELDS.map((field) => `${field}=${quoteValue(manifest[field])}`).join('\n')}\n`;
+}
+
+function pathState(path) {
+  try {
+    const lst = lstatSync(path);
+    const symlink = lst.isSymbolicLink();
+    let target = lst;
+    if (symlink) {
+      try {
+        target = statSync(path);
+      } catch {
+        target = null;
+      }
+    }
+    return {
+      present: true,
+      symlink,
+      file: Boolean(target?.isFile()),
+      directory: Boolean(target?.isDirectory()),
+      executable: Boolean(target?.isFile() && (target.mode & 0o111)),
+    };
+  } catch {
+    return { present: false, symlink: false, file: false, directory: false, executable: false };
+  }
+}
+
+export function findPathPhronesis(pathEnv = process.env.PATH) {
+  for (const entry of String(pathEnv || '').split(delimiter)) {
+    if (!entry) continue;
+    const candidate = join(resolve(entry), 'phronesis');
+    const state = pathState(candidate);
+    if (state.file && state.executable) return candidate;
+  }
+  return null;
+}
+
+function nearestPackageForTarget(target) {
+  let dir = dirname(target);
+  for (let i = 0; i < 5; i += 1) {
+    const manifestPath = join(dir, 'package.json');
+    try {
+      const manifest = statSync(manifestPath);
+      if (!manifest.isFile()) return null;
+      return { root: dir, packageJson: JSON.parse(readFileSync(manifestPath, 'utf8')) };
+    } catch (error) {
+      if (error?.code !== 'ENOENT') return null;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function packageVersionForTarget(target) {
+  let dir = dirname(target);
+  for (let i = 0; i < 5; i += 1) {
+    try {
+      const parsed = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+      if (typeof parsed.version === 'string' && parsed.version) return parsed.version;
+    } catch {
+      // Preserve the self-copy inspector's existing ancestor-search behavior.
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function phronesisVersionForTarget(target) {
+  const resolved = nearestPackageForTarget(target);
+  if (!resolved || resolved.packageJson?.name !== 'phronesis') return null;
+  const bin = resolved.packageJson.bin;
+  const entry = typeof bin === 'string' ? bin : bin?.phronesis;
+  if (typeof entry !== 'string' || !entry) return null;
+  const lexicalEntry = resolve(resolved.root, entry);
+  const rel = relative(resolved.root, lexicalEntry);
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) return null;
+  try {
+    if (realpathSync(lexicalEntry) !== realpathSync(target)) return null;
+  } catch {
+    return null;
+  }
+  const version = resolved.packageJson.version;
+  return typeof version === 'string' && version ? version : null;
+}
+
+function strictlyContainedBy(parent, child) {
+  try {
+    const rel = relative(realpathSync(parent), realpathSync(child));
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+  } catch {
+    return false;
+  }
+}
+
+export function inspectLauncher({ home = homedir(), pathEnv = process.env.PATH } = {}) {
+  const paths = launcherPaths({ home });
+  const issues = [];
+  const managedDir = pathState(paths.managedDir);
+  const binDir = pathState(paths.binDir);
+  const dispatcher = pathState(paths.dispatcher);
+  const manifestFile = pathState(paths.manifest);
+  const pathCandidate = findPathPhronesis(pathEnv);
+
+  if (managedDir.symlink) issues.push({ code: 'managed-dir-symlink', detail: `${paths.managedDir} is a symlink (non-compliant managed path)` });
+  if (binDir.symlink) issues.push({ code: 'bin-dir-symlink', detail: `${paths.binDir} is a symlink (non-compliant managed path)` });
+
+  if (!dispatcher.present && !manifestFile.present) {
+    issues.push({ code: 'not-installed', detail: 'managed dispatcher and launcher.env are absent' });
+    return {
+      compliant: false,
+      paths,
+      pathCandidate,
+      managedDir,
+      binDir,
+      dispatcher,
+      manifestFile,
+      manifest: null,
+      target: null,
+      runtime: null,
+      generation: null,
+      issues,
+    };
+  }
+  if (!dispatcher.present) issues.push({ code: 'dispatcher-missing', detail: 'managed dispatcher is missing' });
+  else {
+    if (dispatcher.symlink) issues.push({ code: 'dispatcher-symlink', detail: 'managed dispatcher is a symlink (non-compliant)' });
+    if (!dispatcher.file || !dispatcher.executable) issues.push({ code: 'dispatcher-not-executable', detail: 'managed dispatcher is not a regular executable file' });
+  }
+  if (!manifestFile.present) issues.push({ code: 'manifest-missing', detail: 'launcher.env is missing' });
+  else if (manifestFile.symlink) issues.push({ code: 'manifest-symlink', detail: 'launcher.env is a symlink (non-compliant)' });
+  else if (!manifestFile.file) issues.push({ code: 'manifest-not-file', detail: 'launcher.env is not a regular file' });
+
+  let parsed = { ok: false, manifest: {}, errors: [] };
+  if (manifestFile.file) {
+    try {
+      parsed = parseLauncherManifest(readFileSync(paths.manifest, 'utf8'));
+    } catch (err) {
+      parsed = { ok: false, manifest: {}, errors: [`launcher.env unreadable: ${err.message}`] };
+    }
+    for (const error of parsed.errors) issues.push({ code: 'manifest-invalid', detail: error });
+  }
+
+  let target = null;
+  let runtime = null;
+  let generation = null;
+  if (parsed.ok) {
+    target = pathState(parsed.manifest.PHR_TARGET);
+    runtime = pathState(parsed.manifest.PHR_RUNTIME);
+    if (!target.file) issues.push({ code: 'target-missing', detail: `recorded target is missing: ${parsed.manifest.PHR_TARGET}` });
+    if (target.symlink) issues.push({ code: 'target-symlink', detail: `recorded target is a symlink (non-compliant): ${parsed.manifest.PHR_TARGET}` });
+    if (!runtime.file || !runtime.executable) {
+      issues.push({ code: 'runtime-stale', detail: `recorded runtime is missing or not executable: ${parsed.manifest.PHR_RUNTIME}` });
+    }
+
+    if (parsed.manifest.PHR_BACKEND === 'self-copy') {
+      const generationPath = join(paths.generations, parsed.manifest.PHR_GENERATION);
+      generation = { path: generationPath, ...pathState(generationPath) };
+      if (generation.symlink) {
+        issues.push({ code: 'generation-symlink', detail: `generation directory is a symlink (non-compliant): ${generationPath}` });
+      }
+      if (generation.present && !generation.directory) {
+        issues.push({ code: 'generation-not-directory', detail: `recorded generation is not a directory: ${generationPath}` });
+      }
+      if (!generation.present || !generation.directory || generation.symlink || !strictlyContainedBy(generationPath, parsed.manifest.PHR_TARGET)) {
+        issues.push({
+          code: 'torn-generation',
+          detail: `launcher.env names generation ${parsed.manifest.PHR_GENERATION}, but its generation directory/target is missing or inconsistent`,
+        });
+      }
+    }
+
+    const installedVersion = target?.file
+      ? parsed.manifest.PHR_BACKEND === 'app'
+        ? phronesisVersionForTarget(parsed.manifest.PHR_TARGET)
+        : packageVersionForTarget(parsed.manifest.PHR_TARGET)
+      : null;
+    if (parsed.manifest.PHR_BACKEND === 'app') {
+      const expectedGeneration = `app-${parsed.manifest.PHR_VERSION}`;
+      if (parsed.manifest.PHR_GENERATION !== expectedGeneration) {
+        issues.push({
+          code: 'app-generation-incoherent',
+          detail: `app launcher generation ${parsed.manifest.PHR_GENERATION} must equal ${expectedGeneration}`,
+        });
+      }
+      if (!installedVersion) {
+        issues.push({
+          code: 'app-target-version-underivable',
+          detail: `app target package version could not be derived: ${parsed.manifest.PHR_TARGET}`,
+        });
+      }
+    }
+    if (installedVersion && installedVersion !== parsed.manifest.PHR_VERSION) {
+      issues.push({
+        code: 'version-skew',
+        detail: `manifest version ${parsed.manifest.PHR_VERSION} differs from target package version ${installedVersion}`,
+      });
+    }
+  }
+
+  return {
+    compliant: issues.length === 0,
+    paths,
+    pathCandidate,
+    managedDir,
+    binDir,
+    dispatcher,
+    manifestFile,
+    manifest: parsed.ok ? parsed.manifest : null,
+    target,
+    runtime,
+    generation,
+    issues,
+  };
+}
+
+export function launcherStatus({ home = homedir(), pathEnv = process.env.PATH } = {}) {
+  const report = inspectLauncher({ home, pathEnv });
+  return {
+    exists: report.dispatcher.present || report.manifestFile.present,
+    owner: report.manifest?.PHR_BACKEND ?? null,
+    version: report.manifest?.PHR_VERSION ?? null,
+    compliant: report.compliant,
+    issues: report.issues,
+  };
+}
+
+// The write side of the launcher contract lives beside the read side above so every
+// producer consumes the same field serializer, token rules, paths, and inspector.
+
+function launcherWriteError(message) {
+  return new Error(`launcher: ${message}`);
+}
+
+async function stateFor(path) {
+  try {
+    const value = await lstat(path);
+    const testUid = process.env.NODE_ENV === 'test'
+      && process.env.PHRONESIS_TEST_LAUNCHER_UID_PATH === path
+      ? Number(process.env.PHRONESIS_TEST_LAUNCHER_UID)
+      : null;
+    return {
+      present: true,
+      symlink: value.isSymbolicLink(),
+      file: value.isFile(),
+      directory: value.isDirectory(),
+      mode: value.mode,
+      uid: Number.isSafeInteger(testUid) && testUid >= 0 ? testUid : value.uid,
+      mtimeMs: value.mtimeMs,
+      dev: value.dev,
+      ino: value.ino,
+    };
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return {
+        present: false,
+        symlink: false,
+        file: false,
+        directory: false,
+        mode: 0,
+        uid: null,
+        mtimeMs: null,
+        dev: null,
+        ino: null,
+      };
+    }
+    throw error;
+  }
+}
+
+function expectedUid() {
+  return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+
+function assertCurrentOwner(path, current, label = 'managed path') {
+  const uid = expectedUid();
+  if (current.present && uid !== null && current.uid !== uid) {
+    const error = launcherWriteError(
+      `refusing ${label} owned by uid ${current.uid}; current uid is ${uid}. `
+      + `Ask uid ${current.uid} to remove it, or have an administrator chown it to uid ${uid}: ${path}`,
+    );
+    error.code = 'PHR_LAUNCHER_FOREIGN_OWNER';
+    throw error;
+  }
+}
+
+function assertAppMaterialOwner(path, current, label) {
+  const uid = expectedUid();
+  if (current.present && uid !== null && current.uid !== 0 && current.uid !== uid) {
+    const error = launcherWriteError(
+      `refusing ${label} owned by uid ${current.uid}; app read material must be owned by root (uid 0) or current uid ${uid}. `
+      + `Ask uid ${current.uid} or an administrator to reinstall the app for root or uid ${uid}: ${path}`,
+    );
+    error.code = 'PHR_LAUNCHER_FOREIGN_OWNER';
+    throw error;
+  }
+}
+
+function cleanupFailure(error, label) {
+  if (error?.code === 'PHR_LAUNCHER_FOREIGN_OWNER') throw error;
+  return { removed: [], warnings: [`${label} failed: ${error.message}`] };
+}
+
+async function assertTreeOwned(path, label) {
+  const root = await stateFor(path);
+  if (!root.present) return;
+  assertCurrentOwner(path, root, label);
+  if (root.symlink || !root.directory) return;
+  for (const entry of await readdir(path)) {
+    await assertTreeOwned(join(path, entry), label);
+  }
+}
+
+async function ensureDirectoryNoFollow(path, mode = 0o700) {
+  const before = await stateFor(path);
+  if (before.present) {
+    assertCurrentOwner(path, before, 'managed directory');
+    if (before.symlink) throw launcherWriteError(`refusing symlinked managed directory: ${path}`);
+    if (!before.directory) throw launcherWriteError(`managed directory path is not a directory: ${path}`);
+    return;
+  }
+  try {
+    await mkdir(path, { mode });
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+  }
+  const after = await stateFor(path);
+  assertCurrentOwner(path, after, 'managed directory');
+  if (after.symlink || !after.directory) {
+    throw launcherWriteError(`refusing non-directory or symlinked managed path: ${path}`);
+  }
+}
+
+async function ensureManagedTree(paths) {
+  await ensureDirectoryNoFollow(paths.managedDir);
+  await ensureDirectoryNoFollow(paths.binDir);
+  await ensureDirectoryNoFollow(paths.generations);
+}
+
+const UNPARSEABLE_LOCK_STALE_MS = 60 * 1000;
+const LIVE_LOCK_GUIDANCE_MS = 60 * 60 * 1000;
+
+function uniqueSuffix() {
+  return `${process.pid}-${randomBytes(8).toString('hex')}`;
+}
+
+function uniqueStagingSuffix() {
+  return `${process.pid}${randomBytes(8).toString('hex')}`;
+}
+
+function uniqueTempPath(path) {
+  return `${path}.tmp-${uniqueSuffix()}`;
+}
+
+function processIsAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ESRCH') return false;
+    if (error?.code === 'EPERM') return true;
+    return null;
+  }
+}
+
+async function readLockRecordAt(path) {
+  const current = await stateFor(path);
+  if (!current.present) return { current, record: null, text: null };
+  assertCurrentOwner(path, current, 'launcher lifecycle lock');
+  if (current.symlink) throw launcherWriteError(`refusing symlinked launcher lifecycle lock: ${path}`);
+  if (!current.file) throw launcherWriteError(`launcher lifecycle lock is not a regular file: ${path}`);
+  let text;
+  try {
+    text = (await readRegularFileNoFollow(path, 'launcher lifecycle lock')).toString('utf8');
+  } catch (error) {
+    return { current, record: null, text: null, error };
+  }
+  try {
+    return { current, record: JSON.parse(text), text };
+  } catch (error) {
+    return { current, record: null, text, error };
+  }
+}
+
+async function readLockRecord(paths) {
+  return readLockRecordAt(paths.lock);
+}
+
+function lockAge(lock) {
+  const timestamp = Date.parse(lock.record?.created_at);
+  const basis = Number.isFinite(timestamp) ? timestamp : lock.current?.mtimeMs;
+  return Number.isFinite(basis) ? Math.max(0, Date.now() - basis) : null;
+}
+
+function lockDisposition(lock) {
+  const pid = lock.record?.pid;
+  const age = lockAge(lock);
+  if (Number.isSafeInteger(pid) && pid > 0) {
+    const alive = processIsAlive(pid);
+    if (alive === false) return { stale: true, age, alive, reason: `pid ${pid} is not running` };
+    return { stale: false, age, alive, longLived: alive === true && age !== null && age > LIVE_LOCK_GUIDANCE_MS };
+  }
+  return {
+    stale: age !== null && age > UNPARSEABLE_LOCK_STALE_MS,
+    age,
+    alive: null,
+    reason: 'the lock record is empty or unparseable',
+  };
+}
+
+function lockDescription(lock) {
+  const pid = Number.isSafeInteger(lock.record?.pid) ? lock.record.pid : 'unknown';
+  const created = typeof lock.record?.created_at === 'string' ? lock.record.created_at : 'unknown time';
+  return `pid ${pid} since ${created}`;
+}
+
+function lockIdentityMatches(left, right) {
+  return left.current?.dev === right.current?.dev
+    && left.current?.ino === right.current?.ino
+    && left.text === right.text;
+}
+
+function lockHeldError(paths, lock, disposition) {
+  const base = `lifecycle lock is held by ${lockDescription(lock)}: ${paths.lock}`;
+  if (!disposition.longLived) return launcherWriteError(base);
+  const minutes = Math.floor(disposition.age / 60_000);
+  return launcherWriteError(
+    `${base} (alive for about ${minutes} minutes). Verify or stop pid ${lock.record.pid}; `
+    + 'remove the lock manually only after confirming no launcher operation is running.',
+  );
+}
+
+async function restoreRenamedLock(paths, aside) {
+  try {
+    await link(aside, paths.lock);
+    await unlink(aside);
+    await syncDirectory(paths.binDir);
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+    throw launcherWriteError(
+      `lifecycle lock changed during stale-lock takeover; preserved displaced lock at ${aside}`,
+    );
+  }
+}
+
+async function acquireLauncherLock(paths) {
+  const token = uniqueSuffix();
+  const record = { pid: process.pid, created_at: new Date().toISOString(), token };
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    let handle;
+    let created = false;
+    try {
+      handle = await open(
+        paths.lock,
+        noFollowFlags(constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY),
+        0o600,
+      );
+      created = true;
+      await handle.writeFile(`${JSON.stringify(record)}\n`);
+      await handle.sync();
+      await handle.close();
+      await syncDirectory(paths.binDir);
+      await runTestPhase('lock-acquired');
+      return { paths, record };
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      if (created) {
+        const own = await readLockRecord(paths).catch(() => null);
+        if (own?.record?.token === record.token) await unlink(paths.lock).catch(() => {});
+        throw error;
+      }
+      if (error?.code !== 'EEXIST') throw error;
+      const prior = await readLockRecord(paths);
+      const disposition = lockDisposition(prior);
+      if (!disposition.stale) throw lockHeldError(paths, prior, disposition);
+      await runTestPhase('stale-lock-judged');
+      const aside = `${paths.lock}.reaping-${uniqueSuffix()}`;
+      try {
+        await rename(paths.lock, aside);
+      } catch (renameError) {
+        if (renameError?.code === 'ENOENT') continue;
+        throw renameError;
+      }
+      const moved = await readLockRecordAt(aside);
+      if (!lockIdentityMatches(prior, moved)) {
+        await restoreRenamedLock(paths, aside);
+        continue;
+      }
+      console.log(
+        `launcher: taking over stale lifecycle lock held by ${lockDescription(prior)} (${disposition.reason}).`,
+      );
+      await unlink(aside);
+      await syncDirectory(paths.binDir);
+    }
+  }
+  throw launcherWriteError(`could not acquire lifecycle lock after stale-lock takeover: ${paths.lock}`);
+}
+
+async function releaseLauncherLock(lock) {
+  try {
+    const current = await readLockRecord(lock.paths);
+    if (current.record?.token === lock.record.token) {
+      await unlink(lock.paths.lock);
+      await syncDirectory(lock.paths.binDir);
+    }
+  } catch (error) {
+    console.error(`launcher: warning — could not release lifecycle lock: ${error.message}`);
+  }
+}
+
+async function withLauncherLock(paths, operation) {
+  const lock = await acquireLauncherLock(paths);
+  try {
+    return await operation();
+  } finally {
+    await releaseLauncherLock(lock);
+  }
+}
+
+async function runTestPhase(phase) {
+  if (process.env.NODE_ENV !== 'test') return;
+  if (process.env.PHRONESIS_TEST_LAUNCHER_SIGKILL_PHASE === phase) {
+    process.kill(process.pid, 'SIGKILL');
+  }
+  const holdPhases = (process.env.PHRONESIS_TEST_LAUNCHER_HOLD_PHASES || '')
+    .split(',')
+    .filter(Boolean);
+  if (holdPhases.includes(phase)) {
+    const readyDir = process.env.PHRONESIS_TEST_LAUNCHER_READY_DIR;
+    const releaseDir = process.env.PHRONESIS_TEST_LAUNCHER_RELEASE_DIR;
+    if (!readyDir || !releaseDir) {
+      throw launcherWriteError('test hold phases require ready and release directories');
+    }
+    const ready = join(readyDir, `${phase}-${process.pid}`);
+    const release = join(releaseDir, `${phase}-${process.pid}`);
+    await writeFile(ready, `${process.pid}\n`);
+    for (;;) {
+      const released = await stateFor(release);
+      if (released.present) return;
+      await new Promise((resolveWait) => setTimeout(resolveWait, 10));
+    }
+  }
+  if (process.env.PHRONESIS_TEST_LAUNCHER_HOLD_PHASE !== phase) return;
+  const ready = process.env.PHRONESIS_TEST_LAUNCHER_READY_FILE;
+  const release = process.env.PHRONESIS_TEST_LAUNCHER_RELEASE_FILE;
+  if (!ready || !release) throw launcherWriteError('test hold phase requires ready and release files');
+  await writeFile(ready, `${process.pid}\n`);
+  for (;;) {
+    const released = await stateFor(release);
+    if (released.present) return;
+    await new Promise((resolveWait) => setTimeout(resolveWait, 10));
+  }
+}
+
+async function notifyPhase(onPhase, phase) {
+  await onPhase?.(phase);
+  await runTestPhase(phase);
+}
+
+async function syncDirectory(path) {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY);
+    await handle.sync();
+  } catch (error) {
+    // Some supported filesystems do not expose directory fsync. The payload/manifest
+    // file itself is still fsynced before rename; only explicitly unsupported directory
+    // sync is tolerated.
+    if (!['EINVAL', 'ENOTSUP', 'EBADF', 'EISDIR'].includes(error?.code)) throw error;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+function noFollowFlags(base) {
+  return base | (constants.O_NOFOLLOW || 0);
+}
+
+export async function readRegularFileNoFollow(path, label = path) {
+  const before = await stateFor(path);
+  if (before.symlink) throw launcherWriteError(`refusing symlinked ${label}: ${path}`);
+  if (!before.file) throw launcherWriteError(`${label} is not a regular file: ${path}`);
+  const handle = await open(path, noFollowFlags(constants.O_RDONLY));
+  try {
+    return await handle.readFile();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function writeAtomicFile({
+  path,
+  tempPath,
+  bytes,
+  mode,
+  exclusiveTarget = false,
+  onBeforeRename,
+  onBeforeExclusiveCreate,
+  onAfterRename,
+  commitRename,
+}) {
+  if (exclusiveTarget) {
+    // Missing targets are written through the O_EXCL handle itself. There is no
+    // placeholder and no later rename-over: a concurrent creator wins with
+    // EEXIST, while normal write failures remove only the inode created here.
+    await onBeforeRename?.();
+    await onBeforeExclusiveCreate?.();
+    let exclusiveHandle;
+    let createdTarget = null;
+    let completed = false;
+    try {
+      try {
+        exclusiveHandle = await open(
+          path,
+          noFollowFlags(constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY),
+          mode,
+        );
+        createdTarget = await exclusiveHandle.stat();
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error;
+        const conflict = launcherWriteError(`exclusive create refused because target appeared: ${path}`);
+        conflict.code = 'PHR_ATOMIC_TARGET_EXISTS';
+        throw conflict;
+      }
+      await exclusiveHandle.writeFile(bytes);
+      await exclusiveHandle.chmod(mode);
+      await exclusiveHandle.sync();
+      await exclusiveHandle.close();
+      completed = true;
+      await onAfterRename?.();
+      await syncDirectory(dirname(path));
+      return;
+    } finally {
+      await exclusiveHandle?.close().catch(() => {});
+      if (!completed && createdTarget) {
+        const latest = await stateFor(path).catch(() => null);
+        if (latest?.dev === createdTarget.dev && latest?.ino === createdTarget.ino) {
+          await unlink(path).catch(() => {});
+        }
+      }
+    }
+  }
+
+  const handle = await open(
+    tempPath,
+    noFollowFlags(constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY),
+    mode,
+  );
+  let renamed = false;
+  try {
+    await handle.writeFile(bytes);
+    await handle.chmod(mode);
+    await handle.sync();
+
+    const target = await stateFor(path);
+    assertCurrentOwner(path, target, 'managed artifact');
+    if (target.symlink) throw launcherWriteError(`refusing symlinked managed artifact: ${path}`);
+    if (target.present && !target.file) throw launcherWriteError(`managed artifact is not a regular file: ${path}`);
+    if (commitRename) await commitRename();
+    else {
+      await onBeforeRename?.();
+      await rename(tempPath, path);
+    }
+    renamed = true;
+    await onAfterRename?.();
+    await handle.close();
+    await syncDirectory(dirname(path));
+  } finally {
+    await handle.close().catch(() => {});
+    if (!renamed) await unlink(tempPath).catch(() => {});
+  }
+}
+
+// Shared atomic/no-follow primitive for managed files outside the launcher tree.
+// Callers still preflight their own parent-directory ownership/containment rules;
+// this helper owns the final-file race check, fsync, existing-target rename or
+// missing-target exclusive creation, and partial cleanup.
+export async function writeAtomicFileNoFollow({
+  path,
+  bytes,
+  mode = 0o600,
+  exclusiveTarget = false,
+  onBeforeRename,
+  onBeforeExclusiveCreate,
+  onAfterRename,
+}) {
+  return writeAtomicFile({
+    path,
+    tempPath: uniqueTempPath(path),
+    bytes,
+    mode,
+    exclusiveTarget,
+    onBeforeRename,
+    onBeforeExclusiveCreate,
+    onAfterRename,
+  });
+}
+
+async function cleanupStaleLauncherArtifacts(paths) {
+  const removed = [];
+  const warnings = [];
+  const bin = await stateFor(paths.binDir);
+  if (bin.present) {
+    assertCurrentOwner(paths.binDir, bin, 'managed bin directory');
+    for (const entry of await readdir(paths.binDir, { withFileTypes: true })) {
+      if (!/^(?:(?:phronesis|launcher\.env)\.tmp(?:-|$)|\.launcher\.lock\.reaping-)/.test(entry.name)) continue;
+      const candidate = join(paths.binDir, entry.name);
+      try {
+        const current = await stateFor(candidate);
+        assertCurrentOwner(candidate, current, 'stale launcher temporary file');
+        if (current.symlink || !current.file) {
+          warnings.push(`stale cleanup skipped non-file or symlinked artifact: ${candidate}`);
+          continue;
+        }
+        await unlink(candidate);
+        removed.push(candidate);
+      } catch (error) {
+        if (error?.code === 'PHR_LAUNCHER_FOREIGN_OWNER') throw error;
+        warnings.push(`stale cleanup could not remove ${candidate}: ${error.message}`);
+      }
+    }
+  }
+
+  const generations = await stateFor(paths.generations);
+  if (generations.present) {
+    assertCurrentOwner(paths.generations, generations, 'generation directory');
+    for (const entry of await readdir(paths.generations, { withFileTypes: true })) {
+      if (!STAGING_DIR_RE.test(entry.name)) continue;
+      const candidate = join(paths.generations, entry.name);
+      try {
+        const current = await stateFor(candidate);
+        assertCurrentOwner(candidate, current, 'stale staging generation');
+        if (current.symlink || !current.directory) {
+          warnings.push(`stale cleanup skipped non-directory or symlinked staging artifact: ${candidate}`);
+          continue;
+        }
+        await rm(candidate, { recursive: true, force: false });
+        removed.push(candidate);
+      } catch (error) {
+        if (error?.code === 'PHR_LAUNCHER_FOREIGN_OWNER') throw error;
+        warnings.push(`stale cleanup could not remove ${candidate}: ${error.message}`);
+      }
+    }
+  }
+  return { removed, warnings };
+}
+
+async function existingManifestRecord(paths) {
+  const current = await stateFor(paths.manifest);
+  if (!current.present) return { present: false, valid: false, manifest: null, errors: [] };
+  assertCurrentOwner(paths.manifest, current, 'launcher.env');
+  if (current.symlink) throw launcherWriteError(`refusing symlinked launcher.env: ${paths.manifest}`);
+  if (!current.file) throw launcherWriteError(`launcher.env is not a regular file: ${paths.manifest}`);
+  try {
+    const parsed = parseLauncherManifest((await readRegularFileNoFollow(paths.manifest, 'launcher.env')).toString('utf8'));
+    return { present: true, valid: parsed.ok, manifest: parsed.manifest, errors: parsed.errors };
+  } catch (error) {
+    return { present: true, valid: false, manifest: null, errors: [`launcher.env unreadable: ${error.message}`] };
+  }
+}
+
+function parseSemver(value) {
+  const match = String(value).match(
+    /^(?:v)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/,
+  );
+  if (!match) return null;
+  return {
+    core: match.slice(1, 4).map(Number),
+    prerelease: match[4] === undefined ? null : match[4].split('.'),
+  };
+}
+
+export function compareLauncherVersions(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (a.core[i] !== b.core[i]) return a.core[i] < b.core[i] ? -1 : 1;
+  }
+  if (a.prerelease === null && b.prerelease === null) return 0;
+  if (a.prerelease === null) return 1;
+  if (b.prerelease === null) return -1;
+  const length = Math.max(a.prerelease.length, b.prerelease.length);
+  for (let i = 0; i < length; i += 1) {
+    const av = a.prerelease[i];
+    const bv = b.prerelease[i];
+    if (av === undefined) return -1;
+    if (bv === undefined) return 1;
+    if (av === bv) continue;
+    const an = /^\d+$/.test(av);
+    const bn = /^\d+$/.test(bv);
+    if (an && bn) {
+      const ai = BigInt(av);
+      const bi = BigInt(bv);
+      if (ai !== bi) return ai < bi ? -1 : 1;
+      continue;
+    }
+    if (an !== bn) return an ? -1 : 1;
+    return av < bv ? -1 : 1;
+  }
+  return 0;
+}
+
+async function packageDescriptor(packageRoot) {
+  const manifestPath = join(packageRoot, 'package.json');
+  const packageJson = JSON.parse((await readRegularFileNoFollow(manifestPath, 'CLI package.json')).toString('utf8'));
+  if (packageJson.name !== 'phronesis') {
+    throw launcherWriteError(`source package must be named phronesis (got ${JSON.stringify(packageJson.name)})`);
+  }
+  if (!TOKEN_RE.test(packageJson.version || '') || /^\.+$/.test(packageJson.version)) {
+    throw launcherWriteError(`source package has an invalid launcher version token: ${JSON.stringify(packageJson.version)}`);
+  }
+  const entry = typeof packageJson.bin === 'string' ? packageJson.bin : packageJson.bin?.phronesis;
+  if (typeof entry !== 'string' || !entry) {
+    throw launcherWriteError('source package does not declare bin.phronesis');
+  }
+  const lexicalEntry = resolve(packageRoot, entry);
+  const rel = relative(packageRoot, lexicalEntry);
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) {
+    throw launcherWriteError(`bin.phronesis escapes the source package: ${entry}`);
+  }
+  return { name: packageJson.name, version: packageJson.version, entry };
+}
+
+function runSubprocess(command, args, { cwd, env = {} } = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env: { ...process.env, ...env },
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) {
+    const detail = [result.error?.message, result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+    throw launcherWriteError(`${command} ${args.join(' ')} failed${detail ? `: ${detail}` : ''}`);
+  }
+  return result;
+}
+
+export async function resolveNpmCommand(runtime = process.execPath) {
+  const canonical = realpathSync(runtime);
+  const adjacent = join(dirname(canonical), process.platform === 'win32' ? 'npm.cmd' : 'npm');
+  try {
+    const candidate = await stat(adjacent);
+    if (candidate.isFile() && (process.platform === 'win32' || candidate.mode & 0o111)) return adjacent;
+  } catch {
+    // Fall through to PATH resolution when this runtime does not ship npm beside node.
+  }
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+export async function materializePackageClosure({
+  packageRoot,
+  stagingDir,
+  home = homedir(),
+  npmCommand,
+  runtime = process.execPath,
+} = {}) {
+  const npm = npmCommand || await resolveNpmCommand(runtime);
+  const runtimePath = [dirname(realpathSync(runtime)), process.env.PATH]
+    .filter((entry) => typeof entry === 'string' && entry.length > 0)
+    .join(delimiter);
+  const packDir = await mkdtemp(join(tmpdir(), 'phronesis-launcher-pack-'));
+  try {
+    // This is the same npm-materialized closure used by verify-installability.mjs:
+    // a local package tarball is installed into a clean prefix so npm resolves and
+    // lays out the complete production dependency tree. Lifecycle scripts are not
+    // needed by Phronesis's pure-JS closure and are disabled at both boundaries.
+    runSubprocess(
+      npm,
+      ['pack', packageRoot, '--ignore-scripts', '--pack-destination', packDir],
+      {
+        cwd: packageRoot,
+        env: {
+          HOME: home,
+          PATH: runtimePath,
+          npm_config_audit: 'false',
+          npm_config_fund: 'false',
+          npm_config_update_notifier: 'false',
+        },
+      },
+    );
+    const tarballs = (await readdir(packDir)).filter((name) => name.endsWith('.tgz'));
+    if (tarballs.length !== 1) {
+      throw launcherWriteError(`npm pack produced ${tarballs.length} tarballs (expected exactly one)`);
+    }
+    runSubprocess(
+      npm,
+      [
+        'install',
+        '--prefix',
+        stagingDir,
+        '--omit=dev',
+        '--ignore-scripts',
+        '--no-audit',
+        '--no-fund',
+        '--package-lock=false',
+        join(packDir, tarballs[0]),
+      ],
+      {
+        cwd: stagingDir,
+        env: {
+          HOME: home,
+          PATH: runtimePath,
+          npm_config_update_notifier: 'false',
+        },
+      },
+    );
+  } finally {
+    await rm(packDir, { recursive: true, force: true });
+  }
+}
+
+async function validateGeneration({ generationDir, descriptor, runtime, home }) {
+  const generationState = await stateFor(generationDir);
+  assertCurrentOwner(generationDir, generationState, 'staged generation');
+  if (generationState.symlink || !generationState.directory) {
+    throw launcherWriteError(`staged generation is missing, non-directory, or symlinked: ${generationDir}`);
+  }
+  const packageRoot = join(generationDir, 'node_modules', descriptor.name);
+  const packageFile = join(packageRoot, 'package.json');
+  const entry = resolve(packageRoot, descriptor.entry);
+  const rel = relative(packageRoot, entry);
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) {
+    throw launcherWriteError(`staged CLI entry escapes its package tree: ${entry}`);
+  }
+
+  const packageState = await stateFor(packageFile);
+  assertCurrentOwner(packageFile, packageState, 'staged CLI package.json');
+  const packageJson = JSON.parse((await readRegularFileNoFollow(packageFile, 'staged CLI package.json')).toString('utf8'));
+  if (packageJson.name !== descriptor.name || packageJson.version !== descriptor.version) {
+    throw launcherWriteError(
+      `staged CLI package mismatch (expected ${descriptor.name}@${descriptor.version}, got ${packageJson.name}@${packageJson.version})`,
+    );
+  }
+  const entryState = await stateFor(entry);
+  assertCurrentOwner(entry, entryState, 'staged CLI entry');
+  if (entryState.symlink || !entryState.file) {
+    throw launcherWriteError(`staged CLI entry is missing, non-regular, or symlinked: ${entry}`);
+  }
+  const probe = spawnSync(runtime, [entry, '--version'], {
+    cwd: generationDir,
+    env: { ...process.env, HOME: home, PATH: '', NO_COLOR: '1' },
+    encoding: 'utf8',
+    maxBuffer: 4 * 1024 * 1024,
+  });
+  if (probe.error || probe.status !== 0 || probe.stdout.trim() !== descriptor.version) {
+    const detail = [probe.error?.message, probe.stdout, probe.stderr].filter(Boolean).join('\n').trim();
+    throw launcherWriteError(
+      `staged CLI integrity probe failed (expected --version ${descriptor.version})${detail ? `: ${detail}` : ''}`,
+    );
+  }
+  return entry;
+}
+
+async function canonicalRuntime(runtimePath) {
+  let canonical;
+  try {
+    canonical = realpathSync(runtimePath);
+  } catch (error) {
+    throw launcherWriteError(`runtime cannot be canonicalized: ${runtimePath} (${error.message})`);
+  }
+  const runtimeState = await stat(canonical).catch(() => null);
+  if (!runtimeState?.isFile() || !(runtimeState.mode & 0o111)) {
+    throw launcherWriteError(`canonical runtime is missing or not executable: ${canonical}`);
+  }
+  return canonical;
+}
+
+async function removeGenerationPath(path, paths, label = 'generation') {
+  if (dirname(path) !== paths.generations) {
+    throw launcherWriteError(`refusing to remove ${label} outside ${paths.generations}: ${path}`);
+  }
+  const current = await stateFor(path);
+  if (!current.present) return false;
+  assertCurrentOwner(path, current, label);
+  if (current.symlink) throw launcherWriteError(`refusing symlinked ${label}: ${path}`);
+  if (!current.directory) throw launcherWriteError(`${label} is not a directory: ${path}`);
+  await rm(path, { recursive: true, force: false });
+  return true;
+}
+
+async function prepareGeneration({
+  paths,
+  descriptor,
+  runtime,
+  home,
+  prior,
+  onPhase,
+  materialize,
+  npmCommand,
+}) {
+  const generationDir = join(paths.generations, descriptor.version);
+  const suffix = uniqueSuffix();
+  const stagingDir = join(paths.generations, `${descriptor.version}.staging-${uniqueStagingSuffix()}`);
+  const payloadName = `payload-${suffix}`;
+  const stagedPayload = join(stagingDir, payloadName);
+  const priorGeneration = prior.valid && prior.manifest.PHR_BACKEND === 'self-copy'
+    ? prior.manifest.PHR_GENERATION
+    : null;
+
+  const existing = await stateFor(generationDir);
+  if (existing.present) {
+    assertCurrentOwner(generationDir, existing, 'generation path');
+    if (existing.symlink) throw launcherWriteError(`refusing symlinked generation path: ${generationDir}`);
+    if (!existing.directory) throw launcherWriteError(`generation path is not a directory: ${generationDir}`);
+    if (priorGeneration !== descriptor.version) await removeGenerationPath(generationDir, paths);
+  }
+
+  await notifyPhase(onPhase, 'before-stage-create');
+  await mkdir(stagingDir, { mode: 0o700 });
+  try {
+    await mkdir(stagedPayload, { mode: 0o700 });
+    await notifyPhase(onPhase, 'after-stage-create');
+    await materialize({
+      packageRoot: descriptor.packageRoot,
+      stagingDir: stagedPayload,
+      home,
+      npmCommand,
+      runtime,
+    });
+    await notifyPhase(onPhase, 'after-stage-materialize');
+    await assertTreeOwned(stagingDir, 'staged generation artifact');
+    const stagedTarget = await validateGeneration({
+      generationDir: stagedPayload,
+      descriptor,
+      runtime,
+      home,
+    });
+    await notifyPhase(onPhase, 'after-integrity-check');
+
+    const destination = await stateFor(generationDir);
+    assertCurrentOwner(generationDir, destination, 'generation path');
+    let target;
+    if (!destination.present) {
+      await rename(stagingDir, generationDir);
+      target = join(generationDir, relative(stagingDir, stagedTarget));
+    } else {
+      if (destination.symlink || !destination.directory) {
+        throw launcherWriteError(`generation path became symlinked or non-directory during staging: ${generationDir}`);
+      }
+      const finalPayload = join(generationDir, payloadName);
+      const payloadState = await stateFor(finalPayload);
+      if (payloadState.present) throw launcherWriteError(`generation payload appeared during staging: ${finalPayload}`);
+      await rename(stagedPayload, finalPayload);
+      await rm(stagingDir, { recursive: true, force: false });
+      target = join(finalPayload, relative(stagedPayload, stagedTarget));
+    }
+    await syncDirectory(paths.generations);
+    await notifyPhase(onPhase, 'after-generation-rename');
+    return { generationDir, target, payloadName, reused: false };
+  } catch (error) {
+    await removeGenerationPath(stagingDir, paths, 'staging generation').catch(() => {});
+    throw error;
+  }
+}
+
+async function cleanupOrphanPayloads(paths) {
+  const removed = [];
+  const warnings = [];
+  const initial = await existingManifestRecord(paths);
+  if (!initial.valid || initial.manifest.PHR_BACKEND !== 'self-copy') return { removed, warnings };
+  const generationDir = join(paths.generations, initial.manifest.PHR_GENERATION);
+  const current = await stateFor(generationDir);
+  if (!current.present || current.symlink || !current.directory) return { removed, warnings };
+  assertCurrentOwner(generationDir, current, 'generation path');
+  for (const entry of await readdir(generationDir, { withFileTypes: true })) {
+    if (!entry.name.startsWith('payload-')) continue;
+    const candidate = join(generationDir, entry.name);
+    try {
+      // Re-read at the destructive edge even though the lifecycle lock excludes
+      // cooperating writers. The manifest bytes being honored decide liveness.
+      const latest = await existingManifestRecord(paths);
+      if (!latest.valid || latest.manifest.PHR_BACKEND !== 'self-copy') {
+        warnings.push('payload cleanup stopped because launcher.env is absent, invalid, or no longer self-copy');
+        break;
+      }
+      const latestGeneration = join(paths.generations, latest.manifest.PHR_GENERATION);
+      if (latestGeneration !== generationDir) break;
+      if (strictlyContainedBy(candidate, latest.manifest.PHR_TARGET)) continue;
+      const payload = await stateFor(candidate);
+      assertCurrentOwner(candidate, payload, 'orphan generation payload');
+      if (payload.symlink || !payload.directory) {
+        warnings.push(`payload cleanup skipped non-directory or symlinked artifact: ${candidate}`);
+        continue;
+      }
+      await rm(candidate, { recursive: true, force: false });
+      removed.push(candidate);
+    } catch (error) {
+      if (error?.code === 'PHR_LAUNCHER_FOREIGN_OWNER') throw error;
+      warnings.push(`payload cleanup could not remove ${candidate}: ${error.message}`);
+    }
+  }
+  return { removed, warnings };
+}
+
+function collisionRecord(prior, dispatcher) {
+  if (!prior.present) {
+    return dispatcher?.present
+      ? { kind: 'unowned dispatcher', owner: 'none', version: 'unknown' }
+      : null;
+  }
+  if (!prior.valid) {
+    return {
+      kind: 'unrecognized manifest',
+      owner: prior.manifest?.PHR_BACKEND || 'unrecognized',
+      version: prior.manifest?.PHR_VERSION || 'unknown',
+    };
+  }
+  return {
+    kind: 'recognized manifest',
+    owner: prior.manifest?.PHR_BACKEND || 'invalid',
+    version: prior.manifest?.PHR_VERSION || 'unknown',
+  };
+}
+
+async function assertExpectedPrior(paths, prior, expectedPrior) {
+  if (!expectedPrior) return;
+  const dispatcher = await stateFor(paths.dispatcher);
+  if (expectedPrior.absent === true) {
+    if (!prior.present && !dispatcher.present) return;
+    const actual = prior.valid
+      ? `${prior.manifest.PHR_BACKEND}@${prior.manifest.PHR_VERSION}`
+      : prior.present ? 'unrecognized-manifest' : 'unowned-dispatcher';
+    throw launcherWriteError(`slot-changed-since-disclosure: expected absent; found ${actual}`);
+  }
+  if (
+    prior.valid
+    && prior.manifest.PHR_BACKEND === expectedPrior.owner
+    && prior.manifest.PHR_VERSION === expectedPrior.version
+  ) return;
+  const actual = prior.valid
+    ? `${prior.manifest.PHR_BACKEND}@${prior.manifest.PHR_VERSION}`
+    : prior.present ? 'unrecognized-manifest' : dispatcher.present ? 'unowned-dispatcher' : 'absent';
+  throw launcherWriteError(
+    `slot-changed-since-disclosure: expected ${expectedPrior.owner}@${expectedPrior.version}; found ${actual}`,
+  );
+}
+
+async function preflightInstall({
+  paths,
+  descriptor,
+  backend = 'self-copy',
+  prior,
+  forceLauncher,
+  reconcileAppOwner = false,
+  dispatcherTemplate,
+}) {
+  if (prior.present && !prior.valid && !forceLauncher) {
+    throw launcherWriteError(`existing launcher.env is invalid (${prior.errors.join('; ')}); use --force-launcher to replace it`);
+  }
+  if (prior.valid && prior.manifest.PHR_BACKEND !== backend && !forceLauncher) {
+    throw launcherWriteError(
+      `launcher slot is owned by ${prior.manifest.PHR_BACKEND}@${prior.manifest.PHR_VERSION}; use --force-launcher to replace it`,
+    );
+  }
+  if (prior.valid) {
+    const order = compareLauncherVersions(descriptor.version, prior.manifest.PHR_VERSION);
+    if (order === null && descriptor.version !== prior.manifest.PHR_VERSION && !forceLauncher && !reconcileAppOwner) {
+      throw launcherWriteError(
+        `cannot compare installed version ${prior.manifest.PHR_VERSION} with ${descriptor.version}; use --force-launcher to replace it`,
+      );
+    }
+    if (order !== null && order < 0 && !forceLauncher && !reconcileAppOwner) {
+      throw launcherWriteError(
+        `downgrade from ${prior.manifest.PHR_VERSION} to ${descriptor.version} refused; use --force-launcher to continue`,
+      );
+    }
+  }
+
+  const dispatcher = await stateFor(paths.dispatcher);
+  assertCurrentOwner(paths.dispatcher, dispatcher, 'dispatcher');
+  if (dispatcher.symlink) throw launcherWriteError(`refusing symlinked dispatcher: ${paths.dispatcher}`);
+  if (dispatcher.present && !dispatcher.file) {
+    throw launcherWriteError(`dispatcher path is not a regular file: ${paths.dispatcher}`);
+  }
+  if (dispatcher.file && !prior.present) {
+    const existing = await readRegularFileNoFollow(paths.dispatcher, 'dispatcher');
+    if (!existing.equals(dispatcherTemplate) && !forceLauncher) {
+      throw launcherWriteError(`launcher slot contains an unowned dispatcher; use --force-launcher to replace it`);
+    }
+  }
+  return dispatcher;
+}
+
+async function installDispatcher({ paths, template, onPhase }) {
+  await writeAtomicFile({
+    path: paths.dispatcher,
+    tempPath: uniqueTempPath(paths.dispatcher),
+    bytes: template,
+    mode: 0o755,
+    onBeforeRename: async () => notifyPhase(onPhase, 'before-dispatcher-rename'),
+  });
+  await notifyPhase(onPhase, 'after-dispatcher-rename');
+}
+
+async function verifyManifestTargetForCommit(paths, manifest) {
+  if (manifest.PHR_BACKEND === 'app') {
+    const target = await stateFor(manifest.PHR_TARGET);
+    assertAppMaterialOwner(manifest.PHR_TARGET, target, 'app target');
+    if (target.symlink || !target.file) {
+      throw launcherWriteError(`pre-commit app target is missing, non-regular, or symlinked: ${manifest.PHR_TARGET}`);
+    }
+    const runtime = await stateFor(manifest.PHR_RUNTIME);
+    assertAppMaterialOwner(manifest.PHR_RUNTIME, runtime, 'app runtime');
+    if (runtime.symlink || !runtime.file || !(runtime.mode & 0o111)) {
+      throw launcherWriteError(`pre-commit app runtime is missing, non-executable, non-regular, or symlinked: ${manifest.PHR_RUNTIME}`);
+    }
+    return;
+  }
+  const generationDir = join(paths.generations, manifest.PHR_GENERATION);
+  const generation = await stateFor(generationDir);
+  assertCurrentOwner(generationDir, generation, 'generation path');
+  if (generation.symlink || !generation.directory) {
+    throw launcherWriteError(`pre-commit generation is missing, non-directory, or symlinked: ${generationDir}`);
+  }
+  const target = await stateFor(manifest.PHR_TARGET);
+  assertCurrentOwner(manifest.PHR_TARGET, target, 'staged CLI target');
+  if (target.symlink || !target.file) {
+    throw launcherWriteError(`pre-commit target is missing, non-regular, or symlinked: ${manifest.PHR_TARGET}`);
+  }
+  if (!strictlyContainedBy(generationDir, manifest.PHR_TARGET)) {
+    throw launcherWriteError(`pre-commit target escapes generation ${generationDir}: ${manifest.PHR_TARGET}`);
+  }
+}
+
+async function commitManifest({ paths, manifest, onPhase }) {
+  let committed = false;
+  const manifestTmp = uniqueTempPath(paths.manifest);
+  const handle = await open(
+    manifestTmp,
+    noFollowFlags(constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY),
+    0o600,
+  );
+  try {
+    await handle.writeFile(serializeLauncherManifest(manifest));
+    await handle.sync();
+    await notifyPhase(onPhase, 'after-manifest-fsync');
+    const current = await stateFor(paths.manifest);
+    assertCurrentOwner(paths.manifest, current, 'launcher.env');
+    if (current.symlink) throw launcherWriteError(`refusing symlinked launcher.env: ${paths.manifest}`);
+    if (current.present && !current.file) throw launcherWriteError(`launcher.env is not a regular file: ${paths.manifest}`);
+    await notifyPhase(onPhase, 'before-manifest-rename');
+    await verifyManifestTargetForCommit(paths, manifest);
+    await runTestPhase('immediately-before-manifest-rename');
+    await rename(manifestTmp, paths.manifest);
+    committed = true;
+    await runTestPhase('immediately-after-manifest-rename');
+    await handle.close();
+    await syncDirectory(paths.binDir);
+    await notifyPhase(onPhase, 'after-manifest-rename');
+  } finally {
+    await handle.close().catch(() => {});
+    if (!committed) await unlink(manifestTmp).catch(() => {});
+  }
+  return committed;
+}
+
+async function garbageCollectLauncherGenerationsUnlocked(paths, { cleanStale = false } = {}) {
+  const removed = [];
+  const warnings = [];
+  await assertTreeOwned(paths.binDir, 'managed launcher artifact');
+  await assertTreeOwned(paths.generations, 'managed generation artifact');
+  if (cleanStale) {
+    const stale = await cleanupStaleLauncherArtifacts(paths);
+    removed.push(...stale.removed);
+    warnings.push(...stale.warnings);
+  }
+  const generationsState = await stateFor(paths.generations);
+  if (!generationsState.present) return { removed, warnings };
+  assertCurrentOwner(paths.generations, generationsState, 'generation directory');
+  if (generationsState.symlink || !generationsState.directory) {
+    return { removed, warnings: [`refusing GC: ${paths.generations} is symlinked or not a directory`] };
+  }
+
+  let prior;
+  try {
+    prior = await existingManifestRecord(paths);
+  } catch (error) {
+    return { removed, warnings: [`refusing GC: ${error.message}`] };
+  }
+  if (prior.present && !prior.valid) {
+    return { removed, warnings: [`refusing GC while launcher.env is invalid: ${prior.errors.join('; ')}`] };
+  }
+  const payloadCleanup = await cleanupOrphanPayloads(paths);
+  removed.push(...payloadCleanup.removed);
+  warnings.push(...payloadCleanup.warnings);
+  const referenced = prior.valid && prior.manifest.PHR_BACKEND === 'self-copy'
+    ? prior.manifest.PHR_GENERATION
+    : null;
+
+  for (const entry of await readdir(paths.generations, { withFileTypes: true })) {
+    if (entry.name === referenced || STAGING_DIR_RE.test(entry.name)) continue;
+    if (!TOKEN_RE.test(entry.name) || /^\.+$/.test(entry.name)) continue;
+    const candidate = join(paths.generations, entry.name);
+    try {
+      const latest = await existingManifestRecord(paths);
+      if (latest.present && !latest.valid) {
+        warnings.push(`GC stopped because launcher.env became invalid: ${latest.errors.join('; ')}`);
+        break;
+      }
+      const latestReference = latest.valid && latest.manifest.PHR_BACKEND === 'self-copy'
+        ? latest.manifest.PHR_GENERATION
+        : null;
+      if (entry.name === latestReference) continue;
+      const current = await stateFor(candidate);
+      assertCurrentOwner(candidate, current, 'generation path');
+      if (current.symlink || !current.directory) {
+        warnings.push(`GC skipped non-directory or symlinked generation: ${candidate}`);
+        continue;
+      }
+      await removeGenerationPath(candidate, paths);
+      removed.push(candidate);
+    } catch (error) {
+      if (error?.code === 'PHR_LAUNCHER_FOREIGN_OWNER') throw error;
+      warnings.push(`GC could not remove ${candidate}: ${error.message}`);
+    }
+  }
+  return { removed, warnings };
+}
+
+export async function garbageCollectLauncherGenerations({ home = homedir() } = {}) {
+  const paths = launcherPaths({ home });
+  const managed = await stateFor(paths.managedDir);
+  if (!managed.present) return { removed: [], warnings: [] };
+  await ensureManagedTree(paths);
+  return withLauncherLock(paths, () => garbageCollectLauncherGenerationsUnlocked(paths, { cleanStale: true }));
+}
+
+async function canonicalAppFile(path, { label, executable = false } = {}) {
+  if (typeof path !== 'string' || !isAbsolute(path)) {
+    throw launcherWriteError(`${label} must be an absolute path: ${String(path)}`);
+  }
+  const lexical = await stateFor(path);
+  assertAppMaterialOwner(path, lexical, label);
+  if (lexical.symlink || !lexical.file || (executable && !(lexical.mode & 0o111))) {
+    const requirement = executable ? 'regular executable file' : 'regular file';
+    throw launcherWriteError(`${label} is not a ${requirement}: ${path}`);
+  }
+  let canonical;
+  try {
+    canonical = realpathSync(path);
+  } catch (error) {
+    throw launcherWriteError(`${label} cannot be canonicalized: ${path} (${error.message})`);
+  }
+  const resolved = await stateFor(canonical);
+  assertAppMaterialOwner(canonical, resolved, `canonical ${label}`);
+  if (resolved.symlink || !resolved.file || (executable && !(resolved.mode & 0o111))) {
+    const requirement = executable ? 'regular executable file' : 'regular file';
+    throw launcherWriteError(`canonical ${label} is not a ${requirement}: ${canonical}`);
+  }
+  return canonical;
+}
+
+function appVersionDescriptor(target, assertedVersion) {
+  const version = phronesisVersionForTarget(target);
+  if (!version) {
+    throw launcherWriteError(`app-target-version-underivable: target is not the declared bin.phronesis of a readable phronesis package: ${target}`);
+  }
+  if (!TOKEN_RE.test(version) || /^\.+$/.test(version)) {
+    throw launcherWriteError(`app target package has an invalid launcher version token: ${JSON.stringify(version)}`);
+  }
+  if (assertedVersion !== undefined && assertedVersion !== version) {
+    throw launcherWriteError(
+      `--app-version assertion ${JSON.stringify(assertedVersion)} does not match target package version ${JSON.stringify(version)}`,
+    );
+  }
+  return { version };
+}
+
+async function existingAppOwnerForRestamp(paths) {
+  for (const [path, label] of [
+    [paths.managedDir, 'managed directory'],
+    [paths.binDir, 'managed bin directory'],
+  ]) {
+    const current = await stateFor(path);
+    if (!current.present) return false;
+    assertCurrentOwner(path, current, label);
+    if (current.symlink) throw launcherWriteError(`refusing symlinked ${label}: ${path}`);
+    if (!current.directory) throw launcherWriteError(`${label} is not a directory: ${path}`);
+  }
+  const prior = await existingManifestRecord(paths);
+  return prior.valid && prior.manifest.PHR_BACKEND === 'app';
+}
+
+function sameManifest(left, right) {
+  return LAUNCHER_FIELDS.every((field) => left?.[field] === right?.[field]);
+}
+
+export async function installLauncher({
+  home = homedir(),
+  forceLauncher = false,
+  backend = 'self-copy',
+  packageRoot = CLI_PACKAGE_ROOT,
+  runtime = process.execPath,
+  appTarget,
+  appRuntime,
+  appVersion,
+  ifOwned = false,
+  expectedPrior = null,
+  onPhase,
+  materialize = materializePackageClosure,
+} = {}) {
+  if (!LAUNCHER_BACKENDS.includes(backend)) {
+    throw launcherWriteError(`backend must be ${LAUNCHER_BACKENDS.join(' | ')} (got ${JSON.stringify(backend)})`);
+  }
+  if (ifOwned && backend !== 'app') {
+    throw launcherWriteError('--if-owned is only valid for the app backend');
+  }
+  if (ifOwned && expectedPrior !== null) {
+    throw launcherWriteError('--if-owned cannot be combined with expected prior disclosure binding');
+  }
+  if (expectedPrior !== null) {
+    const expectsAbsent = expectedPrior?.absent === true
+      && expectedPrior?.owner === undefined
+      && expectedPrior?.version === undefined;
+    const expectsIdentity = LAUNCHER_BACKENDS.includes(expectedPrior?.owner)
+      && typeof expectedPrior?.version === 'string'
+      && expectedPrior.version.length > 0;
+    if (!expectsAbsent && !expectsIdentity) {
+      throw launcherWriteError('expected prior must be { absent: true } or { owner: app|self-copy, version }');
+    }
+  }
+  const paths = launcherPaths({ home });
+  let descriptor;
+  let canonicalPackageRoot;
+  let canonicalRecordedRuntime;
+  let canonicalTarget = null;
+  if (backend === 'app') {
+    canonicalTarget = await canonicalAppFile(appTarget, { label: 'app target' });
+    canonicalRecordedRuntime = await canonicalAppFile(appRuntime, { label: 'app runtime', executable: true });
+    descriptor = appVersionDescriptor(canonicalTarget, appVersion);
+    if (ifOwned && !(await existingAppOwnerForRestamp(paths))) {
+      return {
+        paths,
+        manifest: null,
+        npmCommand: null,
+        generationDir: null,
+        reusedGeneration: false,
+        replaced: null,
+        gcRemoved: [],
+        warnings: [],
+        skipped: 'not-app-owned',
+      };
+    }
+  } else {
+    if (appTarget !== undefined || appRuntime !== undefined || appVersion !== undefined || ifOwned) {
+      throw launcherWriteError('app backend options require --backend app');
+    }
+  }
+  await ensureManagedTree(paths);
+  return withLauncherLock(paths, async () => {
+    await assertTreeOwned(paths.binDir, 'managed launcher artifact');
+    await assertTreeOwned(paths.generations, 'managed generation artifact');
+    const stale = await cleanupStaleLauncherArtifacts(paths);
+    let npmCommand = null;
+    if (backend === 'self-copy') {
+      // Keep the core-0070 self-copy resolution and npm discovery inside the lifecycle
+      // lock and in their original order. App mode never enters this staging path.
+      canonicalPackageRoot = realpathSync(packageRoot);
+      descriptor = { ...(await packageDescriptor(canonicalPackageRoot)), packageRoot: canonicalPackageRoot };
+      canonicalRecordedRuntime = await canonicalRuntime(runtime);
+      npmCommand = await resolveNpmCommand(canonicalRecordedRuntime);
+    }
+    const prior = await existingManifestRecord(paths);
+    await assertExpectedPrior(paths, prior, expectedPrior);
+    if (ifOwned && (!prior.valid || prior.manifest.PHR_BACKEND !== 'app')) {
+      return {
+        paths,
+        manifest: null,
+        npmCommand: null,
+        generationDir: null,
+        reusedGeneration: false,
+        replaced: null,
+        gcRemoved: [],
+        warnings: stale.warnings,
+        skipped: 'not-app-owned',
+      };
+    }
+    const template = await readRegularFileNoFollow(DISPATCHER_TEMPLATE, 'shipped dispatcher template');
+    const priorDispatcher = await preflightInstall({
+      paths,
+      descriptor,
+      backend,
+      prior,
+      forceLauncher,
+      reconcileAppOwner: Boolean(ifOwned && prior.valid && prior.manifest.PHR_BACKEND === 'app'),
+      dispatcherTemplate: template,
+    });
+
+    let generation = null;
+    if (backend === 'self-copy') {
+      generation = await prepareGeneration({
+        paths,
+        descriptor,
+        runtime: canonicalRecordedRuntime,
+        home,
+        prior,
+        onPhase,
+        materialize,
+        npmCommand,
+      });
+    }
+    const manifest = backend === 'app'
+      ? {
+        PHR_BACKEND: 'app',
+        PHR_VERSION: descriptor.version,
+        PHR_TARGET: canonicalTarget,
+        PHR_RUNTIME: canonicalRecordedRuntime,
+        PHR_GENERATION: `app-${descriptor.version}`,
+      }
+      : {
+        PHR_BACKEND: 'self-copy',
+        PHR_VERSION: descriptor.version,
+        PHR_TARGET: generation.target,
+        PHR_RUNTIME: canonicalRecordedRuntime,
+        PHR_GENERATION: descriptor.version,
+      };
+
+    if (ifOwned && sameManifest(prior.manifest, manifest) && priorDispatcher.file && (priorDispatcher.mode & 0o111)) {
+      const existingDispatcher = await readRegularFileNoFollow(paths.dispatcher, 'dispatcher');
+      if (existingDispatcher.equals(template)) {
+        return {
+          paths,
+          manifest,
+          npmCommand: null,
+          generationDir: null,
+          reusedGeneration: false,
+          replaced: null,
+          gcRemoved: [],
+          warnings: stale.warnings,
+          skipped: 'current',
+        };
+      }
+    }
+    await installDispatcher({ paths, template, onPhase });
+    await commitManifest({ paths, manifest, onPhase });
+
+    const payloadCleanup = await cleanupOrphanPayloads(paths)
+      .catch((error) => cleanupFailure(error, 'payload cleanup'));
+    const gc = await garbageCollectLauncherGenerationsUnlocked(paths)
+      .catch((error) => cleanupFailure(error, 'GC'));
+    return {
+      paths,
+      manifest,
+      npmCommand,
+      generationDir: generation?.generationDir ?? null,
+      reusedGeneration: false,
+      replaced: collisionRecord(prior, priorDispatcher),
+      gcRemoved: [...payloadCleanup.removed, ...gc.removed],
+      warnings: [...stale.warnings, ...payloadCleanup.warnings, ...gc.warnings],
+    };
+  });
+}
+
+async function validateRemoveTree(paths) {
+  for (const [path, label] of [
+    [paths.managedDir, 'managed directory'],
+    [paths.binDir, 'managed bin directory'],
+    [paths.generations, 'generation directory'],
+  ]) {
+    const current = await stateFor(path);
+    if (!current.present) continue;
+    assertCurrentOwner(path, current, label);
+    if (current.symlink) throw launcherWriteError(`refusing symlinked ${label}: ${path}`);
+    if (!current.directory) throw launcherWriteError(`${label} is not a directory: ${path}`);
+  }
+}
+
+export async function removeLauncher({
+  home = homedir(),
+  forceLauncher = false,
+  backend = 'self-copy',
+  onPhase,
+} = {}) {
+  if (!LAUNCHER_BACKENDS.includes(backend)) {
+    throw launcherWriteError(`backend must be ${LAUNCHER_BACKENDS.join(' | ')} (got ${JSON.stringify(backend)})`);
+  }
+  const paths = launcherPaths({ home });
+  await validateRemoveTree(paths);
+  const bin = await stateFor(paths.binDir);
+  if (!bin.present) {
+    return { paths, removed: false, prior: null, gcRemoved: [], warnings: [] };
+  }
+  return withLauncherLock(paths, async () => {
+    await assertTreeOwned(paths.binDir, 'managed launcher artifact');
+    await assertTreeOwned(paths.generations, 'managed generation artifact');
+    let prior = await existingManifestRecord(paths);
+    let dispatcher = await stateFor(paths.dispatcher);
+    assertCurrentOwner(paths.dispatcher, dispatcher, 'dispatcher');
+    if (dispatcher.symlink) throw launcherWriteError(`refusing symlinked dispatcher: ${paths.dispatcher}`);
+    if (dispatcher.present && !dispatcher.file) {
+      throw launcherWriteError(`dispatcher path is not a regular file: ${paths.dispatcher}`);
+    }
+
+    if (!prior.present && !dispatcher.present) {
+      return { paths, removed: false, prior: null, gcRemoved: [], warnings: [] };
+    }
+    if (!prior.present && dispatcher.present && !forceLauncher) {
+      throw launcherWriteError('dispatcher is present without launcher.env ownership; use --force-launcher to remove it');
+    }
+    if (prior.present && !prior.valid && !forceLauncher) {
+      throw launcherWriteError(`launcher.env is invalid (${prior.errors.join('; ')}); use --force-launcher to remove it`);
+    }
+    if (prior.valid && prior.manifest.PHR_BACKEND !== backend && !forceLauncher) {
+      throw launcherWriteError(
+        `launcher remove refused: owner=${prior.manifest.PHR_BACKEND}, version=${prior.manifest.PHR_VERSION}; use --force-launcher to override`,
+      );
+    }
+
+    // Re-read under the lifecycle lock immediately before the unlink. This is
+    // deliberately redundant with the earlier policy check: the bytes being
+    // removed, not a stale inspection result, determine ownership.
+    prior = await existingManifestRecord(paths);
+    dispatcher = await stateFor(paths.dispatcher);
+    assertCurrentOwner(paths.dispatcher, dispatcher, 'dispatcher');
+    if (!prior.present && dispatcher.present && !forceLauncher) {
+      throw launcherWriteError('launcher.env disappeared before removal; unowned dispatcher removal refused');
+    }
+    if (prior.present && !prior.valid && !forceLauncher) {
+      throw launcherWriteError(`launcher.env changed and is invalid (${prior.errors.join('; ')}); removal refused`);
+    }
+    if (prior.valid && prior.manifest.PHR_BACKEND !== backend && !forceLauncher) {
+      throw launcherWriteError(
+        `launcher.env changed ownership to ${prior.manifest.PHR_BACKEND}@${prior.manifest.PHR_VERSION}; removal refused`,
+      );
+    }
+    const replacement = collisionRecord(prior, dispatcher);
+
+    // Manifest removal is the uninstall commit boundary. If the next unlink is
+    // interrupted, the static dispatcher remains and diagnoses the absent manifest.
+    if (prior.present) {
+      await unlink(paths.manifest);
+      await syncDirectory(paths.binDir);
+      await notifyPhase(onPhase, 'after-manifest-remove');
+    }
+    dispatcher = await stateFor(paths.dispatcher);
+    assertCurrentOwner(paths.dispatcher, dispatcher, 'dispatcher');
+    if (dispatcher.present) {
+      if (dispatcher.symlink || !dispatcher.file) {
+        throw launcherWriteError(`dispatcher changed before removal: ${paths.dispatcher}`);
+      }
+      await unlink(paths.dispatcher);
+      await syncDirectory(paths.binDir);
+      await notifyPhase(onPhase, 'after-dispatcher-remove');
+    }
+
+    const gc = await garbageCollectLauncherGenerationsUnlocked(paths)
+      .catch((error) => cleanupFailure(error, 'GC'));
+    return {
+      paths,
+      removed: true,
+      prior: replacement,
+      gcRemoved: gc.removed,
+      warnings: gc.warnings,
+    };
+  });
+}
+
+export function launcherShellProfile({ home = homedir(), shell = process.env.SHELL } = {}) {
+  switch (basename(shell || '')) {
+    case 'zsh':
+      return join(home, '.zprofile');
+    case 'bash':
+      return join(home, '.bash_profile');
+    case 'fish':
+      return null;
+    default:
+      return join(home, '.profile');
+  }
+}
+
+export function launcherPathPlan({ home = homedir(), shell = process.env.SHELL } = {}) {
+  if (basename(shell || '') === 'fish') {
+    return { profilePath: null, line: FISH_LAUNCHER_PATH_LINE, appendable: false, shell: 'fish' };
+  }
+  return {
+    profilePath: launcherShellProfile({ home, shell }),
+    line: LAUNCHER_PATH_LINE,
+    appendable: true,
+    shell: basename(shell || '') || 'POSIX shell',
+  };
+}
+
+function printPathInstruction(plan) {
+  if (!plan.appendable) {
+    console.log('Terminal PATH was not changed. Run this command in fish:');
+  } else {
+    console.log(`Terminal PATH was not changed. Add this line to ${plan.profilePath}:`);
+  }
+  console.log(`  ${plan.line}`);
+}
+
+function contentDigest(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function profileChangedError(profilePath) {
+  const error = launcherWriteError(`shell profile changed before PATH append commit: ${profilePath}`);
+  error.code = 'PHR_LAUNCHER_PROFILE_CHANGED';
+  return error;
+}
+
+function sameFileIdentity(left, right) {
+  return left.present === right.present
+    && (!left.present || (left.file && right.file && left.dev === right.dev && left.ino === right.ino));
+}
+
+async function createProfileExclusively(profilePath, { onBeforeProfileRename } = {}) {
+  // The hook models another process creating the previously absent profile at the
+  // last boundary. O_EXCL makes exactly one creator win without overwriting either.
+  await onBeforeProfileRename?.();
+  let handle;
+  try {
+    handle = await open(
+      profilePath,
+      noFollowFlags(constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY),
+      0o600,
+    );
+  } catch (error) {
+    if (error?.code === 'EEXIST') throw profileChangedError(profilePath);
+    throw error;
+  }
+  let complete = false;
+  let created;
+  try {
+    created = await handle.stat();
+    await handle.writeFile(`${LAUNCHER_PATH_LINE}\n`);
+    await handle.chmod(0o600);
+    await handle.sync();
+    complete = true;
+  } finally {
+    await handle.close().catch(() => {});
+    if (!complete && created) {
+      const current = await stateFor(profilePath).catch(() => null);
+      if (current?.file && current.dev === created.dev && current.ino === created.ino) {
+        await unlink(profilePath).catch(() => {});
+      }
+    }
+  }
+  await syncDirectory(dirname(profilePath));
+}
+
+async function appendPathLineAtomic(profilePath, { onBeforeProfileRename } = {}) {
+  const current = await stateFor(profilePath);
+  assertCurrentOwner(profilePath, current, 'shell profile');
+  if (current.symlink) throw launcherWriteError(`refusing to edit symlinked shell profile: ${profilePath}`);
+  if (current.present && !current.file) throw launcherWriteError(`shell profile is not a regular file: ${profilePath}`);
+  if (!current.present) {
+    await createProfileExclusively(profilePath, { onBeforeProfileRename });
+    return true;
+  }
+  const existingBytes = await readRegularFileNoFollow(profilePath, 'shell profile');
+  const captured = await stateFor(profilePath);
+  if (!sameFileIdentity(current, captured)) throw profileChangedError(profilePath);
+  const existing = existingBytes.toString('utf8');
+  if (existing.split(/\r?\n/).includes(LAUNCHER_PATH_LINE)) return false;
+  const prefix = existing && !existing.endsWith('\n') ? `${existing}\n` : existing;
+  const tempPath = uniqueTempPath(`${profilePath}.phronesis`);
+  await writeAtomicFile({
+    path: profilePath,
+    tempPath,
+    bytes: `${prefix}${LAUNCHER_PATH_LINE}\n`,
+    mode: current.mode & 0o777,
+    commitRename: async () => {
+      await onBeforeProfileRename?.();
+      const latest = await stateFor(profilePath);
+      assertCurrentOwner(profilePath, latest, 'shell profile');
+      if (latest.symlink) throw launcherWriteError(`refusing to edit symlinked shell profile: ${profilePath}`);
+      if (latest.present && !latest.file) throw launcherWriteError(`shell profile is not a regular file: ${profilePath}`);
+      if (!sameFileIdentity(captured, latest)) throw profileChangedError(profilePath);
+      if (latest.file) {
+        const latestBytes = await readRegularFileNoFollow(profilePath, 'shell profile');
+        const afterRead = await stateFor(profilePath);
+        if (
+          !sameFileIdentity(latest, afterRead)
+          || contentDigest(latestBytes) !== contentDigest(existingBytes)
+        ) throw profileChangedError(profilePath);
+      }
+      // POSIX rename still has no portable compare-and-swap form for an existing
+      // destination on macOS. Keep the final check and rename invocation adjacent:
+      // an external write after this check but before the kernel applies rename is
+      // the bounded residual described in the core-0069 evidence.
+      await rename(tempPath, profilePath);
+    },
+  });
+  return true;
+}
+
+export async function offerLauncherPath({
+  home = homedir(),
+  shell = process.env.SHELL,
+  isTTY = Boolean(process.stdin.isTTY),
+  prompt,
+  onBeforeProfileRename,
+} = {}) {
+  const plan = launcherPathPlan({ home, shell });
+  const { profilePath, line } = plan;
+  if (!isTTY || !plan.appendable) {
+    printPathInstruction(plan);
+    return { profilePath, line, written: false, declined: true };
+  }
+
+  console.log(`PATH offer for ${profilePath}:`);
+  console.log(`  ${line}`);
+  const current = await stateFor(profilePath);
+  assertCurrentOwner(profilePath, current, 'shell profile');
+  if (current.symlink) {
+    console.error(`launcher: warning — refusing to edit symlinked shell profile: ${profilePath}`);
+    printPathInstruction(plan);
+    return { profilePath, line, written: false, declined: true };
+  }
+  if (current.file) {
+    const body = (await readRegularFileNoFollow(profilePath, 'shell profile')).toString('utf8');
+    if (body.split(/\r?\n/).includes(LAUNCHER_PATH_LINE)) {
+      console.log(`PATH line already present in ${profilePath}.`);
+      return { profilePath, line: LAUNCHER_PATH_LINE, written: false, alreadyPresent: true };
+    }
+  }
+  const accepted = typeof prompt === 'function' ? await prompt({ profilePath, line }) : false;
+  if (!accepted) {
+    printPathInstruction(plan);
+    return { profilePath, line, written: false, declined: true };
+  }
+  let written;
+  try {
+    written = await appendLauncherPath({ home, shell, onBeforeProfileRename });
+  } catch (error) {
+    if (error?.code !== 'PHR_LAUNCHER_PROFILE_CHANGED') throw error;
+    console.error(`launcher: warning — ${error.message}`);
+    printPathInstruction(plan);
+    return { profilePath, line, written: false, declined: true, warning: error.message };
+  }
+  if (written) console.log(`Appended the disclosed PATH line to ${profilePath}.`);
+  return { profilePath, line, written, alreadyPresent: !written };
+}
+
+export async function appendLauncherPath({
+  home = homedir(),
+  shell = process.env.SHELL,
+  onBeforeProfileRename,
+} = {}) {
+  const plan = launcherPathPlan({ home, shell });
+  if (!plan.appendable || !plan.profilePath) return false;
+  return appendPathLineAtomic(plan.profilePath, { onBeforeProfileRename });
+}
+
+export async function runLauncherPath({
+  home = homedir(),
+  shell = process.env.SHELL,
+  append = false,
+  surfaceConsented = false,
+  json = false,
+  isTTY = Boolean(process.stdin.isTTY),
+  prompt,
+  onBeforeProfileRename,
+} = {}) {
+  const plan = launcherPathPlan({ home, shell });
+  let result = { ...plan, written: false, alreadyPresent: false };
+
+  if (append && surfaceConsented && !isTTY) {
+    try {
+      const written = await appendLauncherPath({ home, shell, onBeforeProfileRename });
+      result = { ...plan, written, alreadyPresent: Boolean(plan.appendable && !written) };
+      console.log(`Surface-consented PATH append for ${plan.profilePath ?? `${plan.shell} configuration`}:`);
+      console.log(`  ${plan.line}`);
+    } catch (error) {
+      if (error?.code !== 'PHR_LAUNCHER_PROFILE_CHANGED') throw error;
+      console.error(`launcher: warning — ${error.message}`);
+      printPathInstruction(plan);
+      result = { ...plan, written: false, alreadyPresent: false, warning: error.message };
+    }
+  } else if (append) {
+    const offered = await offerLauncherPath({ home, shell, isTTY, prompt, onBeforeProfileRename });
+    result = {
+      ...plan,
+      written: Boolean(offered.written),
+      alreadyPresent: Boolean(offered.alreadyPresent),
+      ...(offered.warning ? { warning: offered.warning } : {}),
+    };
+    if (!isTTY) {
+      console.log('Automatic PATH append requires a TTY confirmation or a consenting surface; no profile was changed.');
+    }
+  }
+
+  if (json) {
+    console.log(JSON.stringify(result));
+  } else if (!append) {
+    console.log(plan.appendable
+      ? `Shell profile: ${plan.profilePath}`
+      : `Shell profile: manual ${plan.shell} configuration`);
+    console.log(`PATH line: ${plan.line}`);
+  } else if (surfaceConsented && !isTTY) {
+    if (!result.warning) {
+      console.log(result.written ? 'PATH line appended.' : 'PATH line was already present or requires manual shell configuration.');
+    }
+  }
+  return result;
+}
+
+export async function runLauncherInstall(options = {}) {
+  const result = await installLauncher(options);
+  if (result.skipped) return result;
+  console.log('Installed the `phronesis` command.');
+  if (result.generationDir) console.log(`  CLI generation: ${result.generationDir}`);
+  else console.log(`  App target: ${result.manifest.PHR_TARGET}`);
+  console.log(`  Dispatcher: ${result.paths.dispatcher}`);
+  console.log(`  Manifest: ${result.paths.manifest}`);
+  console.log(`  Runtime: ${result.manifest.PHR_RUNTIME}`);
+  if (result.npmCommand) console.log(`  npm used: ${result.npmCommand}`);
+  if (result.replaced && (result.replaced.owner !== result.manifest.PHR_BACKEND || options.forceLauncher)) {
+    console.log(
+      `  Replaced ${result.replaced.kind}; prior owner=${result.replaced.owner}, version=${result.replaced.version}.`,
+    );
+  }
+  for (const warning of result.warnings) console.error(`launcher: warning — ${warning}`);
+
+  if (options.offerPath !== false) {
+    try {
+      await offerLauncherPath({
+        home: options.home,
+        shell: options.shell,
+        isTTY: options.isTTY,
+        prompt: options.promptPath,
+      });
+    } catch (error) {
+      console.error(`launcher installed; PATH offer could not complete: ${error.message}`);
+      printPathInstruction(launcherPathPlan({ home: options.home, shell: options.shell }));
+      result.pathOfferWarning = error.message;
+    }
+  }
+  return result;
+}
+
+export async function runLauncherRemove(options = {}) {
+  const result = await removeLauncher(options);
+  if (!result.removed) {
+    console.log('Managed `phronesis` command is not installed.');
+    return result;
+  }
+  console.log('Removed the managed `phronesis` command.');
+  console.log(`  Manifest: ${result.paths.manifest}`);
+  console.log(`  Dispatcher: ${result.paths.dispatcher}`);
+  if (result.prior) console.log(`  Prior owner=${result.prior.owner}, version=${result.prior.version}.`);
+  for (const warning of result.warnings) console.error(`launcher: warning — ${warning}`);
+  return result;
+}