session-orchestrator 3.16.0

package/scripts/ci/assert-vitest-green.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// scripts/ci/assert-vitest-green.mjs
+//
+// Fail-closed verifier for a vitest JSON result file. Replaces the brittle
+// grep-the-stdout heuristic the GitLab `test`/`coverage` jobs used to rely on.
+//
+// WHY THIS EXISTS (the silent-regression incident class):
+//   The old CI test job ran `timeout --preserve-status 240s npm test … || true`
+//   and then counted `✓`/`FAIL` markers in the captured stdout. Two ways that
+//   reported a RED suite as GREEN:
+//     1. The suite took longer than the 240s cap under runner contention
+//        (observed: 257s on the Mac shell-executor). `timeout` killed vitest
+//        BEFORE it printed the bottom failure-summary block; `|| true` swallowed
+//        the kill; the grep found zero `FAIL  tests/…` lines → false GREEN.
+//     2. The verbose reporter marks failing tests with `×` (U+00D7), which the
+//        `✗` (U+2717) regex never matched.
+//   Net effect: a 12-failure suite shipped green (commit c6e34e1 / pipeline
+//   #5828). This is the same class as the documented 8-pipeline silent
+//   regression (CLAUDE.md / AGENTS.md Critical Gotchas).
+//
+// THE FIX:
+//   vitest's `--reporter=json --outputFile=<path>` writes a machine-readable
+//   result on completion. This script is the single authority on pass/fail.
+//   It is FAIL-CLOSED: any ambiguity (file missing, unparseable, truncated run,
+//   success!==true) exits non-zero. The only GREEN path is an explicit, complete,
+//   all-passing result.
+//
+//   Robustness to the legacy vitest-2.1.9 tinypool exit-hang (#268): the JSON
+//   file is written at onFinished — AFTER all tests pass but BEFORE the hang —
+//   so a post-completion hang (whose non-zero exit the CI step swallows with
+//   `|| true`) still yields success:true here. A run killed mid-flight never
+//   writes a complete file, so it fails closed. Both behaviours are correct.
+//
+// USAGE:
+//   node scripts/ci/assert-vitest-green.mjs <result.json> [--min-tests=N] [--log=<path>]
+//   Exit 0 → suite is verifiably green. Exit 1 → fail (with a [ci] reason line).
+//
+// The caller MUST `rm -f` the result file before the vitest run so a stale
+// file from a prior run on a reused shell-executor host cannot be mistaken for
+// the current run's result.
+//
+// SELF-DIAGNOSING HANGS (--log):
+//   When the result JSON is missing/unreadable — the runner-contention hang case
+//   where vitest is killed before writing onFinished — an optional `--log=<path>`
+//   pointing at the captured `--reporter=default` stdout lets the verifier name
+//   the test files that were IN-FLIGHT at the kill (started with `❯ <file>` but
+//   never reached a `✓`/`×` completion marker). This turns a bare ENOENT into an
+//   actionable "these N files were running when the run died" hint. Purely
+//   additive: absent `--log` (or an unreadable/uninformative log) falls back to
+//   the existing bare message and the exit-code contract is unchanged.
+
+import { readFileSync } from 'node:fs';
+
+const DEFAULT_MIN_TESTS = 5000;
+
+/**
+ * Verify a parsed vitest JSON result is a complete, all-passing run.
+ * Pure function — returns { ok, reason, summary } and never throws or exits.
+ * @param {unknown} result - parsed JSON (any shape; validated here)
+ * @param {{ minTests?: number }} [opts]
+ * @returns {{ ok: boolean, reason: string, summary: object }}
+ */
+export function verifyVitestResult(result, opts = {}) {
+  const minTests = Number.isFinite(opts.minTests) ? opts.minTests : DEFAULT_MIN_TESTS;
+
+  if (result === null || typeof result !== 'object') {
+    return { ok: false, reason: 'result is not an object', summary: {} };
+  }
+
+  const numFailedTests = result.numFailedTests ?? null;
+  const numFailedTestSuites = result.numFailedTestSuites ?? null;
+  const numPassedTests = result.numPassedTests ?? null;
+  const numTotalTests = result.numTotalTests ?? null;
+  const success = result.success;
+
+  const summary = { success, numPassedTests, numFailedTests, numFailedTestSuites, numTotalTests };
+
+  // Shape guard: the required numeric fields must all be present. A partial /
+  // truncated JSON (e.g. a half-written file) lacks them → fail closed.
+  for (const [k, v] of Object.entries({ numFailedTests, numFailedTestSuites, numPassedTests, numTotalTests })) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+      return { ok: false, reason: `missing/invalid field "${k}" (truncated or wrong-shape JSON)`, summary };
+    }
+  }
+
+  // Failed-count guards run BEFORE the generic success flag so a real failure
+  // reports the actionable count ("12 failed test(s)") rather than the opaque
+  // "success is false". success!==true with zero counts is a separate edge.
+  if (numFailedTests > 0) {
+    return { ok: false, reason: `${numFailedTests} failed test(s)`, summary };
+  }
+  if (numFailedTestSuites > 0) {
+    return { ok: false, reason: `${numFailedTestSuites} failed test suite(s)`, summary };
+  }
+  if (success !== true) {
+    return { ok: false, reason: `success is ${JSON.stringify(success)} (expected true)`, summary };
+  }
+  // Floor guard: a suspiciously small run signals a truncated/partial/empty
+  // execution masquerading as green. The real suite is ~12.1k tests (2026-07-17).
+  if (numTotalTests < minTests) {
+    return {
+      ok: false,
+      reason: `only ${numTotalTests} total tests (< floor ${minTests}) — truncated or partial run`,
+      summary,
+    };
+  }
+
+  return { ok: true, reason: 'all tests passed', summary };
+}
+
+/**
+ * Read + verify a vitest JSON result file. Fail-closed on any read/parse error.
+ * @param {string} path
+ * @param {{ minTests?: number }} [opts]
+ * @returns {{ ok: boolean, reason: string, summary: object }}
+ */
+export function assertVitestGreenFile(path, opts = {}) {
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    return { ok: false, reason: `cannot read result file "${path}": ${err.message}`, summary: {} };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { ok: false, reason: `result file "${path}" is not valid JSON: ${err.message}`, summary: {} };
+  }
+  return verifyVitestResult(parsed, opts);
+}
+
+/**
+ * Parse a captured vitest `--reporter=default` log and return the test files
+ * that bear a `❯ <file>` lead glyph but never reached a per-file completion
+ * marker (`✓ <file>` / `× <file>`). The intent is to surface the "in-flight at
+ * kill" set — the files that were still running when the runner timed vitest
+ * out — so a hang dump names the likely culprit.
+ *
+ * BEST-EFFORT — DOES NOT reliably mark in-progress files in CI. This is a known
+ * limitation, not a bug:
+ *   - The `❯ U+276F` glyph denotes "in-progress/queued" only on an INTERACTIVE
+ *     TTY, where vitest live-updates the running-file list in place.
+ *   - In non-TTY CI (`--reporter=default --no-color`, no live rewrite), `❯`
+ *     instead marks FAILED files in the FINAL summary block — NOT in-progress.
+ *     There is no per-file "started" line emitted mid-flight to key off.
+ *   - Consequence: on a TRUE mid-flight hang (vitest killed before it writes the
+ *     summary), there is often no `❯` line at all, so this hint returns [] —
+ *     empty exactly when it would be most useful, and potentially misleading
+ *     (matching a failed-summary file) when the run did reach the summary.
+ *
+ * A robust in-flight signal would need `--reporter=verbose` per-file START
+ * lines (which DO emit mid-flight). Wiring that in is deferred to a follow-up:
+ * it needs a captured real CI log to pin the exact start-line token format
+ * before changing the regex. THIS FUNCTION'S PARSE LOGIC IS UNCHANGED — the
+ * correction here is documentation-only.
+ *
+ * Pure function — never throws. Returns [] when the text is empty or no
+ * matching files are detectable.
+ *
+ * Marker glyphs (vitest default reporter, --no-color):
+ *   ✓ U+2713  per-file PASS completion
+ *   × U+00D7  per-file FAIL completion
+ *   ❯ U+276F  in-progress/queued on a TTY; FAILED-in-summary in non-TTY CI
+ *             (see the BEST-EFFORT caveat above — the non-TTY meaning is why
+ *              this hint can be empty/misleading on a real hang)
+ *
+ * @param {string} logText - raw captured reporter stdout
+ * @returns {string[]} sorted list of candidate test file paths (deduped)
+ */
+export function inFlightFilesFromLog(logText) {
+  if (typeof logText !== 'string' || logText.length === 0) return [];
+
+  const started = new Set();
+  const completed = new Set();
+
+  // Lead glyph, optional indentation, then the file path up to a trailing
+  // " (N tests…" annotation or end-of-line. The default reporter emits the
+  // file path as the first token after the status glyph.
+  const STARTED = /[❯>]\s+(\S+\.(?:test|spec)\.[cm]?[jt]sx?)\b/;
+  const COMPLETED = /[✓×✗]\s+(\S+\.(?:test|spec)\.[cm]?[jt]sx?)\b/;
+
+  // Defense-in-depth (security-review Q2 NICE): the captured path is later
+  // printed to stderr in a CI log pane. `\S+` admits control/ESC bytes, so
+  // strip C0 + DEL before they reach the terminal — a malicious vitest log
+  // line cannot smuggle terminal-escape sequences through the hint.
+  // eslint-disable-next-line no-control-regex -- intentional: neutralizing C0 + DEL is the whole point
+  const stripCtrl = (s) => s.replace(/[\u0000-\u001f\u007f]/g, '?');
+
+  for (const line of logText.split('\n')) {
+    const c = COMPLETED.exec(line);
+    if (c) {
+      completed.add(stripCtrl(c[1]));
+      continue;
+    }
+    const s = STARTED.exec(line);
+    if (s) started.add(stripCtrl(s[1]));
+  }
+
+  const inFlight = [...started].filter((f) => !completed.has(f));
+  return inFlight.sort();
+}
+
+/**
+ * Read a log file and extract the in-flight set. Fail-soft: a missing or
+ * unreadable log yields [] (the caller falls back to the bare message).
+ * @param {string} path
+ * @returns {string[]}
+ */
+export function inFlightFilesFromLogFile(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    return [];
+  }
+  return inFlightFilesFromLog(raw);
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  let minTests = DEFAULT_MIN_TESTS;
+  let logPath = null;
+  for (const arg of argv) {
+    const m = /^--min-tests=(\d+)$/.exec(arg);
+    const l = /^--log=(.+)$/.exec(arg);
+    if (m) minTests = Number(m[1]);
+    else if (l) logPath = l[1];
+    else positional.push(arg);
+  }
+  return { path: positional[0], minTests, logPath };
+}
+
+// CLI entry — only when run directly, not when imported by tests.
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const { path, minTests, logPath } = parseArgs(process.argv.slice(2));
+  if (!path) {
+    console.error('[ci] assert-vitest-green: missing <result.json> argument — failing closed');
+    process.exit(1);
+  }
+  const { ok, reason, summary } = assertVitestGreenFile(path, { minTests });
+  const s = summary || {};
+  console.log(
+    `[ci] vitest result: success=${s.success} passed=${s.numPassedTests} failed=${s.numFailedTests} ` +
+      `failedSuites=${s.numFailedTestSuites} total=${s.numTotalTests} (floor=${minTests})`,
+  );
+  if (ok) {
+    console.log(`[ci] ✓ suite verifiably green — ${reason}`);
+    process.exit(0);
+  }
+  console.error(`[ci] ✗ FAIL-CLOSED: ${reason}`);
+  // Self-diagnosing hint: the result JSON could not be READ (the hang case
+  // where vitest was killed before writing it). When a --log is supplied,
+  // surface the test files that were in-flight at the kill. This is purely an
+  // enriched stderr message — the exit-1 contract is unchanged.
+  if (logPath && reason.startsWith('cannot read result file')) {
+    const inFlight = inFlightFilesFromLogFile(logPath);
+    if (inFlight.length > 0) {
+      console.error(
+        `[ci] hint: ${inFlight.length} test file(s) in-flight when killed ` +
+          `(likely hang/slowdown): ${inFlight.join(', ')}`,
+      );
+    }
+  }
+  process.exit(1);
+}

