phronesis 1.0.0 → 1.1.0

package/src/hooks-refresh.js

@@ -0,0 +1,1363 @@
+// `phronesis hooks refresh` — the narrow, approval-gated D9 migration slice.
+//
+// The manifest comes from layout.js's init copies. A missing global 0047 baseline
+// does not change this command's posture: without a hook-scoped entry, drift is
+// unattributable and requires explicit approval. This module owns only
+// .phronesis/hook-stamp.json and never treats any broader install baseline as authority.
+
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { lstat, mkdir, readdir, realpath, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RE_SLUG, resolveInstall } from '@phronesis/core';
+import { hookManifestCopies } from './layout.js';
+import {
+  inspectLauncher,
+  readRegularFileNoFollow,
+  runLauncherInstall,
+  writeAtomicFileNoFollow,
+} from './launcher.js';
+import {
+  confirmHookRestamp,
+  confirmPathAppend,
+  confirmPersistence,
+  PERSISTENCE_PROMPT,
+} from './prompts.js';
+
+const require = createRequire(import.meta.url);
+const { version: CLI_VERSION } = require('../package.json');
+const TEMPLATES_DIR = fileURLToPath(new URL('../templates/', import.meta.url));
+const HOOK_STAMP_REL = '.phronesis/hook-stamp.json';
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const STALE_HOOK_TEMP_AGE_MS = 60 * 1000;
+
+function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function pathError(message) {
+  return new Error(`hooks refresh: ${message}`);
+}
+
+function changedSinceReviewError(path, detail) {
+  const error = pathError(`changed-since-review ${path}: ${detail}`);
+  error.code = 'PHR_HOOK_CHANGED_SINCE_REVIEW';
+  error.path = path;
+  error.detail = detail;
+  return error;
+}
+
+function validateRelativePath(path, label = 'path') {
+  if (typeof path !== 'string' || !path || isAbsolute(path)) {
+    throw pathError(`${label} must be a non-empty install-relative path`);
+  }
+  const parts = path.split('/');
+  if (parts.some((part) => !part || part === '.' || part === '..' || part.includes('\\'))) {
+    throw pathError(`${label} is not a normalized install-relative path: ${path}`);
+  }
+  return path;
+}
+
+function expectedUid() {
+  return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+
+function assertOwned(path, state, label = 'managed path') {
+  const uid = expectedUid();
+  if (state.present && uid !== null && state.uid !== uid) {
+    throw pathError(
+      `refusing ${label} owned by uid ${state.uid}; current uid is ${uid}: ${path}`,
+    );
+  }
+}
+
+async function stateAt(path) {
+  try {
+    const value = await lstat(path);
+    return {
+      present: true,
+      symlink: value.isSymbolicLink(),
+      file: value.isFile(),
+      directory: value.isDirectory(),
+      mode: value.mode,
+      uid: value.uid,
+      mtimeMs: value.mtimeMs,
+    };
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return {
+        present: false,
+        symlink: false,
+        file: false,
+        directory: false,
+        mode: 0,
+        uid: null,
+        mtimeMs: null,
+      };
+    }
+    throw error;
+  }
+}
+
+async function inspectInstallPath(root, relPath) {
+  validateRelativePath(relPath);
+  const parts = relPath.split('/');
+  let current = root;
+  for (let index = 0; index < parts.length; index += 1) {
+    current = join(current, parts[index]);
+    const state = await stateAt(current);
+    if (!state.present) return { present: false, path: current, missingAt: parts.slice(0, index + 1).join('/') };
+    if (state.symlink) {
+      return { present: true, unsafe: true, path: current, detail: `symlinked path component ${parts.slice(0, index + 1).join('/')}` };
+    }
+    if (index < parts.length - 1 && !state.directory) {
+      return { present: true, unsafe: true, path: current, detail: `non-directory path component ${parts.slice(0, index + 1).join('/')}` };
+    }
+    if (index === parts.length - 1) return { ...state, path: current };
+  }
+  throw pathError(`could not inspect ${relPath}`);
+}
+
+async function ensureParentDirectoriesNoFollow(root, relPath) {
+  const parentRel = dirname(relPath);
+  if (parentRel === '.') return;
+  let current = root;
+  for (const part of parentRel.split('/')) {
+    current = join(current, part);
+    let state = await stateAt(current);
+    if (!state.present) {
+      try {
+        await mkdir(current, { mode: 0o755 });
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error;
+      }
+      state = await stateAt(current);
+    }
+    assertOwned(current, state, 'managed parent directory');
+    if (state.symlink || !state.directory) {
+      throw pathError(`refusing non-directory or symlinked managed parent: ${current}`);
+    }
+  }
+}
+
+function shellCommandWords(command) {
+  if (typeof command !== 'string') return null;
+  const words = [];
+  let word = '';
+  let started = false;
+  let quote = null;
+
+  function finishWord() {
+    if (!started) return;
+    words.push(word);
+    word = '';
+    started = false;
+  }
+
+  for (let index = 0; index < command.length; index += 1) {
+    const character = command[index];
+    if (quote === "'") {
+      if (character === "'") quote = null;
+      else word += character;
+      continue;
+    }
+    if (quote === '"') {
+      if (character === '"') {
+        quote = null;
+        continue;
+      }
+      if (character === '\\') {
+        index += 1;
+        if (index >= command.length) return null;
+        word += command[index];
+        continue;
+      }
+      if (character === '`' || (character === '$' && command[index + 1] === '(')) return null;
+      word += character;
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quote = character;
+      started = true;
+      continue;
+    }
+    if (character === '\\') {
+      index += 1;
+      if (index >= command.length) return null;
+      word += command[index];
+      started = true;
+      continue;
+    }
+    if (character === '`' || (character === '$' && command[index + 1] === '(')) return null;
+    if (/\s/.test(character)) {
+      finishWord();
+      continue;
+    }
+    if (';|&<>'.includes(character)) {
+      finishWord();
+      break;
+    }
+    word += character;
+    started = true;
+  }
+  if (quote) return null;
+  finishWord();
+  return words;
+}
+
+function primaryInvokedWords(words, depth) {
+  if (depth > 4 || !words?.length) return null;
+  let index = 0;
+  while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[index] || '')) index += 1;
+  if (index >= words.length) return null;
+
+  const invokedToken = words[index];
+  // Wrapper recognition is exact, never basename-derived. In particular, an
+  // operator executable such as scripts/sh or ./env must remain the primary
+  // target instead of borrowing semantics from the system command with the same
+  // basename. /usr/bin/env is the one explicit canonical system path supported
+  // by Claude hook emissions and migration tests.
+  const executable = invokedToken === '/usr/bin/env'
+    ? 'env'
+    : invokedToken.includes('/') ? null : invokedToken;
+  if (executable === 'env') {
+    index += 1;
+    while (index < words.length) {
+      if (words[index] === '--') {
+        index += 1;
+        break;
+      }
+      if (words[index] === '-S' || words[index] === '--split-string') {
+        return primaryInvokedScript(words[index + 1], depth + 1);
+      }
+      if (words[index].startsWith('-') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[index])) {
+        index += 1;
+        continue;
+      }
+      break;
+    }
+    return primaryInvokedWords(words.slice(index), depth + 1);
+  }
+  if (['command', 'exec', 'nohup'].includes(executable)) {
+    index += 1;
+    while (words[index]?.startsWith('-')) index += 1;
+    return primaryInvokedWords(words.slice(index), depth + 1);
+  }
+  if (['sh', 'bash', 'dash', 'zsh'].includes(executable)) {
+    index += 1;
+    while (index < words.length) {
+      if (words[index] === '-c') return primaryInvokedScript(words[index + 1], depth + 1);
+      if (words[index] === '--') {
+        index += 1;
+        break;
+      }
+      if (words[index].startsWith('-')) {
+        index += 1;
+        continue;
+      }
+      break;
+    }
+    return words[index] || null;
+  }
+  return invokedToken;
+}
+
+function primaryInvokedScript(command, depth = 0) {
+  return primaryInvokedWords(shellCommandWords(command), depth);
+}
+
+function managedTargetForCommand(command, managedTargets, root) {
+  const invoked = primaryInvokedScript(command);
+  // Conservative attribution is intentional: an unresolvable/normalized command
+  // is preserved as operator-owned. The residual failure direction is a duplicate,
+  // never deletion of an operator hook.
+  if (!invoked) return null;
+  for (const target of managedTargets) {
+    const variants = new Set([
+      target,
+      `./${target}`,
+      `$CLAUDE_PROJECT_DIR/${target}`,
+      `\${CLAUDE_PROJECT_DIR}/${target}`,
+      join(root, target),
+    ]);
+    if (variants.has(invoked)) return target;
+  }
+  return null;
+}
+
+function managedClaudeHook(hook, managedTargets, root) {
+  return managedTargetForCommand(hook?.command, managedTargets, root);
+}
+
+function managedClaudeEntries(settings, managedTargets, root) {
+  const entries = [];
+  const hooks = settings?.hooks;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return entries;
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      if (!group || typeof group !== 'object' || !Array.isArray(group.hooks)) continue;
+      for (const hook of group.hooks) {
+        const target = managedClaudeHook(hook, managedTargets, root);
+        if (target) entries.push({ event, target, command: hook.command });
+      }
+    }
+  }
+  return entries;
+}
+
+function managedClaudeBlock(settings, managedTargets, root) {
+  const hooks = settings?.hooks;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return {};
+  const block = {};
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const managedGroups = [];
+    for (const group of groups) {
+      if (!group || typeof group !== 'object' || !Array.isArray(group.hooks)) continue;
+      const managedHooks = group.hooks.filter((hook) =>
+        managedClaudeHook(hook, managedTargets, root));
+      if (managedHooks.length) managedGroups.push({ ...group, hooks: managedHooks });
+    }
+    if (managedGroups.length) block[event] = managedGroups;
+  }
+  return block;
+}
+
+function managedBlockBytes(block) {
+  return Buffer.from(JSON.stringify(block), 'utf8');
+}
+
+function mergeClaudeHookEntries(liveSettings, expectedBlock, managedTargets, root) {
+  if (!liveSettings || typeof liveSettings !== 'object' || Array.isArray(liveSettings)) {
+    throw pathError('.claude/settings.json must contain a JSON object; refusing whole-file replacement');
+  }
+  if (
+    Object.hasOwn(liveSettings, 'hooks')
+    && (liveSettings.hooks === null || typeof liveSettings.hooks !== 'object' || Array.isArray(liveSettings.hooks))
+  ) {
+    throw pathError('.claude/settings.json hooks must be an object; refusing to discard operator settings');
+  }
+
+  const preservedHooks = {};
+  for (const [event, groups] of Object.entries(liveSettings.hooks || {})) {
+    if (!Array.isArray(groups)) {
+      if (Object.hasOwn(expectedBlock, event)) {
+        throw pathError(
+          `.claude/settings.json hooks.${event} is not an array; refusing to overwrite an unmergeable operator value`,
+        );
+      }
+      preservedHooks[event] = groups;
+      continue;
+    }
+    const preservedGroups = [];
+    for (const group of groups) {
+      if (!group || typeof group !== 'object' || !Array.isArray(group.hooks)) {
+        preservedGroups.push(group);
+        continue;
+      }
+      const operatorHooks = group.hooks.filter((hook) =>
+        !managedClaudeHook(hook, managedTargets, root));
+      if (operatorHooks.length === group.hooks.length) preservedGroups.push(group);
+      else if (operatorHooks.length) preservedGroups.push({ ...group, hooks: operatorHooks });
+    }
+    if (preservedGroups.length) preservedHooks[event] = preservedGroups;
+  }
+
+  // Re-emit managed events in the shipped block's order. Assigning over keys in
+  // live order would preserve a historical/operator key order and make an approved
+  // refresh report `differs` forever even though every managed entry was replaced.
+  const nextHooks = {};
+  for (const [event, groups] of Object.entries(expectedBlock)) {
+    nextHooks[event] = [...groups, ...(preservedHooks[event] || [])];
+  }
+  for (const [event, groups] of Object.entries(preservedHooks)) {
+    if (!Object.hasOwn(expectedBlock, event)) nextHooks[event] = groups;
+  }
+  return { ...liveSettings, hooks: nextHooks };
+}
+
+function parseJson(bytes, label) {
+  try {
+    return JSON.parse(bytes.toString('utf8'));
+  } catch (error) {
+    throw pathError(`${label} is not valid JSON: ${error.message}`);
+  }
+}
+
+// JSON.parse silently keeps the last duplicate object key. Class-C surgery cannot
+// safely round-trip that input because doing so would erase operator bytes without
+// any indication that two values existed. This small grammar pass rejects duplicates
+// at every object depth before the normal JSON parser is allowed to construct values.
+function assertNoDuplicateJsonKeys(bytes, label) {
+  const source = bytes.toString('utf8');
+  let index = 0;
+
+  function fail(message) {
+    throw pathError(`${label} ${message}`);
+  }
+
+  function skipWhitespace() {
+    while (/[\t\n\r ]/.test(source[index] || '')) index += 1;
+  }
+
+  function parseStringToken() {
+    if (source[index] !== '"') fail(`has invalid JSON at byte ${index}`);
+    const start = index;
+    index += 1;
+    let escaped = false;
+    while (index < source.length) {
+      const character = source[index];
+      index += 1;
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (character === '\\') {
+        escaped = true;
+        continue;
+      }
+      if (character === '"') {
+        const token = source.slice(start, index);
+        try {
+          return JSON.parse(token);
+        } catch (error) {
+          fail(`is not valid JSON: ${error.message}`);
+        }
+      }
+    }
+    fail('is not valid JSON: unterminated string');
+  }
+
+  function parseValue() {
+    skipWhitespace();
+    const character = source[index];
+    if (character === '{') return parseObject();
+    if (character === '[') return parseArray();
+    if (character === '"') {
+      parseStringToken();
+      return;
+    }
+    const literal = /^(?:true|false|null)/.exec(source.slice(index));
+    if (literal) {
+      index += literal[0].length;
+      return;
+    }
+    const number = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(source.slice(index));
+    if (number) {
+      index += number[0].length;
+      return;
+    }
+    fail(`has invalid JSON at byte ${index}`);
+  }
+
+  function parseObject() {
+    index += 1;
+    skipWhitespace();
+    const keys = new Set();
+    if (source[index] === '}') {
+      index += 1;
+      return;
+    }
+    for (;;) {
+      skipWhitespace();
+      const key = parseStringToken();
+      if (keys.has(key)) {
+        fail(`contains duplicate object key ${JSON.stringify(key)}; refusing settings surgery`);
+      }
+      keys.add(key);
+      skipWhitespace();
+      if (source[index] !== ':') fail(`has invalid JSON at byte ${index}`);
+      index += 1;
+      parseValue();
+      skipWhitespace();
+      if (source[index] === '}') {
+        index += 1;
+        return;
+      }
+      if (source[index] !== ',') fail(`has invalid JSON at byte ${index}`);
+      index += 1;
+    }
+  }
+
+  function parseArray() {
+    index += 1;
+    skipWhitespace();
+    if (source[index] === ']') {
+      index += 1;
+      return;
+    }
+    for (;;) {
+      parseValue();
+      skipWhitespace();
+      if (source[index] === ']') {
+        index += 1;
+        return;
+      }
+      if (source[index] !== ',') fail(`has invalid JSON at byte ${index}`);
+      index += 1;
+    }
+  }
+
+  parseValue();
+  skipWhitespace();
+  if (index !== source.length) fail(`has invalid JSON at byte ${index}`);
+}
+
+function parseClaudeSettings(bytes, label = '.claude/settings.json') {
+  assertNoDuplicateJsonKeys(bytes, label);
+  return parseJson(bytes, label);
+}
+
+function installDomains(registry) {
+  if (!Array.isArray(registry?.domains) || registry.domains.length === 0) {
+    throw pathError('.phronesis/registry.json must declare at least one domain');
+  }
+  const domains = [];
+  for (const domain of registry.domains) {
+    if (typeof domain !== 'string' || !RE_SLUG.test(domain)) {
+      throw pathError(`.phronesis/registry.json contains an invalid domain: ${JSON.stringify(domain)}`);
+    }
+    if (!domains.includes(domain)) domains.push(domain);
+  }
+  return domains;
+}
+
+async function buildHookManifest(root, { templatesDir = TEMPLATES_DIR } = {}) {
+  const registryPath = join(root, '.phronesis', 'registry.json');
+  const registryInspection = await inspectInstallPath(root, '.phronesis/registry.json');
+  if (
+    !registryInspection.present
+    || registryInspection.unsafe
+    || registryInspection.symlink
+    || !registryInspection.file
+  ) {
+    throw pathError(
+      `.phronesis/registry.json must be a regular non-symlink file (${registryInspection.detail || 'missing or not a file'})`,
+    );
+  }
+  const registry = parseJson(
+    await readRegularFileNoFollow(registryPath, 'installation registry'),
+    '.phronesis/registry.json',
+  );
+  const domains = installDomains(registry);
+  const copies = [
+    ...hookManifestCopies(domains[0]).filter(({ to }) => !to.startsWith(`domains/${domains[0]}/`)),
+    ...domains.flatMap((domain) =>
+      hookManifestCopies(domain).filter(({ to }) => to.startsWith(`domains/${domain}/`))),
+  ];
+  const managedClaudeTargets = copies
+    .filter(({ to }) => to.startsWith('.phronesis/hooks/') && to.endsWith('.sh'))
+    .map(({ to }) => to)
+    .sort();
+  const entries = [];
+  for (const copy of copies) {
+    validateRelativePath(copy.to, 'hook-manifest path');
+    const sourcePath = join(templatesDir, copy.from);
+    const sourceBytes = await readRegularFileNoFollow(sourcePath, `shipped template ${copy.from}`);
+    if (copy.kind === 'claude-hook-entries') {
+      const expectedSettings = parseJson(sourceBytes, copy.shippedTemplate);
+      const expectedBlock = expectedSettings?.hooks;
+      if (!expectedBlock || typeof expectedBlock !== 'object' || Array.isArray(expectedBlock)) {
+        throw pathError(`${copy.shippedTemplate} must contain a hooks object`);
+      }
+      entries.push({
+        ...copy,
+        path: copy.to,
+        sourcePath,
+        expectedSettings,
+        expectedBlock,
+        managedClaudeTargets,
+        expectedBytes: managedBlockBytes(expectedBlock),
+      });
+    } else {
+      entries.push({
+        ...copy,
+        path: copy.to,
+        sourcePath,
+        expectedBytes: sourceBytes,
+      });
+    }
+  }
+  return { domains, entries };
+}
+
+function stampSchemaError(message) {
+  return pathError(`invalid ${HOOK_STAMP_REL}: ${message}`);
+}
+
+function validateHookStamp(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw stampSchemaError('expected an object');
+  const outerKeys = Object.keys(value).sort();
+  if (JSON.stringify(outerKeys) !== JSON.stringify(['files', 'schema_version', 'scope'])) {
+    throw stampSchemaError('expected exactly schema_version, scope, and files');
+  }
+  if (value.schema_version !== 1) throw stampSchemaError('schema_version must be 1');
+  if (value.scope !== 'hooks') throw stampSchemaError('scope must be "hooks"');
+  if (!Array.isArray(value.files)) throw stampSchemaError('files must be an array');
+
+  const seen = new Set();
+  for (const [index, entry] of value.files.entries()) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw stampSchemaError(`files[${index}] must be an object`);
+    }
+    const keys = Object.keys(entry).sort();
+    const expectedKeys = ['cli_version', 'path', 'sha256', 'shipped_template', 'stamped_at'];
+    if (JSON.stringify(keys) !== JSON.stringify(expectedKeys)) {
+      throw stampSchemaError(`files[${index}] has unknown or missing fields`);
+    }
+    validateRelativePath(entry.path, `files[${index}].path`);
+    if (seen.has(entry.path)) throw stampSchemaError(`duplicate path ${entry.path}`);
+    seen.add(entry.path);
+    if (typeof entry.shipped_template !== 'string' || !entry.shipped_template) {
+      throw stampSchemaError(`files[${index}].shipped_template must be a non-empty string`);
+    }
+    if (typeof entry.sha256 !== 'string' || !SHA256_RE.test(entry.sha256)) {
+      throw stampSchemaError(`files[${index}].sha256 must be lowercase sha256 hex`);
+    }
+    if (typeof entry.cli_version !== 'string' || !entry.cli_version) {
+      throw stampSchemaError(`files[${index}].cli_version must be a non-empty string`);
+    }
+    if (typeof entry.stamped_at !== 'string' || Number.isNaN(Date.parse(entry.stamped_at))) {
+      throw stampSchemaError(`files[${index}].stamped_at must be an ISO timestamp`);
+    }
+  }
+  return value;
+}
+
+async function loadHookStamp(root) {
+  const inspected = await inspectInstallPath(root, HOOK_STAMP_REL);
+  if (!inspected.present) return null;
+  if (inspected.unsafe || inspected.symlink || !inspected.file) {
+    throw stampSchemaError(inspected.detail || 'must be a regular non-symlink file');
+  }
+  const bytes = await readRegularFileNoFollow(join(root, HOOK_STAMP_REL), HOOK_STAMP_REL);
+  return validateHookStamp(parseJson(bytes, HOOK_STAMP_REL));
+}
+
+function stampDisposition(report, stamped) {
+  if (!stamped) return 'unstamped';
+  if (stamped.shipped_template !== report.shippedTemplate) return 'unstamped';
+  if (report.status === 'current') return 'current';
+  if (
+    report.liveHash
+    && report.liveHash === stamped.sha256
+    && stamped.sha256 !== report.expectedHash
+  ) return 'safe';
+  return 'operator-modified';
+}
+
+async function classifyManifestEntry(root, entry, stampEntry) {
+  const inspected = await inspectInstallPath(root, entry.path);
+  const expectedHash = sha256(entry.expectedBytes);
+  const base = { ...entry, expectedHash, inspected };
+  if (!inspected.present) {
+    const report = {
+      ...base,
+      status: 'missing',
+      detail: 'managed path is absent',
+      liveHash: null,
+      reviewedDigest: null,
+      reviewedPresent: false,
+      settingsPlan: entry.kind === 'claude-hook-entries'
+        ? {
+          remove: [],
+          add: managedClaudeEntries(entry.expectedSettings, entry.managedClaudeTargets, root),
+        }
+        : undefined,
+    };
+    report.disposition = stampDisposition(report, stampEntry);
+    return report;
+  }
+  if (inspected.unsafe || inspected.symlink || !inspected.file) {
+    const report = {
+      ...base,
+      status: 'differs',
+      detail: inspected.detail || 'managed path is not a regular non-symlink file',
+      liveHash: null,
+      unsafe: true,
+      reviewedDigest: null,
+      reviewedPresent: true,
+    };
+    report.disposition = stampDisposition(report, stampEntry);
+    return report;
+  }
+
+  const liveBytes = await readRegularFileNoFollow(join(root, entry.path), entry.path);
+  const reviewedDigest = sha256(liveBytes);
+  if (entry.kind === 'claude-hook-entries') {
+    let liveSettings;
+    try {
+      liveSettings = parseClaudeSettings(liveBytes, entry.path);
+    } catch (error) {
+      const report = {
+        ...base,
+        status: 'differs',
+        detail: error.message,
+        liveHash: null,
+        reviewedDigest,
+        reviewedPresent: true,
+        unmergeable: true,
+      };
+      report.disposition = stampDisposition(report, stampEntry);
+      return report;
+    }
+    try {
+      // Preflight the bounded Class-C surgery while the command is still entirely
+      // read-only. A malformed operator value must fail before any selected sibling
+      // is re-stamped, never halfway through a multi-path apply.
+      mergeClaudeHookEntries(
+        liveSettings,
+        entry.expectedBlock,
+        entry.managedClaudeTargets,
+        root,
+      );
+    } catch (error) {
+      const report = {
+        ...base,
+        status: 'differs',
+        detail: error.message,
+        liveHash: null,
+        liveBytes,
+        liveSettings,
+        reviewedDigest,
+        reviewedPresent: true,
+        unmergeable: true,
+      };
+      report.disposition = stampDisposition(report, stampEntry);
+      return report;
+    }
+    const liveBlock = managedClaudeBlock(liveSettings, entry.managedClaudeTargets, root);
+    const settingsPlan = {
+      remove: managedClaudeEntries(liveSettings, entry.managedClaudeTargets, root),
+      add: managedClaudeEntries(entry.expectedSettings, entry.managedClaudeTargets, root),
+    };
+    const blockBytes = managedBlockBytes(liveBlock);
+    const managedCount = Object.values(liveBlock).reduce((count, groups) =>
+      count + groups.reduce((sum, group) => sum + group.hooks.length, 0), 0);
+    const report = {
+      ...base,
+      status: managedCount === 0 ? 'missing' : blockBytes.equals(entry.expectedBytes) ? 'current' : 'differs',
+      detail: managedCount === 0 ? 'Phronesis hook entries are absent from operator settings' : 'Phronesis hook entries differ',
+      liveHash: managedCount === 0 ? null : sha256(blockBytes),
+      liveBytes,
+      liveSettings,
+      liveBlock,
+      settingsPlan,
+      reviewedDigest,
+      reviewedPresent: true,
+    };
+    report.disposition = stampDisposition(report, stampEntry);
+    return report;
+  }
+
+  const bytesMatch = liveBytes.equals(entry.expectedBytes);
+  const modeMatch = !entry.executable || Boolean(inspected.mode & 0o111);
+  const report = {
+    ...base,
+    status: bytesMatch && modeMatch ? 'current' : 'differs',
+    detail: !bytesMatch ? 'live bytes differ from the shipped template' : 'script is not executable',
+    liveHash: sha256(liveBytes),
+    liveBytes,
+    reviewedDigest,
+    reviewedPresent: true,
+  };
+  report.disposition = stampDisposition(report, stampEntry);
+  return report;
+}
+
+async function findUnknownSiblings(root, entries) {
+  const directories = new Map();
+  for (const entry of entries.filter(({ scanUnknownSiblings }) => scanUnknownSiblings)) {
+    const dir = dirname(entry.path);
+    if (!directories.has(dir)) directories.set(dir, new Set());
+    directories.get(dir).add(basename(entry.path));
+  }
+  const extras = [];
+  for (const [dir, expectedNames] of directories) {
+    const inspected = await inspectInstallPath(root, dir);
+    if (!inspected.present || inspected.unsafe || !inspected.directory) continue;
+    const children = await readdir(join(root, dir), { withFileTypes: true });
+    for (const child of children) {
+      if (!expectedNames.has(child.name)) {
+        extras.push({
+          path: `${dir}/${child.name}`,
+          status: 'extra-unknown',
+          detail: 'present outside the derived hook manifest; never touched',
+        });
+      }
+    }
+  }
+  return extras.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function reportSuffix(report) {
+  if (report.status === 'extra-unknown') return report.detail;
+  if (report.status === 'current') return '';
+  if (report.disposition === 'safe') {
+    return 'stamped bytes are unchanged by the operator and the shipped template changed; safe to re-stamp with approval';
+  }
+  if (report.disposition === 'operator-modified') {
+    return 'stamped path was modified or removed after stamping; skipped unless explicitly approved';
+  }
+  return 'no hook-scoped baseline; explicit approval required';
+}
+
+function printReport(root, reports, extras) {
+  console.log(`Hook refresh report: ${root}`);
+  for (const report of [...reports, ...extras]) {
+    const suffix = reportSuffix(report);
+    console.log(`  ${report.status.padEnd(13)} ${report.path}${suffix ? ` — ${suffix}` : ''}`);
+    if (report.kind === 'claude-hook-entries' && report.status !== 'current' && report.settingsPlan) {
+      if (!report.settingsPlan.remove.length) console.log('    settings remove: (no target-attributed managed entries)');
+      for (const entry of report.settingsPlan.remove) {
+        console.log(`    settings remove ${entry.event}: ${JSON.stringify(entry.command)} -> ${entry.target}`);
+      }
+      for (const entry of report.settingsPlan.add) {
+        console.log(`    settings add    ${entry.event}: ${JSON.stringify(entry.command)} -> ${entry.target}`);
+      }
+    }
+  }
+}
+
+async function preflightWrite(root, report) {
+  const inspected = await inspectInstallPath(root, report.path);
+  if (inspected.unsafe || inspected.symlink) {
+    throw pathError(`refusing to follow ${inspected.detail || `symlinked ${report.path}`}`);
+  }
+  if (inspected.present && !inspected.file) {
+    throw pathError(`refusing non-file refresh target: ${report.path}`);
+  }
+  if (inspected.present) assertOwned(join(root, report.path), inspected, 'refresh target');
+  if (report.unmergeable) throw pathError(`${report.path} cannot be bounded-merged: ${report.detail}`);
+}
+
+async function reviewedTargetAtWriteBoundary(root, report) {
+  const inspected = await inspectInstallPath(root, report.path);
+  if (!report.reviewedPresent) {
+    if (!inspected.present) return { matches: true, inspected, liveBytes: null, liveSettings: null };
+    return {
+      matches: false,
+      detail: 'the path was missing when reviewed but now exists',
+    };
+  }
+  if (inspected.unsafe || inspected.symlink || !inspected.file) {
+    return {
+      matches: false,
+      detail: inspected.detail || 'the reviewed regular file is now missing or unsafe',
+    };
+  }
+  let liveBytes;
+  try {
+    liveBytes = await readRegularFileNoFollow(join(root, report.path), report.path);
+  } catch (error) {
+    return { matches: false, detail: error.message };
+  }
+  if (sha256(liveBytes) !== report.reviewedDigest) {
+    return { matches: false, detail: 'live bytes no longer match the reviewed digest' };
+  }
+  let liveSettings = null;
+  if (report.kind === 'claude-hook-entries') {
+    try {
+      liveSettings = parseClaudeSettings(liveBytes, report.path);
+      mergeClaudeHookEntries(
+        liveSettings,
+        report.expectedBlock,
+        report.managedClaudeTargets,
+        root,
+      );
+    } catch (error) {
+      return { matches: false, detail: error.message };
+    }
+  }
+  return { matches: true, inspected, liveBytes, liveSettings };
+}
+
+function atomicTestPhase(phase) {
+  if (
+    process.env.NODE_ENV === 'test'
+    && process.env.PHRONESIS_TEST_HOOK_REFRESH_SIGKILL_PHASE === phase
+  ) process.kill(process.pid, 'SIGKILL');
+}
+
+function escapedRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function cleanupAgedManagedTemps(root, entries, nowMs) {
+  const directories = new Map([
+    ['.phronesis', new Set(['hook-stamp.json'])],
+  ]);
+  for (const entry of entries) {
+    const dir = dirname(entry.path);
+    if (!directories.has(dir)) directories.set(dir, new Set());
+    directories.get(dir).add(basename(entry.path));
+  }
+
+  const removed = [];
+  for (const [dir, managedNames] of directories) {
+    const inspected = await inspectInstallPath(root, dir);
+    if (!inspected.present) continue;
+    if (inspected.unsafe || !inspected.directory) {
+      throw pathError(`refusing temporary cleanup through unsafe managed directory: ${dir}`);
+    }
+    for (const child of await readdir(join(root, dir), { withFileTypes: true })) {
+      const managedName = [...managedNames].find((name) => (
+        new RegExp(`^${escapedRegExp(name)}\\.tmp-[0-9]+-[a-f0-9]+$`).test(child.name)
+      ));
+      if (!managedName) continue;
+      const path = join(root, dir, child.name);
+      const state = await stateAt(path);
+      assertOwned(path, state, 'stale hook temporary');
+      if (state.symlink || !state.file) {
+        throw pathError(`refusing stale hook temporary cleanup for non-file or symlink: ${path}`);
+      }
+      if (nowMs - state.mtimeMs < STALE_HOOK_TEMP_AGE_MS) continue;
+      await unlink(path);
+      removed.push(path);
+    }
+  }
+  return removed;
+}
+
+async function writeManifestEntry(
+  root,
+  report,
+  reviewed,
+  { onBeforeTargetRename, onBeforeTargetCreate } = {},
+) {
+  await ensureParentDirectoriesNoFollow(root, report.path);
+  const targetPath = join(root, report.path);
+  let bytes;
+  let mode;
+  if (report.kind === 'claude-hook-entries') {
+    if (reviewed.inspected.present) {
+      const merged = mergeClaudeHookEntries(
+        reviewed.liveSettings,
+        report.expectedBlock,
+        report.managedClaudeTargets,
+        root,
+      );
+      bytes = Buffer.from(`${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+      mode = reviewed.inspected.mode & 0o777;
+    } else {
+      bytes = await readRegularFileNoFollow(report.sourcePath, report.shippedTemplate);
+      mode = 0o644;
+    }
+  } else {
+    bytes = report.expectedBytes;
+    mode = report.executable ? 0o755 : reviewed.inspected.present ? reviewed.inspected.mode & 0o777 : 0o644;
+  }
+  try {
+    await writeAtomicFileNoFollow({
+      path: targetPath,
+      bytes,
+      mode: mode || 0o600,
+      exclusiveTarget: !report.reviewedPresent,
+      onBeforeRename: async () => {
+        await onBeforeTargetRename?.(report);
+        const finalReview = await reviewedTargetAtWriteBoundary(root, report);
+        if (!finalReview.matches) {
+          throw changedSinceReviewError(report.path, finalReview.detail);
+        }
+        atomicTestPhase('before-hook-rename');
+      },
+      onBeforeExclusiveCreate: async () => onBeforeTargetCreate?.(report),
+      onAfterRename: () => atomicTestPhase('after-hook-rename'),
+    });
+  } catch (error) {
+    if (error?.code !== 'PHR_ATOMIC_TARGET_EXISTS') throw error;
+    throw changedSinceReviewError(
+      report.path,
+      'the path was missing when reviewed but appeared before exclusive creation',
+    );
+  }
+  return { bytes, mode, reserializedSettings: report.kind === 'claude-hook-entries' };
+}
+
+async function currentEmissionAtStampBoundary(root, report) {
+  const inspected = await inspectInstallPath(root, report.path);
+  if (inspected.unsafe || inspected.symlink || !inspected.file) {
+    return { current: false, detail: inspected.detail || 'stamped target is missing or unsafe' };
+  }
+  const liveBytes = await readRegularFileNoFollow(join(root, report.path), report.path);
+  if (report.kind === 'claude-hook-entries') {
+    let settings;
+    try {
+      settings = parseClaudeSettings(liveBytes, report.path);
+    } catch (error) {
+      return { current: false, detail: error.message };
+    }
+    const liveBlock = managedClaudeBlock(settings, report.managedClaudeTargets, root);
+    if (!managedBlockBytes(liveBlock).equals(report.expectedBytes)) {
+      return { current: false, detail: 'managed Claude hook entries changed before provenance commit' };
+    }
+    return { current: true };
+  }
+  if (!liveBytes.equals(report.expectedBytes)) {
+    return { current: false, detail: 'hook bytes changed before provenance commit' };
+  }
+  if (report.executable && !(inspected.mode & 0o111)) {
+    return { current: false, detail: 'hook executable mode changed before provenance commit' };
+  }
+  return { current: true };
+}
+
+function stampEntryFor(report, stampedAt) {
+  return {
+    path: report.path,
+    shipped_template: report.shippedTemplate,
+    sha256: report.expectedHash,
+    cli_version: CLI_VERSION,
+    stamped_at: stampedAt,
+  };
+}
+
+async function writeHookStamp(root, priorStamp, reports, stampedAt) {
+  const manifestEntries = new Map(reports.all.map((report) => [report.path, report]));
+  const next = new Map(
+    (priorStamp?.files || [])
+      .filter((entry) => (
+        manifestEntries.get(entry.path)?.shippedTemplate === entry.shipped_template
+      ))
+      .map((entry) => [entry.path, entry]),
+  );
+  for (const report of reports.stamped) next.set(report.path, stampEntryFor(report, stampedAt));
+  const files = reports.all.flatMap(({ path }) => next.has(path) ? [next.get(path)] : []);
+  const value = { schema_version: 1, scope: 'hooks', files };
+  validateHookStamp(value);
+
+  const stampPath = join(root, HOOK_STAMP_REL);
+  const inspected = await inspectInstallPath(root, HOOK_STAMP_REL);
+  const mode = inspected.present && inspected.file ? inspected.mode & 0o777 : 0o644;
+  await writeAtomicFileNoFollow({
+    path: stampPath,
+    bytes: Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8'),
+    mode: mode || 0o600,
+    onBeforeRename: async () => {
+      for (const report of reports.stamped) {
+        const verification = await currentEmissionAtStampBoundary(root, report);
+        if (!verification.current) {
+          throw changedSinceReviewError(report.path, verification.detail);
+        }
+      }
+      atomicTestPhase('before-hook-stamp-rename');
+    },
+    onAfterRename: () => atomicTestPhase('after-hook-stamp-rename'),
+  });
+  console.log(`Wrote ${HOOK_STAMP_REL} for ${reports.stamped.length} re-stamped path(s).`);
+  return value;
+}
+
+function printCodexTrustGuidance(stamped) {
+  const codexScripts = stamped.filter(({ path }) => path.includes('/.codex/hooks/'));
+  const hooksJsonChanged = stamped.some(({ path }) => path.endsWith('/.codex/hooks.json'));
+  if (!codexScripts.length && !hooksJsonChanged) return;
+
+  console.log('');
+  console.log(
+    'Codex trust (empirically verified 2026-07-18 on v0.145.0-alpha.18): per-hook trust keys on the hooks.json config registration, not hook-script bytes.',
+  );
+  console.log(
+    'Script-only re-stamps do not invalidate trust on that v0.145-class build, so no script-only re-trust prompt is promised; later Codex versions may change this behavior.',
+  );
+  console.log(
+    'On that version, a trusted script byte change is not re-verified by Codex; this refresh does not imply byte-level re-verification.',
+  );
+  if (hooksJsonChanged) {
+    console.log(
+      'A hooks.json registration changed. Expect Codex\'s "Hooks need review" banner and review the registrations with `/hooks` or Settings → Hooks.',
+    );
+  }
+}
+
+async function offerLauncher({
+  home,
+  persist,
+  isTTY,
+  inspectManagedLauncher,
+  installManagedLauncher,
+  promptLauncher,
+  promptPath,
+  hookOutcome,
+}) {
+  const launcher = inspectManagedLauncher({ home });
+  if (launcher.compliant) {
+    return { offered: false, launcher };
+  }
+
+  const issues = launcher.issues || [];
+  const absent = issues.some(({ code }) => code === 'not-installed');
+  const backend = launcher.manifest?.PHR_BACKEND || null;
+  const selfCopyOwned = backend === 'self-copy';
+  console.log('');
+  for (const issue of issues) console.error(`Launcher issue ${issue.code}: ${issue.detail}`);
+  if (backend === 'app') {
+    console.log('The unhealthy launcher is app-owned; hooks refresh will not replace it with a self-copy launcher.');
+    console.log('Use the Phronesis desktop app’s Install command-line tools action to repair it, or use `phronesis launcher remove` before intentionally switching ownership.');
+    console.log(hookOutcome);
+    console.log('PATH-isolated surfaces may stay inactive until the app-owned launcher is repaired.');
+    return { offered: false, installed: false, status: 'app-owned-not-clobbered', launcher };
+  }
+  if (!absent && !selfCopyOwned) {
+    console.log('Launcher ownership is invalid or unreadable; hooks refresh will not force a self-copy replacement.');
+    console.log('Resolve the reported launcher.env/dispatcher issue, then run `phronesis launcher install` again.');
+    console.log(hookOutcome);
+    console.log('PATH-isolated surfaces may stay inactive until launcher ownership is resolved.');
+    return { offered: false, installed: false, status: 'ownership-unresolved', launcher };
+  }
+
+  console.log(
+    absent
+      ? 'No managed launcher is installed. Refreshed hooks are still inactive in PATH-isolated surfaces until the launcher is installed.'
+      : 'The self-copy launcher is unhealthy. Refreshed hooks may remain inactive until launcher install repairs it.',
+  );
+  let accepted = persist === true;
+  if (persist === undefined && isTTY) {
+    accepted = await promptLauncher({ message: PERSISTENCE_PROMPT });
+  }
+  if (!accepted) {
+    console.log('Install or repair it when ready: `phronesis launcher install`.');
+    return { offered: true, installed: false, launcher };
+  }
+  const installed = await installManagedLauncher({ home, isTTY, promptPath });
+  return { offered: true, installed: true, status: 'installed', result: installed, launcher };
+}
+
+function describeHookOutcome(stamped, refused) {
+  const summary = `Hook refresh outcome: ${stamped.length} re-stamped, ${refused.length} refused`;
+  if (!refused.length) return `${summary}.`;
+  const reasons = refused.map(({ path, status, detail }) => (
+    `${path} (${status}: ${detail})`
+  ));
+  return `${summary}: ${reasons.join('; ')}.`;
+}
+
+export async function runHooksRefresh({
+  dir,
+  apply = [],
+  applyAll = false,
+  persist,
+  isTTY = Boolean(process.stdin.isTTY),
+  home = homedir(),
+  templatesDir = TEMPLATES_DIR,
+  now = () => new Date(),
+  promptRestamp = confirmHookRestamp,
+  promptLauncher = confirmPersistence,
+  promptPath = confirmPathAppend,
+  inspectManagedLauncher = inspectLauncher,
+  installManagedLauncher = runLauncherInstall,
+  onBeforeTargetRename,
+  onBeforeTargetCreate,
+} = {}) {
+  const installed = resolveInstall({ dir });
+  if (installed.error) {
+    console.error(`hooks refresh: ${installed.error}`);
+    process.exitCode = 1;
+    return { error: installed.error };
+  }
+  const root = await realpath(installed.root);
+  const manifest = await buildHookManifest(root, { templatesDir });
+
+  let stamp = null;
+  let stampError = null;
+  try {
+    stamp = await loadHookStamp(root);
+  } catch (error) {
+    stampError = error;
+  }
+  const stampByPath = new Map((stamp?.files || []).map((entry) => [entry.path, entry]));
+  const reports = [];
+  for (const entry of manifest.entries) {
+    reports.push(await classifyManifestEntry(
+      root,
+      entry,
+      stampByPath.get(entry.path),
+    ));
+  }
+  const extras = await findUnknownSiblings(root, manifest.entries);
+  printReport(root, reports, extras);
+
+  if (stampError) {
+    console.error(stampError.message);
+    console.error('No writes or launcher changes were attempted because hook provenance is unreadable.');
+    process.exitCode = 1;
+    return { root, reports, extras, error: stampError.message };
+  }
+
+  const byPath = new Map(reports.map((report) => [report.path, report]));
+  const requested = Array.isArray(apply) ? apply : [apply];
+  for (const path of requested) {
+    if (!byPath.has(path)) {
+      console.error(`hooks refresh: --apply target is not in the derived hook manifest: ${path}`);
+      process.exitCode = 1;
+      return { root, reports, extras, error: `unknown apply target ${path}` };
+    }
+  }
+
+  const actionable = reports.filter(({ status }) => status !== 'current');
+  // A TTY prompt that already has drift to resolve may also complete provenance
+  // for current unstamped paths. A wholly current fresh install remains quiet;
+  // crash recovery with no other drift is available through the same explicit
+  // `--apply <path>` authority that initiated the interrupted write.
+  const promptCandidates = actionable.length
+    ? reports.filter((report) => (
+      report.status !== 'current' || report.disposition === 'unstamped'
+    ))
+    : [];
+  let selectedPaths;
+  if (applyAll) selectedPaths = actionable
+    .filter(({ disposition }) => disposition === 'safe')
+    .map(({ path }) => path);
+  else if (requested.length) selectedPaths = [...new Set(requested)];
+  else if (isTTY && promptCandidates.length) {
+    const consent = await promptRestamp({
+      entries: promptCandidates.map(({ path, shippedTemplate, disposition, status }) => ({
+        path,
+        shippedTemplate,
+        disposition,
+        status,
+      })),
+    });
+    if (Array.isArray(consent)) selectedPaths = consent;
+    else {
+      const blanket = (consent?.blanket || []).filter((path) => (
+        byPath.get(path)?.disposition === 'safe'
+      ));
+      selectedPaths = [...blanket, ...(consent?.targeted || [])];
+    }
+  } else selectedPaths = [];
+
+  const selected = [...new Set(selectedPaths || [])]
+    .map((path) => byPath.get(path))
+    .filter((report) => report && (
+      report.status !== 'current' || report.disposition === 'unstamped'
+    ));
+
+  let stamped = [];
+  let written = [];
+  const refused = [];
+  if (selected.length) {
+    const stampInspection = await inspectInstallPath(root, HOOK_STAMP_REL);
+    if (stampInspection.unsafe || stampInspection.symlink || (stampInspection.present && !stampInspection.file)) {
+      throw pathError(
+        `refusing non-file or symlinked ${HOOK_STAMP_REL}; no hook path was changed`,
+      );
+    }
+    if (stampInspection.present) assertOwned(join(root, HOOK_STAMP_REL), stampInspection, HOOK_STAMP_REL);
+    for (const report of selected) await preflightWrite(root, report);
+    // Crash residue is removed only inside an explicitly approved apply. Inspecting
+    // and cleaning it before any target write also makes a planted symlink fail the
+    // whole apply before hook bytes move.
+    const operationTime = now();
+    const stampedAt = operationTime.toISOString();
+    await cleanupAgedManagedTemps(root, manifest.entries, operationTime.getTime());
+
+    for (const report of selected) {
+      const reviewed = await reviewedTargetAtWriteBoundary(root, report);
+      if (!reviewed.matches) {
+        const refusal = { path: report.path, status: 'changed-since-review', detail: reviewed.detail };
+        refused.push(refusal);
+        console.error(`  changed-since-review ${report.path} — ${reviewed.detail}; no bytes or provenance were written for this path`);
+        process.exitCode = 1;
+        continue;
+      }
+
+      if (report.status === 'current') {
+        stamped.push(report);
+        console.log(`Recorded provenance for already-current ${report.path}; hook bytes were not rewritten.`);
+        continue;
+      }
+
+      let result;
+      try {
+        result = await writeManifestEntry(root, report, reviewed, {
+          onBeforeTargetRename,
+          onBeforeTargetCreate,
+        });
+      } catch (error) {
+        if (error?.code !== 'PHR_HOOK_CHANGED_SINCE_REVIEW') throw error;
+        const refusal = { path: report.path, status: 'changed-since-review', detail: error.detail };
+        refused.push(refusal);
+        console.error(`  changed-since-review ${report.path} — ${error.detail}; no bytes or provenance were written for this path`);
+        process.exitCode = 1;
+        continue;
+      }
+      stamped.push(report);
+      written.push(report);
+      console.log(`Re-stamped ${report.path} from ${report.shippedTemplate}.`);
+      if (result.reserializedSettings) {
+        console.log('  .claude/settings.json was re-serialized; every non-managed key, hook, and value was preserved semantically.');
+      }
+    }
+    if (stamped.length) {
+      try {
+        await writeHookStamp(root, stamp, { all: reports, stamped }, stampedAt);
+      } catch (error) {
+        if (error?.code !== 'PHR_HOOK_CHANGED_SINCE_REVIEW') throw error;
+        if (!refused.some(({ path }) => path === error.path)) {
+          refused.push({ path: error.path, status: 'changed-since-review', detail: error.detail });
+        }
+        console.error(`  changed-since-review ${error.path} — ${error.detail}; hook provenance was not committed`);
+        process.exitCode = 1;
+        stamped = [];
+      }
+      printCodexTrustGuidance(written);
+    }
+  } else if (actionable.length) {
+    console.log(
+      applyAll
+        ? 'Report only for non-safe paths. `--apply-all` applies only safely attributable stamped updates; name unstamped or operator-modified paths with `--apply <path>`.'
+        : 'Report only. Re-run with `--apply <path>` or `--apply-all` to approve writes off-TTY.',
+    );
+  } else {
+    console.log('All derived hook-manifest paths are current; no files were rewritten.');
+  }
+
+  let launcher;
+  const hookOutcome = describeHookOutcome(stamped, refused);
+  try {
+    launcher = await offerLauncher({
+      home,
+      persist,
+      isTTY,
+      inspectManagedLauncher,
+      installManagedLauncher,
+      promptLauncher,
+      promptPath,
+      hookOutcome,
+    });
+  } catch (error) {
+    console.error(`Launcher install failed: ${error.message}`);
+    console.error(hookOutcome);
+    console.error('The separate launcher installation step failed.');
+    process.exitCode = 1;
+    const launcherFailure = {
+      offered: true,
+      installed: false,
+      status: 'install-failed',
+      error: error.message,
+    };
+    return {
+      root,
+      reports,
+      extras,
+      stamped,
+      written,
+      refused,
+      launcher: launcherFailure,
+      ...(stamped.length ? {} : { error: error.message }),
+    };
+  }
+  return { root, reports, extras, stamped, written, refused, launcher };
+}
+
+export {
+  HOOK_STAMP_REL,
+  buildHookManifest,
+  managedClaudeBlock,
+  mergeClaudeHookEntries,
+  validateHookStamp,
+};