@rover-studio/answer-me 0.1.0-rc.1

package/lib/npm-cli/constants.mjs

@@ -0,0 +1,51 @@
+export const PACKAGE_NAME = '@rover-studio/answer-me';
+export const PACKAGE_VERSION = '0.1.0-rc.1';
+export const MANAGED_SKILLS = Object.freeze(['ask-when-needed', 'answerme']);
+export const INSTALL_LEDGER = '.answerme-toolkit-install.json';
+export const TRANSACTION_DIRECTORY = '.answerme-toolkit-transaction';
+export const JOURNAL_FILE = 'journal.json';
+export const MACHINE_SCHEMA_VERSION = 1;
+export const JOURNAL_SCHEMA_VERSION = 1;
+export const DEFAULT_TIMEOUT_MS = 8_000;
+export const MAX_BUFFER = 1024 * 1024;
+export const USAGE_VALIDATION_TIMEOUT_SECONDS = 300;
+export const OFFICIAL_API_ROOT = 'https://answerme.rover.studio';
+
+export const PUBLIC_CODES = Object.freeze(new Set([
+  'ok',
+  'no-change',
+  'removed',
+  'invalid-command',
+  'unsupported-platform',
+  'node-version-unsupported',
+  'codex-executable-not-found',
+  'codex-executable-untrusted',
+  'codex-version-unverified',
+  'codex-protocol-timeout',
+  'codex-protocol-invalid',
+  'codex-root-untrusted',
+  'codex-discovery-invalid',
+  'codex-discovery-conflict',
+  'package-integrity-invalid',
+  'unsafe-filesystem-entry',
+  'unknown-existing-files',
+  'untrusted-legacy-installation',
+  'not-installed',
+  'target-drift',
+  'transaction-pending',
+  'transaction-failed',
+  'rollback-completed',
+  'recovery-required',
+  'usage-validation-passed',
+  'usage-validation-issue',
+  'usage-validation-timeout',
+  'usage-validation-output-invalid',
+  'usage-validation-runner-unavailable',
+  'cleanup-warning',
+  'doctor-healthy',
+  'doctor-issue',
+]));
+
+export function publicCode(value, fallback = 'transaction-failed') {
+  return typeof value === 'string' && PUBLIC_CODES.has(value) ? value : fallback;
+}

package/lib/npm-cli/errors.mjs

@@ -0,0 +1,15 @@
+import { publicCode } from './constants.mjs';
+
+export class InstallerError extends Error {
+  constructor(code, options = {}) {
+    super(publicCode(code));
+    this.name = 'InstallerError';
+    this.code = publicCode(code);
+    this.mutated = options.mutated === true;
+    this.recoveryRequired = options.recoveryRequired === true;
+  }
+}
+
+export function errorCode(error, fallback = 'transaction-failed') {
+  return publicCode(error?.code ?? error?.message, fallback);
+}

package/lib/npm-cli/filesystem.mjs