package/scripts/codex-install.mjs

@@ -0,0 +1,435 @@
+#!/usr/bin/env node
+/**
+ * Install Session Orchestrator through Codex's public plugin lifecycle.
+ *
+ * Exit codes:
+ *   0 — installed, enabled, and verified
+ *   1 — argument or user-correctable environment error
+ *   2 — system, upstream command/JSON, or runtime postcondition failure
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { validateCodexPluginContract } from './lib/codex/plugin-contract.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = path.dirname(__filename);
+const SO_ROOT = path.dirname(SCRIPT_DIR);
+
+const MIN_CODEX_VERSION = [0, 144, 4];
+const MARKETPLACE_NAME = 'kanevry';
+const PLUGIN_NAME = 'session-orchestrator';
+const PLUGIN_ID = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+const LEGACY_PLUGIN_IDS = [
+  `${PLUGIN_NAME}@openai-curated`,
+  `${PLUGIN_NAME}@local`,
+];
+const CODEX_COMMAND_TIMEOUT_MS = 30_000;
+const ERROR_CATEGORIES = Object.freeze({
+  USER: 'user',
+  SYSTEM: 'system',
+});
+
+class InstallerError extends Error {
+  constructor(message, category = ERROR_CATEGORIES.SYSTEM) {
+    super(message);
+    this.name = 'InstallerError';
+    this.category = category;
+  }
+}
+
+function parseArguments(argv) {
+  let json = false;
+  let help = false;
+  let version = false;
+
+  for (const argument of argv) {
+    if (argument === '--json') json = true;
+    else if (argument === '--help' || argument === '-h') help = true;
+    else if (argument === '--version') version = true;
+    else {
+      throw new InstallerError(
+        `Unknown argument '${argument}'. Run with --help for usage.`,
+        ERROR_CATEGORIES.USER,
+      );
+    }
+  }
+
+  return { json, help, version };
+}
+
+function printHelp() {
+  process.stdout.write(`Usage: node scripts/codex-install.mjs [options]
+
+Install Session Orchestrator through the public Codex plugin lifecycle.
+
+Options:
+  --json     Print the verified final state as JSON
+  --version  Print the package/plugin base version
+  -h, --help Show this help
+
+Examples:
+  node scripts/codex-install.mjs
+  node scripts/codex-install.mjs --json
+  node scripts/codex-install.mjs --version
+`);
+}
+
+function progress(jsonMode, message) {
+  if (!jsonMode) process.stdout.write(`${message}\n`);
+}
+
+function formatCommand(args) {
+  return ['codex', ...args].map((part) => (
+    /\s/.test(part) ? JSON.stringify(part) : part
+  )).join(' ');
+}
+
+function runCodex(args) {
+  const command = formatCommand(args);
+  const result = spawnSync('codex', args, {
+    encoding: 'utf8',
+    timeout: CODEX_COMMAND_TIMEOUT_MS,
+  });
+
+  if (result.error) {
+    throw new InstallerError(`Cannot run '${command}': ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const diagnostic = (result.stderr || result.stdout || '').trim() || 'no diagnostic output';
+    throw new InstallerError(`Command failed with exit ${String(result.status)}: ${command}\n${diagnostic}`);
+  }
+
+  return result.stdout;
+}
+
+function runCodexJson(args, label) {
+  const stdout = runCodex(args);
+  try {
+    const parsed = JSON.parse(stdout);
+    if (!isRecord(parsed)) {
+      throw new Error('top-level value must be an object');
+    }
+    return parsed;
+  } catch (error) {
+    throw new InstallerError(
+      `${label} returned malformed JSON from '${formatCommand(args)}': ${error.message}`,
+    );
+  }
+}
+
+function parseCodexVersion(output) {
+  const match = output.match(/\b(\d+)\.(\d+)\.(\d+)(?:[-+][^\s]+)?\b/);
+  if (!match) {
+    throw new InstallerError(`Cannot parse Codex version from: ${output.trim() || '<empty output>'}`);
+  }
+  return match.slice(1, 4).map(Number);
+}
+
+function compareVersions(left, right) {
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const delta = (left[index] ?? 0) - (right[index] ?? 0);
+    if (delta !== 0) return Math.sign(delta);
+  }
+  return 0;
+}
+
+function formatVersion(version) {
+  return version.join('.');
+}
+
+function parseFeatures(output) {
+  const features = new Map();
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.match(/^(\S+)\s+(.+?)\s+(true|false)\s*$/);
+    if (!match) continue;
+    features.set(match[1], { state: match[2].trim(), enabled: match[3] === 'true' });
+  }
+  return features;
+}
+
+function requireStableFeature(features, name) {
+  const feature = features.get(name);
+  if (feature?.state !== 'stable' || feature.enabled !== true) {
+    const actual = feature ? `${feature.state} ${String(feature.enabled)}` : 'missing';
+    throw new InstallerError(
+      `Codex feature '${name}' must report 'stable true'; got '${actual}'. `
+      + `Upgrade Codex and verify with 'codex features list'.`,
+      ERROR_CATEGORIES.USER,
+    );
+  }
+}
+
+function readLocalJson(relativePath, label) {
+  try {
+    return JSON.parse(readFileSync(path.join(SO_ROOT, relativePath), 'utf8'));
+  } catch (error) {
+    throw new InstallerError(`Cannot read valid ${label}: ${error.message}`);
+  }
+}
+
+function readBaseVersion() {
+  const packageJson = readLocalJson('package.json', 'package.json');
+  if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
+    throw new InstallerError('package.json must contain a non-empty version string.');
+  }
+  return packageJson.version;
+}
+
+function validateLocalContract() {
+  const expectedBaseVersion = readBaseVersion();
+  const manifest = readLocalJson(path.join('.codex-plugin', 'plugin.json'), 'Codex plugin manifest');
+  const verdict = validateCodexPluginContract({
+    pluginRoot: SO_ROOT,
+    expectedBaseVersion,
+  });
+
+  if (!verdict.ok) {
+    const details = verdict.errors
+      .map((error) => `[${error.rule}] ${error.path}: ${error.message}`)
+      .join('\n');
+    throw new InstallerError(`Local Codex plugin contract failed:\n${details}`);
+  }
+  if (manifest.name !== PLUGIN_NAME || typeof manifest.version !== 'string') {
+    throw new InstallerError('Codex plugin manifest must contain the expected name and version.');
+  }
+
+  return manifest.version;
+}
+
+function requireArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new InstallerError(`${label} must be an array in Codex JSON output.`);
+  }
+  return value;
+}
+
+function sameLocalPath(left, right) {
+  return typeof left === 'string' && path.resolve(left) === path.resolve(right);
+}
+
+function assertMarketplaceCompatible(payload) {
+  const marketplaces = requireArray(payload.marketplaces, 'marketplaces');
+  const matches = marketplaces.filter((entry) => isRecord(entry) && entry.name === MARKETPLACE_NAME);
+
+  if (matches.length > 1) {
+    throw new InstallerError(
+      `Codex reports multiple '${MARKETPLACE_NAME}' marketplaces. `
+      + `Inspect them with 'codex plugin marketplace list --json'; this installer will not remove any marketplace.`,
+      ERROR_CATEGORIES.USER,
+    );
+  }
+  if (matches.length === 0) return;
+
+  const existing = matches[0];
+  const sourceType = existing.marketplaceSource?.sourceType;
+  const source = existing.marketplaceSource?.source ?? existing.root;
+  if (sourceType !== 'local' || !sameLocalPath(source, SO_ROOT)) {
+    throw new InstallerError(
+      `Marketplace '${MARKETPLACE_NAME}' already points to '${String(source)}' (${String(sourceType)}), `
+      + `not '${SO_ROOT}'. Resolve the conflict manually after reviewing `
+      + `'codex plugin marketplace list --json'; this installer will not remove or replace it.`,
+      ERROR_CATEGORIES.USER,
+    );
+  }
+}
+
+function assertMarketplaceAddResult(payload) {
+  if (payload.marketplaceName !== MARKETPLACE_NAME) {
+    throw new InstallerError(
+      `Marketplace add returned '${String(payload.marketplaceName)}', expected '${MARKETPLACE_NAME}'.`,
+    );
+  }
+  if (!sameLocalPath(payload.installedRoot, SO_ROOT)) {
+    throw new InstallerError(
+      `Marketplace add returned root '${String(payload.installedRoot)}', expected '${SO_ROOT}'.`,
+    );
+  }
+  if (typeof payload.alreadyAdded !== 'boolean') {
+    throw new InstallerError("Marketplace add JSON is missing boolean field 'alreadyAdded'.");
+  }
+}
+
+function assertPluginAddResult(payload, expectedVersion) {
+  if (payload.pluginId !== PLUGIN_ID) {
+    throw new InstallerError(`Plugin add returned '${String(payload.pluginId)}', expected '${PLUGIN_ID}'.`);
+  }
+  if (payload.version !== expectedVersion) {
+    throw new InstallerError(
+      `Plugin add returned version '${String(payload.version)}', expected '${expectedVersion}'.`,
+    );
+  }
+}
+
+function pluginEntries(payload) {
+  const installed = requireArray(payload.installed, 'installed plugins');
+  const available = requireArray(payload.available, 'available plugins');
+  return { installed, available, all: [...installed, ...available] };
+}
+
+function assertTargetHealthy(payload, expectedVersion, phase) {
+  const entries = pluginEntries(payload);
+  const matches = entries.all.filter((entry) => isRecord(entry) && entry.pluginId === PLUGIN_ID);
+
+  if (matches.length !== 1) {
+    throw new InstallerError(
+      `${phase}: expected exactly one '${PLUGIN_ID}' entry, found ${matches.length}.`,
+    );
+  }
+
+  const target = matches[0];
+  if (target.installed !== true || target.enabled !== true) {
+    throw new InstallerError(
+      `${phase}: '${PLUGIN_ID}' must be installed and enabled; got installed=${String(target.installed)}, `
+      + `enabled=${String(target.enabled)}.`,
+    );
+  }
+  if (target.version !== expectedVersion) {
+    throw new InstallerError(
+      `${phase}: '${PLUGIN_ID}' version '${String(target.version)}' does not match manifest `
+      + `'${expectedVersion}'.`,
+    );
+  }
+
+  return entries;
+}
+
+function installedLegacyPluginIds(entries) {
+  return LEGACY_PLUGIN_IDS.filter((pluginId) => entries.installed.some((entry) => (
+    isRecord(entry) && entry.pluginId === pluginId && entry.installed === true
+  )));
+}
+
+function assertRemoveResult(payload, pluginId) {
+  if (payload.pluginId !== pluginId) {
+    throw new InstallerError(
+      `Plugin remove returned '${String(payload.pluginId)}', expected '${pluginId}'.`,
+    );
+  }
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function install({ json }) {
+  progress(json, 'Session Orchestrator — Codex Setup');
+  progress(json, '=================================');
+
+  const version = parseCodexVersion(runCodex(['--version']));
+  if (compareVersions(version, MIN_CODEX_VERSION) < 0) {
+    throw new InstallerError(
+      `Codex ${formatVersion(version)} is unsupported; install Codex ${formatVersion(MIN_CODEX_VERSION)} or newer.`,
+      ERROR_CATEGORIES.USER,
+    );
+  }
+  progress(json, `Codex: ${formatVersion(version)}`);
+
+  const features = parseFeatures(runCodex(['features', 'list']));
+  requireStableFeature(features, 'plugins');
+  requireStableFeature(features, 'hooks');
+  progress(json, 'Features: plugins stable true; hooks stable true');
+
+  const expectedVersion = validateLocalContract();
+  progress(json, `Local contract: valid (${expectedVersion})`);
+
+  const marketplaceList = runCodexJson(
+    ['plugin', 'marketplace', 'list', '--json'],
+    'Marketplace list',
+  );
+  assertMarketplaceCompatible(marketplaceList);
+
+  progress(json, `Marketplace: adding '${SO_ROOT}'`);
+  const marketplaceAdd = runCodexJson(
+    ['plugin', 'marketplace', 'add', SO_ROOT, '--json'],
+    'Marketplace add',
+  );
+  assertMarketplaceAddResult(marketplaceAdd);
+  progress(
+    json,
+    marketplaceAdd.alreadyAdded
+      ? `Marketplace: '${MARKETPLACE_NAME}' already uses this source; refreshed`
+      : `Marketplace: '${MARKETPLACE_NAME}' added`,
+  );
+
+  progress(json, `Plugin: adding '${PLUGIN_ID}'`);
+  const pluginAdd = runCodexJson(
+    ['plugin', 'add', PLUGIN_ID, '--json'],
+    'Plugin add',
+  );
+  assertPluginAddResult(pluginAdd, expectedVersion);
+
+  const firstPluginList = runCodexJson(
+    ['plugin', 'list', '--available', '--json'],
+    'Plugin list',
+  );
+  const firstEntries = assertTargetHealthy(firstPluginList, expectedVersion, 'Post-install check');
+  progress(json, `Plugin: '${PLUGIN_ID}' is installed, enabled, and at ${expectedVersion}`);
+
+  const removedLegacyPlugins = [];
+  for (const legacyPluginId of installedLegacyPluginIds(firstEntries)) {
+    const removeResult = runCodexJson(
+      ['plugin', 'remove', legacyPluginId, '--json'],
+      `Plugin remove (${legacyPluginId})`,
+    );
+    assertRemoveResult(removeResult, legacyPluginId);
+    removedLegacyPlugins.push(legacyPluginId);
+    progress(json, `Removed legacy plugin: ${legacyPluginId}`);
+  }
+
+  const finalPluginList = runCodexJson(
+    ['plugin', 'list', '--available', '--json'],
+    'Final plugin list',
+  );
+  const finalEntries = assertTargetHealthy(finalPluginList, expectedVersion, 'Final check');
+  const remainingLegacyPlugins = installedLegacyPluginIds(finalEntries);
+  if (remainingLegacyPlugins.length > 0) {
+    throw new InstallerError(
+      `Final check: legacy plugins remain installed: ${remainingLegacyPlugins.join(', ')}.`,
+    );
+  }
+
+  const result = {
+    ok: true,
+    codexVersion: formatVersion(version),
+    marketplace: MARKETPLACE_NAME,
+    marketplaceSource: SO_ROOT,
+    marketplaceAlreadyAdded: marketplaceAdd.alreadyAdded,
+    pluginId: PLUGIN_ID,
+    pluginVersion: expectedVersion,
+    installed: true,
+    enabled: true,
+    removedLegacyPlugins,
+    nextSteps: [
+      'Start a fresh Codex task or fully restart Codex so the plugin and hooks reload.',
+      'In the fresh task, run /hooks and review the hook bundle before approving it.',
+      'This installer does not write or bypass hook trust.',
+    ],
+  };
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write('\nDone. The public Codex plugin state is healthy.\n\n');
+    process.stdout.write('Next steps:\n');
+    for (const [index, step] of result.nextSteps.entries()) {
+      process.stdout.write(`  ${index + 1}. ${step}\n`);
+    }
+  }
+}
+
+try {
+  const options = parseArguments(process.argv.slice(2));
+  if (options.help) printHelp();
+  else if (options.version) process.stdout.write(`${readBaseVersion()}\n`);
+  else install(options);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`ERROR: ${message}\n`);
+  process.exitCode = error instanceof InstallerError && error.category === ERROR_CATEGORIES.USER
+    ? 1
+    : 2;
+}