optbrew 0.0.0-stage → 0.1.2

package/lib/cli.mjs

@@ -0,0 +1,116 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { install } from './install.mjs';
+import { doctor } from './doctor.mjs';
+import { supportedAgents, scopePaths } from './paths.mjs';
+import { checkUpdates, update, rollback } from './update.mjs';
+import { readFile } from 'node:fs/promises';
+import { readInstallRecord } from './records.mjs';
+import { runCli } from '../skills/optbrew/scripts/cli.mjs';
+import { reinstallPlan } from './reinstall.mjs';
+
+const defaultBundle = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../skills/optbrew');
+class UsageError extends Error {}
+const usage = 'usage: optbrew <install|doctor|check-updates|update|rollback|reinstall-plan|score|compare|report> [options]';
+
+function parseOptions(argv, allowed) {
+  const options = {};
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i];
+    if (!allowed.includes(key) || key in options) throw new UsageError(`unknown or repeated option: ${key}`);
+    if (key === '--json' || key === '--dry-run') options[key] = true;
+    else {
+      if (!argv[i + 1] || argv[i + 1].startsWith('--')) throw new UsageError(`missing value for ${key}`);
+      options[key] = argv[++i];
+    }
+  }
+  return options;
+}
+
+function installOptions(argv, command, { cwd, env }) {
+  const allowed = ['--agents', '--scope', '--project', '--home', '--json'];
+  if (command === 'install') allowed.push('--dry-run', '--strategy');
+  const parsed = parseOptions(argv, allowed);
+  if (!parsed['--agents']) throw new UsageError('--agents is required');
+  const agents = parsed['--agents'].split(',');
+  if (agents.some(agent => !supportedAgents.includes(agent)) || new Set(agents).size !== agents.length) throw new UsageError('invalid or duplicate agent');
+  const scope = parsed['--scope'] ?? 'user';
+  if (!['user', 'project'].includes(scope)) throw new UsageError('--scope must be user or project');
+  if (scope === 'project' && !parsed['--project']) throw new UsageError('project scope requires --project');
+  if (scope === 'user' && parsed['--project']) throw new UsageError('--project requires project scope');
+  const strategy = parsed['--strategy'] ?? 'link';
+  if (!['link', 'copy'].includes(strategy)) throw new UsageError('--strategy must be link or copy');
+  return { agents, scope, home: parsed['--home'] ? path.resolve(cwd, parsed['--home']) : env?.HOME ?? os.homedir(),
+    projectRoot: parsed['--project'] ? path.resolve(cwd, parsed['--project']) : undefined,
+    dryRun: Boolean(parsed['--dry-run']), strategy, json: Boolean(parsed['--json']) };
+}
+
+function computeArgs(argv, command, cwd) {
+  const keys = command === 'score' ? ['--input', '--output'] : command === 'compare' ? ['--before', '--after', '--output'] : ['--input', '--output-dir'];
+  const opts = parseOptions(argv, keys);
+  if (keys.some(k => !opts[k])) throw new UsageError(`missing ${keys.filter(k => !opts[k]).join(', ')}`);
+  return [command, ...keys.flatMap(k => [k, path.resolve(cwd, opts[k])])];
+}
+
+/** Return CLI process code: 0 success, 2 argument error, 1 environment or file failure. */
+export async function main(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd(), bundleRoot = defaultBundle, registryTransport } = {}) {
+  try {
+    const [command, ...rest] = argv;
+    if (['score', 'compare', 'report'].includes(command)) {
+      await runCli(computeArgs(rest, command, cwd));
+      stdout.write(`${command} complete\n`);
+      return 0;
+    }
+    if (!['install', 'doctor', 'check-updates', 'update', 'rollback', 'reinstall-plan'].includes(command)) throw new UsageError(usage);
+    if (command === 'reinstall-plan') {
+      // Read-only: validates the install record and prints what the documented manual reinstall may delete.
+      const parsed = parseOptions(rest, ['--scope', '--home', '--project']);
+      const scope = parsed['--scope'] ?? 'user';
+      if (!['user', 'project'].includes(scope)) throw new UsageError('--scope must be user or project');
+      if (scope === 'project' && !parsed['--project']) throw new UsageError('project scope requires --project');
+      if (scope === 'user' && parsed['--project']) throw new UsageError('--project requires project scope');
+      const rows = await reinstallPlan({ scope, home: parsed['--home'] ? path.resolve(cwd, parsed['--home']) : env?.HOME ?? os.homedir(),
+        projectRoot: parsed['--project'] ? path.resolve(cwd, parsed['--project']) : undefined });
+      stdout.write(`${rows.map(row => row.join('\t')).join('\n')}\n`);
+      return 0;
+    }
+    if (command === 'check-updates') {
+      const parsed = parseOptions(rest, ['--package', '--json']);
+      const manifest = JSON.parse(await readFile(path.join(bundleRoot, 'bundle-manifest.json'), 'utf8'));
+      const result = await checkUpdates({ packageName: parsed['--package'], currentVersion: manifest.release_version, registryTransport });
+      stdout.write(`${JSON.stringify(result, null, parsed['--json'] ? 2 : 0)}\n`);
+      return 0;
+    }
+    if (command === 'update' || command === 'rollback') {
+      const allowed = ['--record-root', '--scope', '--home', '--project', '--agents', '--json'];
+      allowed.push(command === 'update' ? '--local-changes' : '--release-version');
+      const parsed = parseOptions(rest, allowed);
+      if (parsed['--record-root'] && ['--scope', '--home', '--project'].some(k => parsed[k])) throw new UsageError('--record-root cannot be combined with scope options');
+      const scope = parsed['--scope'] ?? 'user';
+      if (scope === 'user' && parsed['--project']) throw new UsageError('--project requires project scope');
+      const recordRoot = parsed['--record-root'] ? path.resolve(cwd, parsed['--record-root']) : scopePaths({ scope,
+        home: parsed['--home'] ? path.resolve(cwd, parsed['--home']) : env?.HOME ?? os.homedir(),
+        projectRoot: parsed['--project'] ? path.resolve(cwd, parsed['--project']) : undefined }).managedRoot;
+      if (parsed['--agents']) {
+        const selected = parsed['--agents'].split(',');
+        if (selected.some(agent => !supportedAgents.includes(agent)) || new Set(selected).size !== selected.length) throw new UsageError('invalid or duplicate agent');
+        const record = await readInstallRecord(recordRoot);
+        if (!record) throw new Error('install record missing');
+        if (JSON.stringify(selected.sort()) !== JSON.stringify(record.targets.map(t => t.agent).sort())) throw new UsageError('update/rollback requires all recorded targets; partial updates are unavailable');
+      }
+      if (command === 'rollback' && !parsed['--release-version']) throw new UsageError('--release-version is required');
+      const result = command === 'update' ? await update({ bundleRoot, recordRoot, localChanges: parsed['--local-changes'] ?? 'abort' }) :
+        await rollback({ recordRoot, releaseVersion: parsed['--release-version'] });
+      stdout.write(`${JSON.stringify(result, null, parsed['--json'] ? 2 : 0)}\n`);
+      return ['updated', 'rolled_back', 'unchanged'].includes(result.status) ? 0 : 1;
+    }
+    const options = installOptions(rest, command, { cwd, env });
+    const result = command === 'install' ? await install({ ...options, bundleRoot }) : await doctor(options);
+    stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : `${JSON.stringify(result)}\n`);
+    return 0;
+  } catch (error) {
+    stderr.write(`${error.message}\n`);
+    return error instanceof UsageError || error instanceof TypeError ? 2 : 1;
+  }
+}