@@ -0,0 +1,193 @@
+import { createHash } from 'node:crypto';
+import {
+  copyFile,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  realpath,
+  rename,
+  rm,
+} from 'node:fs/promises';
+import path from 'node:path';
+import { InstallerError } from './errors.mjs';
+
+export function normalizePath(value) {
+  let comparable = value;
+  if (process.platform === 'win32') {
+    comparable = comparable.replaceAll('/', '\\');
+    if (comparable.toLowerCase().startsWith('\\\\?\\unc\\')) comparable = `\\\\${comparable.slice(8)}`;
+    else if (/^\\\\\?\\[A-Za-z]:\\/.test(comparable)) comparable = comparable.slice(4);
+  }
+  const resolved = path.resolve(comparable).replaceAll('\\', '/').replace(/\/$/, '');
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+export function isAbsolutePath(value) {
+  return typeof value === 'string'
+    && value.length > 0
+    && value.length <= 32_768
+    && !value.includes('\0')
+    && path.isAbsolute(value);
+}
+
+export async function pathExists(value) {
+  try {
+    await lstat(value);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function samePlainFilesystemObject(candidate, canonical, inspect = lstat) {
+  if (!isAbsolutePath(canonical)) return false;
+  try {
+    // BigInt avoids rounding distinct Windows file IDs to the same Number.
+    const [original, resolved] = await Promise.all([
+      inspect(candidate, { bigint: true }),
+      inspect(canonical, { bigint: true }),
+    ]);
+    if (original.ino === 0n || resolved.ino === 0n
+      || original.dev !== resolved.dev || original.ino !== resolved.ino
+      || original.isSymbolicLink() || resolved.isSymbolicLink()
+      || original.isDirectory() !== resolved.isDirectory()
+      || original.isFile() !== resolved.isFile()) return false;
+    const inspected = new Set();
+    for (const spelling of [candidate, canonical]) {
+      for (let ancestor = path.dirname(spelling); ; ancestor = path.dirname(ancestor)) {
+        if (!inspected.has(ancestor)) {
+          const info = await inspect(ancestor);
+          if (!info.isDirectory() || info.isSymbolicLink()) return false;
+          inspected.add(ancestor);
+        }
+        if (path.dirname(ancestor) === ancestor) break;
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function assertPlainExisting(candidate, expected = null, dependencies = {}) {
+  const resolveCanonical = dependencies.realpath ?? realpath;
+  if (!isAbsolutePath(candidate)) throw new InstallerError('unsafe-filesystem-entry');
+  const info = await lstat(candidate).catch(() => null);
+  if (!info || info.isSymbolicLink()) throw new InstallerError('unsafe-filesystem-entry');
+  if (expected === 'file' && !info.isFile()) throw new InstallerError('unsafe-filesystem-entry');
+  if (expected === 'directory' && !info.isDirectory()) throw new InstallerError('unsafe-filesystem-entry');
+  const canonical = await resolveCanonical(candidate);
+  if (normalizePath(canonical) !== normalizePath(candidate)
+    && !(await samePlainFilesystemObject(candidate, canonical, dependencies.lstat ?? lstat))) {
+    throw new InstallerError('unsafe-filesystem-entry');
+  }
+  return info;
+}
+
+export async function assertPlainAncestor(candidate) {
+  if (!isAbsolutePath(candidate)) throw new InstallerError('unsafe-filesystem-entry');
+  let current = path.resolve(candidate);
+  while (!(await pathExists(current))) {
+    const parent = path.dirname(current);
+    if (parent === current) throw new InstallerError('unsafe-filesystem-entry');
+    current = parent;
+  }
+  await assertPlainExisting(current, 'directory');
+  return current;
+}
+
+export function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+async function walkPlain(root, current, entries) {
+  const children = await readdir(current, { withFileTypes: true });
+  children.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+  for (const child of children) {
+    const absolute = path.join(current, child.name);
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink()) throw new InstallerError('unsafe-filesystem-entry');
+    const relative = path.relative(root, absolute).replaceAll('\\', '/');
+    if (!relative || relative.startsWith('../') || path.isAbsolute(relative)) {
+      throw new InstallerError('unsafe-filesystem-entry');
+    }
+    if (info.isDirectory()) {
+      entries.push({ path: relative, type: 'directory' });
+      await walkPlain(root, absolute, entries);
+    } else if (info.isFile()) {
+      const bytes = await readFile(absolute);
+      entries.push({ path: relative, type: 'file', size: bytes.length, sha256: sha256(bytes) });
+    } else {
+      throw new InstallerError('unsafe-filesystem-entry');
+    }
+  }
+}
+
+export async function snapshotPath(candidate, kind = 'directory') {
+  if (!(await pathExists(candidate))) return { exists: false, kind, entries: [] };
+  await assertPlainExisting(candidate, kind);
+  if (kind === 'file') {
+    const bytes = await readFile(candidate);
+    return { exists: true, kind, entries: [{ path: '.', type: 'file', size: bytes.length, sha256: sha256(bytes) }] };
+  }
+  const entries = [];
+  await walkPlain(candidate, candidate, entries);
+  entries.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+  return { exists: true, kind, entries };
+}
+
+export function snapshotsEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export async function copyPlainTree(source, destination) {
+  await assertPlainExisting(source, 'directory');
+  if (await pathExists(destination)) throw new InstallerError('unsafe-filesystem-entry');
+  await mkdir(destination, { recursive: false });
+  const entries = await readdir(source, { withFileTypes: true });
+  entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+  for (const entry of entries) {
+    const from = path.join(source, entry.name);
+    const to = path.join(destination, entry.name);
+    const info = await lstat(from);
+    if (info.isSymbolicLink()) throw new InstallerError('unsafe-filesystem-entry');
+    if (info.isDirectory()) await copyPlainTree(from, to);
+    else if (info.isFile()) await copyFile(from, to);
+    else throw new InstallerError('unsafe-filesystem-entry');
+  }
+}
+
+export async function atomicWriteJson(destination, value) {
+  const parent = path.dirname(destination);
+  await assertPlainExisting(parent, 'directory');
+  const temporary = path.join(parent, `.${path.basename(destination)}.${process.pid}.tmp`);
+  if (await pathExists(temporary)) throw new InstallerError('unsafe-filesystem-entry');
+  const handle = await open(temporary, 'wx');
+  try {
+    await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await rename(temporary, destination);
+}
+
+export async function removeVerified(candidate, expectedSnapshot) {
+  const observed = await snapshotPath(candidate, expectedSnapshot.kind);
+  if (!snapshotsEqual(observed, expectedSnapshot)) throw new InstallerError('target-drift');
+  if (observed.exists) await rm(candidate, { recursive: expectedSnapshot.kind === 'directory', force: false });
+}
+
+export async function readJsonFile(candidate, maxBytes = 1024 * 1024) {
+  await assertPlainExisting(candidate, 'file');
+  const bytes = await readFile(candidate);
+  if (bytes.length === 0 || bytes.length > maxBytes) throw new InstallerError('unsafe-filesystem-entry');
+  try {
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+  } catch {
+    throw new InstallerError('unsafe-filesystem-entry');
+  }
+}

package/lib/npm-cli/host-discovery.mjs

@@ -0,0 +1,404 @@
+import { execFile as nodeExecFile, spawn as nodeSpawn } from 'node:child_process';
+import { lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import {
+  DEFAULT_TIMEOUT_MS,
+  MANAGED_SKILLS,
+  MAX_BUFFER,
+  PACKAGE_VERSION,
+} from './constants.mjs';
+import { InstallerError } from './errors.mjs';
+import {
+  assertPlainExisting,
+  isAbsolutePath,
+  normalizePath,
+  pathExists,
+} from './filesystem.mjs';
+
+const execFile = promisify(nodeExecFile);
+const INITIALIZE_ID = 'answerme-initialize-1';
+const SKILLS_LIST_ID = 'answerme-skills-list-2';
+const APP_SERVER_ARGS = Object.freeze(['app-server', '--listen', 'stdio://']);
+const VERSION_PATTERN = /^codex-cli (\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)[\r\n]*$/;
+const INITIALIZE_FIELDS = new Set(['codexHome', 'platformFamily', 'platformOs', 'userAgent']);
+const ENTRY_FIELDS = new Set(['cwd', 'errors', 'skills']);
+const SKILL_FIELDS = new Set([
+  'description', 'enabled', 'interface', 'name', 'path', 'pluginId', 'scope', 'shortDescription', 'dependencies',
+]);
+const SECURITY_FIELD = /(home|root|path|director|permission|sandbox|approval|credential|secret|token|skill)/i;
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function executionContext(value = {}) {
+  const timeoutMs = value.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxBuffer = value.maxBuffer ?? MAX_BUFFER;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 30_000) return null;
+  if (!Number.isSafeInteger(maxBuffer) || maxBuffer < 4096 || maxBuffer > MAX_BUFFER) return null;
+  return { timeoutMs, maxBuffer };
+}
+
+function unknownSecurityField(value, known) {
+  return Object.keys(value).some((key) => !known.has(key) && SECURITY_FIELD.test(key));
+}
+
+async function invokeExecFile(executor, executable, args, options) {
+  if (typeof executor !== 'function') return execFile(executable, args, options);
+  return executor(executable, args, options);
+}
+
+function stdoutOf(result) {
+  if (typeof result === 'string') return result;
+  if (Buffer.isBuffer(result)) return result.toString('utf8');
+  if (isRecord(result)) {
+    return Buffer.isBuffer(result.stdout) ? result.stdout.toString('utf8') : result.stdout;
+  }
+  return '';
+}
+
+export async function validateCodexExecutable(candidate, dependencies = {}) {
+  if (!isAbsolutePath(candidate) || path.basename(candidate).toLowerCase() !== 'codex.exe') {
+    throw new InstallerError('codex-executable-untrusted');
+  }
+  if (typeof dependencies.inspectExecutable === 'function') {
+    if (await dependencies.inspectExecutable(candidate) !== true) throw new InstallerError('codex-executable-untrusted');
+    return path.resolve(candidate);
+  }
+  const info = await lstat(candidate).catch(() => null);
+  if (!info?.isFile() || info.isSymbolicLink()) throw new InstallerError('codex-executable-untrusted');
+  const canonical = await realpath(candidate);
+  if (normalizePath(canonical) !== normalizePath(candidate)) throw new InstallerError('codex-executable-untrusted');
+  return canonical;
+}
+
+export async function findCodexExecutable({ env = process.env } = {}, dependencies = {}) {
+  const injected = dependencies.codexExecutable ?? env.ANSWERME_CODEX_EXECUTABLE;
+  if (injected) return validateCodexExecutable(injected, dependencies);
+  const pathEntries = [];
+  for (const rawEntry of String(env.PATH ?? '').split(path.delimiter)) {
+    const entry = rawEntry.trim().replace(/^"|"$/g, '');
+    if (entry && isAbsolutePath(entry)) pathEntries.push(entry);
+  }
+  async function validatedCandidates(candidates) {
+    const valid = [];
+    for (const candidate of [...new Set(candidates.map((value) => path.resolve(value)))]) {
+      if (!(await pathExists(candidate))) continue;
+      try {
+        valid.push(await validateCodexExecutable(candidate, dependencies));
+      } catch {
+        throw new InstallerError('codex-executable-untrusted');
+      }
+    }
+    return [...new Map(valid.map((value) => [normalizePath(value), value])).values()];
+  }
+
+  const direct = await validatedCandidates(pathEntries.map((entry) => path.join(entry, 'codex.exe')));
+  if (direct.length === 1) return direct[0];
+  if (direct.length > 1) throw new InstallerError('codex-executable-untrusted');
+
+  const target = path.join('vendor', 'x86_64-pc-windows-msvc', 'codex', 'codex.exe');
+  const npmCandidates = [];
+  for (const entry of pathEntries) {
+    const hasShim = await pathExists(path.join(entry, 'codex.cmd')) || await pathExists(path.join(entry, 'codex'));
+    if (!hasShim) continue;
+    npmCandidates.push(
+      path.join(entry, 'node_modules', '@openai', 'codex', 'node_modules', '@openai', 'codex-win32-x64', target),
+      path.join(entry, 'node_modules', '@openai', 'codex-win32-x64', target),
+      path.join(entry, 'node_modules', '@openai', 'codex', target),
+    );
+  }
+  const npmNative = await validatedCandidates(npmCandidates);
+  if (npmNative.length === 1) return npmNative[0];
+  if (npmNative.length > 1) {
+    const versions = new Map();
+    for (const candidate of npmNative) {
+      try {
+        const version = await probeCodexVersion(candidate, {}, dependencies);
+        if (version === 'unknown') throw new InstallerError('codex-executable-untrusted');
+        if (!versions.has(version)) versions.set(version, candidate);
+      } catch {
+        throw new InstallerError('codex-executable-untrusted');
+      }
+    }
+    if (versions.size === 1) return versions.values().next().value;
+    throw new InstallerError('codex-executable-untrusted');
+  }
+  throw new InstallerError('codex-executable-not-found');
+}
+
+export async function probeCodexVersion(executable, context = {}, dependencies = {}) {
+  const bounded = executionContext(context);
+  if (!bounded) return 'unknown';
+  try {
+    const result = await invokeExecFile(dependencies.execFile, executable, ['--version'], {
+      shell: false,
+      windowsHide: true,
+      encoding: 'utf8',
+      timeout: bounded.timeoutMs,
+      maxBuffer: bounded.maxBuffer,
+    });
+    const match = stdoutOf(result)?.match(VERSION_PATTERN);
+    return match?.[1] ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function createLineReader(stream, child, context, stderrState) {
+  let pending = Buffer.alloc(0);
+  let total = 0;
+  let terminalError = null;
+  const queue = [];
+  const waiters = [];
+
+  function fail(code) {
+    if (terminalError) return;
+    terminalError = new InstallerError(code);
+    while (waiters.length > 0) waiters.shift().reject(terminalError);
+    try { child.kill(); } catch { /* best effort */ }
+  }
+
+  function deliver() {
+    while (queue.length > 0 && waiters.length > 0) waiters.shift().resolve(queue.shift());
+  }
+
+  stream.on('data', (chunk) => {
+    const bytes = Buffer.from(chunk);
+    total += bytes.length;
+    if (total > context.maxBuffer) return fail('codex-protocol-invalid');
+    pending = Buffer.concat([pending, bytes]);
+    let newline;
+    while ((newline = pending.indexOf(0x0a)) >= 0) {
+      let line = pending.subarray(0, newline);
+      pending = pending.subarray(newline + 1);
+      if (line.at(-1) === 0x0d) line = line.subarray(0, -1);
+      if (line.length === 0 || line.length > context.maxBuffer) return fail('codex-protocol-invalid');
+      try {
+        queue.push(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(line)));
+      } catch {
+        return fail('codex-protocol-invalid');
+      }
+    }
+    deliver();
+  });
+  stream.on('error', () => fail('codex-protocol-invalid'));
+  child.once('error', () => fail('codex-protocol-invalid'));
+  child.once('exit', () => fail('codex-protocol-invalid'));
+
+  return async function readLine(timeoutMs = context.timeoutMs) {
+    if (stderrState.overflow) throw new InstallerError('codex-protocol-invalid');
+    if (queue.length > 0) return queue.shift();
+    if (terminalError) throw terminalError;
+    return new Promise((resolve, reject) => {
+      const waiter = { resolve, reject };
+      waiters.push(waiter);
+      const timer = setTimeout(() => {
+        const index = waiters.indexOf(waiter);
+        if (index >= 0) waiters.splice(index, 1);
+        reject(new InstallerError('codex-protocol-timeout'));
+        try { child.kill(); } catch { /* best effort */ }
+      }, timeoutMs);
+      timer.unref?.();
+      waiter.resolve = (value) => { clearTimeout(timer); resolve(value); };
+      waiter.reject = (error) => { clearTimeout(timer); reject(error); };
+    });
+  };
+}
+
+function allowedNotification(message) {
+  if (!isRecord(message) || typeof message.method !== 'string' || !isRecord(message.params)) return false;
+  if (message.method === 'remoteControl/status/changed') {
+    return typeof message.params.status === 'string';
+  }
+  if (message.method === 'configWarning') return typeof message.params.summary === 'string';
+  return false;
+}
+
+async function readResponse(readLine, expectedId, timeoutMs, seen) {
+  const deadline = Date.now() + timeoutMs;
+  for (let index = 0; index < 8; index += 1) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new InstallerError('codex-protocol-timeout');
+    const message = await readLine(remaining);
+    if (Object.hasOwn(isRecord(message) ? message : {}, 'id')) {
+      if (message.id !== expectedId || seen.has(message.id) || Object.hasOwn(message, 'error') || !isRecord(message.result)) {
+        throw new InstallerError('codex-protocol-invalid');
+      }
+      seen.add(message.id);
+      return message.result;
+    }
+    if (!allowedNotification(message)) throw new InstallerError('codex-protocol-invalid');
+  }
+  throw new InstallerError('codex-protocol-invalid');
+}
+
+async function writeMessage(child, message) {
+  const line = `${JSON.stringify(message)}\n`;
+  if (!child.stdin.write(line, 'utf8')) await new Promise((resolve) => child.stdin.once('drain', resolve));
+}
+
+function validateInitialize(result) {
+  if (!isRecord(result)
+    || unknownSecurityField(result, INITIALIZE_FIELDS)
+    || !isAbsolutePath(result.codexHome)
+    || typeof result.platformFamily !== 'string'
+    || typeof result.platformOs !== 'string'
+    || typeof result.userAgent !== 'string'
+    || result.userAgent.length === 0
+    || result.userAgent.length > 2048) {
+    throw new InstallerError('codex-protocol-invalid');
+  }
+  return result.codexHome;
+}
+
+function validateError(value) {
+  return isRecord(value) && typeof value.message === 'string' && typeof value.path === 'string';
+}
+
+function validateSkill(value) {
+  if (!isRecord(value)
+    || unknownSecurityField(value, SKILL_FIELDS)
+    || typeof value.description !== 'string'
+    || typeof value.enabled !== 'boolean'
+    || typeof value.name !== 'string'
+    || value.name.length === 0
+    || !isAbsolutePath(value.path)
+    || path.basename(value.path).toLowerCase() !== 'skill.md'
+    || typeof value.scope !== 'string'
+    || value.scope.length === 0) {
+    throw new InstallerError('codex-discovery-invalid');
+  }
+  return {
+    name: value.name,
+    path: path.resolve(value.path),
+    enabled: value.enabled,
+    scope: value.scope,
+  };
+}
+
+function validateSkillsList(result, cwd) {
+  if (!isRecord(result) || !Array.isArray(result.data) || result.data.length !== 1) {
+    throw new InstallerError('codex-discovery-invalid');
+  }
+  const entry = result.data[0];
+  if (!isRecord(entry)
+    || unknownSecurityField(entry, ENTRY_FIELDS)
+    || typeof entry.cwd !== 'string'
+    || normalizePath(entry.cwd) !== normalizePath(cwd)
+    || !Array.isArray(entry.errors)
+    || !entry.errors.every(validateError)
+    || entry.errors.length > 0
+    || !Array.isArray(entry.skills)) {
+    throw new InstallerError('codex-discovery-invalid');
+  }
+  return entry.skills.map(validateSkill);
+}
+
+export async function invokeCodexAppServer({ executable, hostVersion, cwd, context = {} }, dependencies = {}) {
+  const bounded = executionContext(context);
+  if (!bounded || !isAbsolutePath(cwd)) throw new InstallerError('codex-protocol-invalid');
+  const spawn = dependencies.spawn ?? nodeSpawn;
+  let child;
+  try {
+    child = spawn(executable, [...APP_SERVER_ARGS], {
+      cwd,
+      shell: false,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (!child?.stdin || !child?.stdout || !child?.stderr) throw new InstallerError('codex-protocol-invalid');
+    const stderrState = { bytes: 0, overflow: false };
+    child.stderr.on('data', (chunk) => {
+      stderrState.bytes += Buffer.byteLength(chunk);
+      if (stderrState.bytes > bounded.maxBuffer) {
+        stderrState.overflow = true;
+        try { child.kill(); } catch { /* best effort */ }
+      }
+    });
+    const readLine = createLineReader(child.stdout, child, bounded, stderrState);
+    const seen = new Set();
+    await writeMessage(child, {
+      id: INITIALIZE_ID,
+      method: 'initialize',
+      params: {
+        clientInfo: { name: 'answerme-toolkit', version: PACKAGE_VERSION },
+        capabilities: {
+          experimentalApi: true,
+          optOutNotificationMethods: ['configWarning', 'remoteControl/status/changed'],
+        },
+      },
+    });
+    const codexHome = validateInitialize(
+      await readResponse(readLine, INITIALIZE_ID, bounded.timeoutMs, seen),
+      hostVersion,
+    );
+    await writeMessage(child, { method: 'initialized' });
+    await writeMessage(child, {
+      id: SKILLS_LIST_ID,
+      method: 'skills/list',
+      params: { cwds: [cwd], forceReload: true },
+    });
+    const skills = validateSkillsList(
+      await readResponse(readLine, SKILLS_LIST_ID, bounded.timeoutMs, seen),
+      cwd,
+    );
+    if (stderrState.overflow) throw new InstallerError('codex-protocol-invalid');
+    return { codexHome: path.resolve(codexHome), skills };
+  } catch (error) {
+    if (error instanceof InstallerError) throw error;
+    throw new InstallerError('codex-protocol-invalid');
+  } finally {
+    try { child?.stdin?.end(); } catch { /* best effort */ }
+    try { if (child && child.exitCode === null) child.kill(); } catch { /* best effort */ }
+  }
+}
+
+export async function discoverCodexHost({ cwd, env = process.env, context = {} } = {}, dependencies = {}) {
+  if (!isAbsolutePath(cwd)) throw new InstallerError('codex-protocol-invalid');
+  const executable = await findCodexExecutable({ env }, dependencies);
+  const hostVersion = await probeCodexVersion(executable, context, dependencies);
+  const observed = await invokeCodexAppServer({ executable, hostVersion, cwd, context }, dependencies);
+  await assertPlainExisting(observed.codexHome, 'directory');
+  const skillsRoot = path.join(observed.codexHome, 'skills');
+  if (await pathExists(skillsRoot)) await assertPlainExisting(skillsRoot, 'directory');
+  return {
+    executable,
+    hostVersion,
+    codexHome: observed.codexHome,
+    skillsRoot,
+    skills: observed.skills,
+  };
+}
+
+export function evaluateManagedSkillDiscovery(observation, { requireInstalled = false, requireAbsent = false }) {
+  const grouped = new Map(MANAGED_SKILLS.map((name) => [name, []]));
+  for (const skill of observation.skills) {
+    if (grouped.has(skill.name)) grouped.get(skill.name).push(skill);
+  }
+  if ([...grouped.values()].some((items) => items.length > 1)) {
+    throw new InstallerError('codex-discovery-conflict');
+  }
+  for (const [name, items] of grouped) {
+    if (items.length === 0) {
+      if (requireInstalled) throw new InstallerError('codex-discovery-invalid');
+      continue;
+    }
+    if (requireAbsent) throw new InstallerError('codex-discovery-invalid');
+    const expected = path.join(observation.skillsRoot, name, 'SKILL.md');
+    if (normalizePath(items[0].path) !== normalizePath(expected)) {
+      throw new InstallerError('codex-discovery-conflict');
+    }
+    if (requireInstalled && items[0].enabled !== true) throw new InstallerError('codex-discovery-invalid');
+  }
+  return true;
+}
+
+export const __test = Object.freeze({
+  executionContext,
+  unknownSecurityField,
+  validateInitialize,
+  validateSkillsList,
+  readResponse,
+});