package/lib/doctor.mjs

@@ -0,0 +1,45 @@
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { verifyBundle } from '../skills/optbrew/scripts/core/bundle.mjs';
+import { readInstallRecord } from './records.mjs';
+import { resolveTargets, scopePaths } from './paths.mjs';
+import { validateScope } from './transaction.mjs';
+
+async function exists(name) {
+  try { await lstat(name); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+export async function doctor({ agents, scope, home, projectRoot }) {
+  const { scopeRoot, managedRoot } = scopePaths({ scope, home, projectRoot });
+  const selected = resolveTargets({ agents, scope, home, projectRoot });
+  const warnings = [];
+  let record;
+  try { record = await readInstallRecord(managedRoot); if (record) await validateScope(managedRoot, record); }
+  catch (error) { warnings.push(`install record unreadable: ${error.message}`); record = null; }
+  const recoveryPending = await exists(path.join(managedRoot, 'transaction.json'));
+  if (recoveryPending) warnings.push('recovery_required: interrupted transaction; rerun update/rollback to recover before use');
+  if (record?.transaction?.state === 'pending') warnings.push('initial install pending: finish optbrew install before updating');
+  const results = [];
+  for (const target of selected) {
+    const saved = record?.targets.find(t => t.agent === target.agent && t.path === target.path);
+    const filePresent = await exists(path.join(target.path, 'SKILL.md'));
+    let hashOk = false;
+    if (filePresent && saved && record) {
+      try {
+        if (saved.strategy === 'link' && await realpath(target.path) !== await realpath(path.join(managedRoot, 'bundle'))) throw new Error('link target changed');
+        if (saved.strategy === 'copy' && (await lstat(target.path)).isSymbolicLink()) throw new Error('copy replaced by link');
+        const manifest = JSON.parse(await readFile(path.join(target.path, 'bundle-manifest.json'), 'utf8'));
+        const check = await verifyBundle({ bundleRoot: target.path, manifest });
+        if (check.errors.some(e => e.code === 'migration_required')) warnings.push(`${target.agent}: installed release ${manifest.release_version} was built for another evaluation version; update is refused (migration_required). See docs/platforms.md, "Reinstall after a migration_required update".`);
+        hashOk = !recoveryPending && record.transaction.state === 'committed' && check.status === 'valid' && check.bundle_hash === record.bundle_hash && manifest.release_version === record.release_version;
+      } catch (error) { warnings.push(`${target.agent}: ${error.message}`); }
+    }
+    results.push({ agent: target.agent, path: target.path, file_present: filePresent, hash_ok: hashOk,
+      registered: Boolean(saved), session_discovery: 'not_verified', invocation_verified: 'not_verified' });
+  }
+  if (agents.includes('codex') || agents.includes('cursor') || agents.includes('opencode') || agents.includes('pi')) {
+    warnings.push('Shared .agents skill paths may also be discovered by other hosts; only selected targets are registered here.');
+  }
+  if (agents.includes('pi')) warnings.push('Pi custom PI_CODING_AGENT_DIR and project trust settings are not inspected.');
+  return { scope_id: `${scope}:${scopeRoot}`, release_version: record?.release_version ?? null, targets: results, warnings };
+}

package/lib/install.mjs

@@ -0,0 +1,158 @@
+import { cp, lstat, mkdir, open, readFile, realpath, rename, rm, symlink } from 'node:fs/promises';
+import path from 'node:path';
+import { isDistributedBundlePath, verifyBundle } from '../skills/optbrew/scripts/core/bundle.mjs';
+import { readInstallRecord, writeInstallRecord } from './records.mjs';
+import { resolveTargets, scopePaths } from './paths.mjs';
+
+async function statOrNull(name) {
+  try { return await lstat(name); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+async function rejectLinkedAncestors(scopeRoot, destination) {
+  const relative = path.relative(scopeRoot, destination);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`outside scope: ${destination}`);
+  let current = scopeRoot;
+  if ((await statOrNull(current))?.isSymbolicLink()) throw new Error(`scope root is a link: ${current}`);
+  for (const part of relative.split(path.sep).slice(0, -1)) {
+    current = path.join(current, part);
+    if ((await statOrNull(current))?.isSymbolicLink()) throw new Error(`junction/link ancestor outside trusted scope: ${current}`);
+  }
+}
+
+async function verifiedManifest(bundleRoot) {
+  if ((await lstat(bundleRoot)).isSymbolicLink()) throw new Error(`bundle root is a link: ${bundleRoot}`);
+  const manifest = JSON.parse(await readFile(path.join(bundleRoot, 'bundle-manifest.json'), 'utf8'));
+  const verification = await verifyBundle({ bundleRoot, manifest });
+  if (verification.status !== 'valid') throw new Error(`bundle integrity failed: ${verification.errors.map(e => `${e.path}:${e.code}`).join(', ')}`);
+  return { manifest, verification };
+}
+
+async function targetOwned(target, record, managedBundle) {
+  const existing = await statOrNull(target.path);
+  const saved = record?.targets.find(item => item.agent === target.agent && item.path === target.path);
+  if (!existing) {
+    if (saved) throw new Error(`registered target missing: ${target.path}`);
+    return false;
+  }
+  if (!saved || saved.managed_target !== managedBundle) throw new Error(`unmanaged optbrew target exists: ${target.path}`);
+  if (saved.strategy === 'link') {
+    if (!existing.isSymbolicLink() || await realpath(target.path) !== await realpath(managedBundle)) throw new Error(`registered link changed: ${target.path}`);
+  } else if (saved.strategy === 'copy') {
+    if (!existing.isDirectory() || existing.isSymbolicLink()) throw new Error(`registered copy changed: ${target.path}`);
+    const check = await verifiedManifest(target.path);
+    if (check.manifest.bundle_hash !== record.bundle_hash) throw new Error(`registered copy changed: ${target.path}`);
+  } else throw new Error(`invalid recorded strategy: ${saved.strategy}`);
+  return true;
+}
+
+/** Initial install and additive target registration; version changes belong to update. */
+export async function install({ bundleRoot, agents, scope, home, projectRoot, dryRun = false, strategy = 'link' }) {
+  if (!['link', 'copy'].includes(strategy)) throw new TypeError('strategy must be link or copy');
+  const { scopeRoot, managedRoot } = scopePaths({ scope, home, projectRoot });
+  const targets = resolveTargets({ agents, scope, home, projectRoot }).map(t => ({ ...t, strategy }));
+  const source = await verifiedManifest(bundleRoot);
+  for (const target of targets) await rejectLinkedAncestors(scopeRoot, target.path);
+  await rejectLinkedAncestors(scopeRoot, path.join(managedRoot, 'bundle'));
+
+  async function inspect() {
+    if (await statOrNull(path.join(managedRoot, 'transaction.json'))) {
+      // Single-quoted literals: neither PowerShell nor a POSIX shell expands $ or backticks inside them.
+      const powershell = `'${managedRoot.replaceAll("'", "''")}'`, posix = `'${managedRoot.replaceAll("'", "'\\''")}'`;
+      throw new Error(`recovery_required: interrupted transaction; run optbrew update before install. PowerShell: optbrew update --record-root ${powershell}; POSIX shell: optbrew update --record-root ${posix}`);
+    }
+    const record = await readInstallRecord(managedRoot);
+    if (record) {
+      if (record.managed_root !== managedRoot || record.scope_id !== `${scope}:${scopeRoot}`) throw new Error('install record scope mismatch');
+      if (record.bundle_hash !== source.manifest.bundle_hash || record.release_version !== source.manifest.release_version) throw new Error('existing release differs; use optbrew update');
+      const managed = await verifiedManifest(path.join(managedRoot, 'bundle'));
+      if (managed.manifest.bundle_hash !== record.bundle_hash) throw new Error('managed bundle differs from record');
+      for (const saved of record.targets) {
+        const canonical = resolveTargets({ agents: [saved.agent], scope, home, projectRoot })[0];
+        if (saved.path !== canonical.path || saved.managed_target !== canonical.managed_target) throw new Error('install record target path mismatch');
+        await rejectLinkedAncestors(scopeRoot, saved.path);
+        await targetOwned(saved, record, path.join(managedRoot, 'bundle'));
+      }
+    } else if (await statOrNull(path.join(managedRoot, 'bundle'))) throw new Error('unmanaged bundle exists');
+    for (const target of targets) await targetOwned(target, record, path.join(managedRoot, 'bundle'));
+    return record;
+  }
+
+  const before = await inspect();
+  const pending = targets.filter(t => !before?.targets.some(saved => saved.agent === t.agent));
+  const decision = { strategy, targets, pending: pending.map(t => t.path), release_version: source.manifest.release_version };
+  if (dryRun) return { status: 'dry_run', dry_run: true, record: null, changed_paths: [], decision, verification: source.verification };
+
+  await mkdir(managedRoot, { recursive: true });
+  const lockPath = path.join(managedRoot, 'install.lock');
+  let lock;
+  try { lock = await open(lockPath, 'wx'); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error('scope install lock already held'); throw error; }
+  const changed = [];
+  try {
+    const record = await inspect();
+    const toAdd = targets.filter(t => !record?.targets.some(saved => saved.agent === t.agent));
+    const managedBundle = path.join(managedRoot, 'bundle');
+    let next = record;
+    if (!record) {
+      const staging = path.join(managedRoot, `bundle.${process.pid}.${Date.now()}.tmp`);
+      try {
+        await cp(bundleRoot, staging, { recursive: true, errorOnExist: true, force: false, dereference: false,
+          filter: sourcePath => isDistributedBundlePath(path.relative(bundleRoot, sourcePath)) });
+        const copied = await verifiedManifest(staging);
+        if (copied.manifest.bundle_hash !== source.manifest.bundle_hash) throw new Error('staged bundle changed');
+        await rename(staging, managedBundle);
+        changed.push(managedBundle);
+      } finally { await rm(staging, { recursive: true, force: true }); }
+      next = {
+        schema_version: '1.0.0', scope_id: `${scope}:${scopeRoot}`, release_version: source.manifest.release_version,
+        bundle_hash: source.manifest.bundle_hash, source: path.resolve(bundleRoot), managed_root: managedRoot,
+        targets: [], file_hashes: Object.fromEntries(source.manifest.files.map(f => [f.path, f.sha256])),
+        previous_releases: [], transaction: { state: 'pending' }, source_ref: 'bundle-manifest.json',
+      };
+      try { await writeInstallRecord(managedRoot, next); }
+      catch (error) {
+        // Only remove the bundle this invocation created, if no record took ownership of it.
+        if (!(await readInstallRecord(managedRoot)) &&
+            (await verifiedManifest(managedBundle)).manifest.bundle_hash === source.manifest.bundle_hash) {
+          await rm(managedBundle, { recursive: true, force: true });
+        }
+        throw error;
+      }
+    }
+    for (const target of toAdd) {
+      await rejectLinkedAncestors(scopeRoot, target.path);
+      if (await statOrNull(target.path)) throw new Error(`unmanaged optbrew target exists: ${target.path}`);
+      await mkdir(path.dirname(target.path), { recursive: true });
+      if (strategy === 'link') {
+        try { await symlink(managedBundle, target.path, process.platform === 'win32' ? 'junction' : 'dir'); }
+        catch (error) { throw new Error(`link unavailable for ${target.path}; retry explicitly with --strategy copy (${error.message})`); }
+      } else {
+        const staging = `${target.path}.${process.pid}.${Date.now()}.tmp`;
+        try {
+          await cp(managedBundle, staging, { recursive: true, errorOnExist: true, force: false });
+          await verifiedManifest(staging);
+          await rename(staging, target.path);
+        } finally { await rm(staging, { recursive: true, force: true }); }
+      }
+      changed.push(target.path);
+      next.targets = [...next.targets, target];
+      next.transaction = { state: 'pending' };
+      try { await writeInstallRecord(managedRoot, next); }
+      catch (error) {
+        // A write failure leaves the previous record intact. Undo only this newly created target.
+        const current = await statOrNull(target.path);
+        if (current?.isSymbolicLink() && await realpath(target.path) === await realpath(managedBundle)) await rm(target.path);
+        else if (current?.isDirectory() && !current.isSymbolicLink() &&
+                 (await verifiedManifest(target.path)).manifest.bundle_hash === source.manifest.bundle_hash) {
+          await rm(target.path, { recursive: true });
+        }
+        throw error;
+      }
+    }
+    if (next.transaction.state !== 'committed') {
+      next.transaction = { state: 'committed' };
+      await writeInstallRecord(managedRoot, next);
+    }
+    return { status: changed.length ? 'installed' : 'unchanged', dry_run: false, record: next, changed_paths: changed, decision, verification: source.verification };
+  } finally { await lock.close(); await rm(lockPath, { force: true }); }
+}

package/lib/paths.mjs

@@ -0,0 +1,30 @@
+import os from 'node:os';
+import path from 'node:path';
+
+const locations = {
+  codex: ['.agents/skills/optbrew', '.agents/skills/optbrew'],
+  'claude-code': ['.claude/skills/optbrew', '.claude/skills/optbrew'],
+  cursor: ['.cursor/skills/optbrew', '.cursor/skills/optbrew'],
+  opencode: ['.config/opencode/skills/optbrew', '.opencode/skills/optbrew'],
+  pi: ['.pi/agent/skills/optbrew', '.pi/skills/optbrew'],
+};
+
+export const supportedAgents = Object.keys(locations);
+
+export function scopePaths({ scope, home = os.homedir(), projectRoot }) {
+  if (scope !== 'user' && scope !== 'project') throw new TypeError('scope must be user or project');
+  if (scope === 'project' && !projectRoot) throw new TypeError('project scope requires --project');
+  const scopeRoot = path.resolve(scope === 'user' ? home : projectRoot);
+  return { scopeRoot, managedRoot: path.join(scopeRoot, scope === 'user' ? '.optbrew/installs/user' : '.optbrew/install') };
+}
+
+/** Fixed host paths confirmed against current host documentation. */
+export function resolveTargets({ agents, scope, home, projectRoot }) {
+  const { scopeRoot, managedRoot } = scopePaths({ scope, home, projectRoot });
+  if (!Array.isArray(agents) || !agents.length) throw new TypeError('at least one agent required');
+  if (new Set(agents).size !== agents.length) throw new TypeError('duplicate agent');
+  return agents.map(agent => {
+    if (!locations[agent]) throw new TypeError(`unknown agent: ${agent}`);
+    return { agent, path: path.join(scopeRoot, locations[agent][scope === 'user' ? 0 : 1]), strategy: 'link', managed_target: path.join(managedRoot, 'bundle') };
+  });
+}

package/lib/records.mjs

@@ -0,0 +1,44 @@
+import { mkdir, readFile, open, rename, rm, lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export function validateInstallRecord(record) {
+  if (record?.schema_version !== '1.0.0') throw new Error('migration_required: unsupported install record schema; use a compatible optbrew release');
+  if (!Array.isArray(record.targets) || !/^[a-f0-9]{64}$/.test(record.bundle_hash) ||
+      typeof record.managed_root !== 'string' || typeof record.scope_id !== 'string' ||
+      typeof record.release_version !== 'string' || !record.file_hashes || typeof record.file_hashes !== 'object' ||
+      !Array.isArray(record.previous_releases) || !['pending', 'committed'].includes(record.transaction?.state)) throw new Error('invalid install record');
+  if (Object.entries(record.file_hashes).some(([name, hash]) => path.isAbsolute(name) || name.split(/[\\/]/).includes('..') || !/^[a-f0-9]{64}$/.test(hash))) throw new Error('invalid install record file hashes');
+  return record;
+}
+
+/** Flush bytes before atomic replacement; callers hold the scope lock. */
+export async function writeDurableJson(file, value) {
+  const temp = `${file}.${randomUUID()}.tmp`;
+  try {
+    const handle = await open(temp, 'wx');
+    try { await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`); await handle.sync(); }
+    finally { await handle.close(); }
+    await rename(temp, file);
+    // Windows cannot open directories for fsync. File flush + rename remains atomic there.
+    if (process.platform !== 'win32') {
+      const directory = await open(path.dirname(file), 'r');
+      try { await directory.sync(); } finally { await directory.close(); }
+    }
+  } finally { await rm(temp, { force: true }); }
+}
+
+export async function readInstallRecord(scopeRoot) {
+  const file = path.join(scopeRoot, 'install-record.json');
+  try {
+    if ((await lstat(file)).isSymbolicLink()) throw new Error('install record is a link');
+    const record = JSON.parse(await readFile(file, 'utf8'));
+    return validateInstallRecord(record);
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+export async function writeInstallRecord(scopeRoot, record) {
+  await mkdir(scopeRoot, { recursive: true });
+  const file = path.join(scopeRoot, 'install-record.json');
+  await writeDurableJson(file, record);
+}

package/lib/reinstall.mjs

@@ -0,0 +1,92 @@
+import { lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { readInstallRecord } from './records.mjs';
+import { scopePaths } from './paths.mjs';
+import { validateScope, statOrNull } from './transaction.mjs';
+
+const powershell = value => `'${String(value).replaceAll("'", "''")}'`;
+const posix = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+/**
+ * Read-only plan for the manual reinstall of a managed scope. It validates the install record before anything is
+ * deleted: the record belongs to this scope, every recorded target is exactly the expected skills/optbrew path of its
+ * agent (absolute, no "..", no linked ancestor, inside the scope), and every target that exists is what the installer
+ * created (a link to the managed bundle, or a real directory holding a bundle manifest). Any failed check throws, so a
+ * caller that deletes only what this returns never deletes anything for a tampered record.
+ *
+ * Rows: `delete-link|delete-dir <path>` (recorded targets first, the managed root last), then `install <agent> <strategy>`
+ * per recorded agent in record order, then `agents <csv>` for the final doctor call.
+ */
+export async function reinstallPlan({ scope, home, projectRoot }) {
+  const refuse = message => { throw new Error(`reinstall plan refused: ${message}`); };
+  // One output line per path: a line break, tab or other control character would split a row or inject another one.
+  const plain = value => typeof value === 'string' && [...value].every(ch => { const c = ch.codePointAt(0); return c > 31 && (c < 127 || c > 159) && c !== 8232 && c !== 8233; });
+  const { scopeRoot, managedRoot } = scopePaths({ scope, home, projectRoot });
+  if (!plain(scopeRoot) || !plain(managedRoot)) refuse('the scope path contains a control character (a line break, tab or similar)');
+  const record = await readInstallRecord(managedRoot).catch(error => refuse(`install record unreadable (${error.message})`));
+  if (!record) refuse(`no install record in ${managedRoot}`);
+  if (record.scope_id !== `${scope}:${scopeRoot}` || record.managed_root !== managedRoot) refuse('the install record belongs to another scope');
+  if (!record.targets.length) refuse('the install record lists no target');
+  for (const target of record.targets) {
+    if (!plain(target.path) && typeof target.path === 'string') refuse('a recorded target path contains a control character (a line break, tab or similar)');
+    if (typeof target.path !== 'string' || !path.isAbsolute(target.path) || target.path.split(/[\\/]/).includes('..'))
+      refuse(`recorded target is not a plain absolute path: ${JSON.stringify(target.path)}`);
+  }
+  try { await validateScope(managedRoot, record); }
+  catch (error) { refuse(`${error.message} (expected exactly the agent's skills/optbrew path inside ${scopeRoot})`); }
+  const managedBundle = path.join(managedRoot, 'bundle');
+  const rows = [];
+  for (const target of record.targets) {
+    const found = await statOrNull(target.path);
+    if (!found) continue;
+    if (found.isSymbolicLink()) {
+      if (target.strategy !== 'link' || await realpath(target.path) !== await realpath(managedBundle))
+        refuse(`${target.path} is a link that does not lead to the managed bundle`);
+      rows.push(['delete-link', target.path]);
+    } else if (found.isDirectory()) {
+      if (target.strategy !== 'copy') refuse(`${target.path} was recorded as a link but is a directory`);
+      try { await lstat(path.join(target.path, 'bundle-manifest.json')); }
+      catch { refuse(`${target.path} holds no optbrew bundle manifest`); }
+      rows.push(['delete-dir', target.path]);
+    } else refuse(`${target.path} is neither a link nor a directory`);
+  }
+  rows.push(['delete-dir', managedRoot]);
+  for (const target of record.targets) rows.push(['install', target.agent, target.strategy]);
+  rows.push(['agents', record.targets.map(target => target.agent).join(',')]);
+  if (!rows.every(row => row.every(plain))) refuse('a path or name in the plan contains a control character (a line break, tab or similar)');
+  return rows;
+}
+
+/**
+ * Exact manual reinstall steps for a managed scope whose update was refused with migration_required.
+ * Targets are deleted first and the managed root (which holds the install record) last, so the steps can be repeated
+ * after a partial failure. `.optbrew/runs` is never deleted.
+ */
+export function reinstallGuidance({ record, recordRoot, from, to }) {
+  const separator = record.scope_id.indexOf(':');
+  const scope = record.scope_id.slice(0, separator), scopeRoot = record.scope_id.slice(separator + 1);
+  const agents = record.targets.map(target => target.agent).join(',');
+  const place = quote => scope === 'user' ? `--scope user --home ${quote(scopeRoot)}` : `--scope project --project ${quote(scopeRoot)}`;
+  const removePowershell = record.targets.map(target => target.strategy === 'link' ?
+    `[IO.Directory]::Delete(${powershell(target.path)})` : `Remove-Item -Recurse -Force -LiteralPath ${powershell(target.path)}`);
+  removePowershell.push(`Remove-Item -Recurse -Force -LiteralPath ${powershell(recordRoot)}`);
+  const removePosix = `rm -r -- ${[...record.targets.map(target => target.path), recordRoot].map(posix).join(' ')}`;
+  const install = quote => record.targets.map(target =>
+    `optbrew install --agents ${target.agent} ${place(quote)} --strategy ${target.strategy}`);
+  const doctor = quote => `optbrew doctor --agents ${agents} ${place(quote)}`;
+  return [
+    `Release ${to} uses a new evaluation contract, so a managed update from ${from} cannot carry this install over, and scores from the two releases are not comparable. Reinstall instead; your runs folder (${scopeRoot}/.optbrew/runs) is not touched, so never delete it.`,
+    '1. Check the install record first. This read-only command refuses a tampered record and prints exactly what will be deleted:',
+    `   optbrew reinstall-plan ${place(posix)}`,
+    '2. Delete only those paths, the targets first and the managed root last (repeat the same steps if one fails):',
+    '   PowerShell:',
+    ...removePowershell.map(line => `     ${line}`),
+    `   POSIX shell: ${removePosix}`,
+    '3. Install again, one command per recorded agent, from the checkout of the new release:',
+    ...['PowerShell', 'POSIX shell'].flatMap((label, i) => [`   ${label}:`, ...install(i ? posix : powershell).map(line => `     ${line}`)]),
+    '4. Verify:',
+    `   PowerShell: ${doctor(powershell)}`,
+    `   POSIX shell: ${doctor(posix)}`,
+    'The same steps as copy-paste blocks that do these checks for you: docs/platforms.md, "Reinstall after a migration_required update".',
+  ].join('\n');
+}