@marcomigozzi/trailhead 0.3.0 → 0.5.0

package/bin/lib/host-descriptor.js

@@ -0,0 +1,404 @@
+'use strict';
+// host-descriptor.js: trailhead's host descriptor + runtime detection module.
+//
+// This is the single source of truth for the 3 integration axes trailhead
+// projects onto each supported host (commandSurface, subagentToolkit,
+// hookBus), the frozen per-host descriptors built from them, and the
+// projection/degradation helpers that describe what each host gets (or loses)
+// relative to Claude. It is sized to trailhead's actual footprint: 2 hosts
+// (claude, codex), not a general n-host framework.
+//
+// Two consumers:
+//   - install-time: the installer (a separate ticket, #23) reads HOSTS/AXES/
+//     configDirFor/hyphenateCommand/emitsAgentToml to lay out commands,
+//     prompts, and config for whichever host it's installing into.
+//   - run-time: detectHost() lets the engine's inline rules (executed as
+//     Claude Agent-tool text, not compiled code) figure out which host they
+//     are actually running under, without any installer having run first.
+//
+// This is a scaled-down mirror, in shape only, of GSD's host-integration.cjs
+// (the axes + per-host descriptor table) and host-runtime-detection.cjs (the
+// detection ladder + never-throw contract). GSD's versions are TS-compiled
+// and carry far more hosts, adapters, and history; this file intentionally
+// does not copy that machinery, only the pattern, dimensioned down to what
+// trailhead needs today.
+//
+// Self-contained: no dependencies beyond Node's stdlib. Every exported
+// function is pure. All descriptor data is frozen so callers can't mutate
+// the single source of truth out from under each other.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// The Codex support floor (decision #27): multi_agent (the binding constraint)
+// is stable at 0.145.0, so trailhead's single codex descriptor (subagentToolkit
+// 'full') is only projected onto a Codex at or above this version.
+const CODEX_MIN_VERSION = '0.145.0';
+
+// --- Axis 1: the 3 closed vocabularies (decision #17) ---------------------
+// Each axis is a closed set of values a host can take. Closed on purpose:
+// a new value here is a design decision (a new ticket), not a typo away.
+const AXES = Object.freeze({
+  // How a host surfaces trailhead's commands to the user.
+  //   'slash-file'    Claude: namespaced slash-command files under commands/trailhead/*.md
+  //   'hyphen-prompt' Codex:  flat, hyphenated prompt files (trailhead-work.md, etc.)
+  //   'skill'         Codex:  one native skill folder skills/trailhead/, invoked `$trailhead <verb>`
+  commandSurface: Object.freeze(['slash-file', 'hyphen-prompt', 'skill']),
+  // Whether the host has a dedicated subagent/Task-fanout toolkit.
+  //   'full' Claude: the Agent tool; Codex: the native multi_agent tools
+  //          (spawn_agent/..., on by default at the supported floor)
+  //   'none' a host with no such toolkit; everything the engine needs runs inline
+  subagentToolkit: Object.freeze(['full', 'none']),
+  // Whether the host has a lifecycle hook bus (PreToolUse/PostToolUse/Stop/...).
+  //   'host' Claude: native hooks; Codex: the `features.hooks` lifecycle bus
+  //   'none' a host with no hook bus (no supported host today, kept for future hosts)
+  hookBus: Object.freeze(['host', 'none']),
+});
+
+// --- Axis 2: per-host descriptors -------------------------------------------
+// Each descriptor is a frozen data record, not behavior. Anything that reads
+// like "if codex, do X" should be reading one of these fields, not branching
+// on a host-name string sprinkled through the codebase.
+const HOSTS = Object.freeze({
+  claude: Object.freeze({
+    label: 'Claude Code',
+    configDirEnv: 'CLAUDE_CONFIG_DIR',
+    configDirDefault: '.claude',
+    axes: Object.freeze({
+      commandSurface: 'slash-file',
+      subagentToolkit: 'full',
+      hookBus: 'host',
+    }),
+    // Structural layout only. The exact target tree (which files land where)
+    // is refined by the installer, ticket #23; this just says "namespaced
+    // dir of .md files" so the installer has a starting shape to work from.
+    commands: Object.freeze({
+      layout: 'namespaced-dir',
+      dir: 'commands/trailhead',
+      ext: '.md',
+    }),
+    // Explicit data flag, deliberately NOT derived from subagentToolkit:
+    // "full toolkit" and "emits an agents.toml" are independent facts. Claude
+    // uses its native Agent tool and has no reason to emit one.
+    emitsAgentToml: false,
+    // Whether this host can run a subagent on a trailhead `models.*` value (a
+    // Claude model id). Claude Code's subagents do, so the per-activity model
+    // split takes effect here. Like emitsAgentToml, an explicit data flag, not
+    // derived from an axis.
+    honorsModelKeys: true,
+    hooks: Object.freeze({ bus: 'host' }),
+  }),
+  codex: Object.freeze({
+    label: 'Codex',
+    configDirEnv: 'CODEX_HOME',
+    configDirDefault: '.codex',
+    axes: Object.freeze({
+      commandSurface: 'skill',
+      subagentToolkit: 'full',
+      hookBus: 'host',
+    }),
+    // A single native Codex skill folder, invoked `$trailhead <verb>`.
+    commands: Object.freeze({
+      layout: 'native-skill',
+      dir: 'skills/trailhead',
+    }),
+    // Also explicit, also independent from the axis: Codex's native multi_agent
+    // tools are on by default and need NO manifest for base fan-out, but when
+    // models.codex.* is set per technique, the installer projects those pins
+    // into per-technique agents/*.toml files under ~/.codex/agents/ and turns
+    // on features.multi_agent_v2 so Codex honours them.
+    emitsAgentToml: true,
+    // Whether Codex can run a subagent on a trailhead `models.*` value: NO. Its
+    // subagent model registry is OpenAI-only, so a Claude id (e.g. claude-sonnet-5)
+    // cannot run; subagents inherit the one session model. Hence models.* still
+    // collapses here even though fan-out is available.
+    honorsModelKeys: false,
+    // Codex now has a native hook bus (stable at the install floor #27), so
+    // the guardrails (secret-guard, commit-guard, etc.) run as real Codex
+    // hooks, projected into ~/.codex/hooks.json by the installer. The
+    // models.* collapse is the only remaining Codex degradation.
+    hooks: Object.freeze({ bus: 'host' }),
+  }),
+});
+
+// --- Helper: getHost ---------------------------------------------------------
+// Resolve a host name to its descriptor. Throws on an unknown name, naming
+// both the offender and the known hosts, so a typo fails loud at the call
+// site instead of silently returning undefined.
+function getHost(name) {
+  // Own-property check, not `HOSTS[name]`: a bare index walks the prototype
+  // chain, so inherited keys ('toString', 'constructor', ...) would slip past
+  // a truthiness guard and hand back a non-descriptor instead of throwing.
+  if (!Object.prototype.hasOwnProperty.call(HOSTS, name)) {
+    throw new Error(`host-descriptor: unknown host "${name}" (known hosts: ${Object.keys(HOSTS).join(', ')})`);
+  }
+  return HOSTS[name];
+}
+
+// Normalize a "host" argument that may already be a descriptor (has `axes`)
+// or may be a name string, to a descriptor. Used by the small helpers below
+// that accept either, per the spec.
+function resolveHost(host) {
+  return typeof host === 'string' ? getHost(host) : host;
+}
+
+// --- Helper: configDirFor ----------------------------------------------------
+// Resolve where a host's config directory lives: an explicit env override
+// first (e.g. CLAUDE_CONFIG_DIR, CODEX_HOME), falling back to the host's
+// default dir under the user's homedir (e.g. ~/.claude, ~/.codex).
+function configDirFor(host, opts = {}) {
+  const descriptor = resolveHost(host);
+  const env = opts.env || process.env;
+  const homedir = opts.homedir || os.homedir();
+  const override = env[descriptor.configDirEnv];
+  if (typeof override === 'string' && override.trim() !== '') {
+    return override;
+  }
+  return path.join(homedir, descriptor.configDirDefault);
+}
+
+// --- Helper: hyphenateCommand -------------------------------------------------
+// Normalize a command name to Codex's flat hyphen-prompt surface: strip a
+// leading slash, replace ':' namespace separators with '-'.
+//   '/trailhead:work' -> 'trailhead-work'
+//   'trailhead:work'  -> 'trailhead-work'
+//   '/trailhead'      -> 'trailhead'
+function hyphenateCommand(name) {
+  return String(name).trim().replace(/^\//, '').replace(/:/g, '-');
+}
+
+// --- Helper: emitsAgentToml ---------------------------------------------------
+function emitsAgentToml(host) {
+  return resolveHost(host).emitsAgentToml;
+}
+
+// --- Helper: degradations -----------------------------------------------------
+// Plain data-table lookup of what degrades on a given host relative to
+// Claude (the reference host with the full toolkit and a native hook bus).
+// Deliberately NOT clever: no inference engine, just entries keyed off the
+// axes that produced them, so the list stays legible and auditable.
+function degradations(host) {
+  const descriptor = resolveHost(host);
+  const entries = [];
+
+  if (descriptor.axes.subagentToolkit === 'none') {
+    entries.push({
+      from: 'subagent fan-out (research, codebase-map, review, plan, execute)',
+      to: 'inline sequential execution in the main session',
+    });
+  }
+
+  // Independent of fan-out: a host whose subagents can't run a trailhead
+  // models.* value (a Claude id) loses the per-activity model split even when
+  // fan-out itself is available (e.g. Codex, OpenAI-only subagent registry).
+  if (!descriptor.honorsModelKeys) {
+    entries.push({
+      from: 'per-activity model split (models.*)',
+      to: 'collapses to a single session model (recover the split with models.codex.*)',
+    });
+  }
+
+  if (descriptor.axes.hookBus === 'none') {
+    entries.push({
+      from: 'lifecycle hooks (secret-guard, commit-guard, injection-scanner, check-update)',
+      to: 'a git commit-msg hook plus inline prose guardrails (decision #16)',
+    });
+  }
+
+  return entries;
+}
+
+// --- Helper: modelsCollapseNotice --------------------------------------------
+// The one-time notice the engine surfaces at session start when models.* is
+// configured on a host that cannot honour it (honorsModelKeys === false): its
+// subagents run on the host's own model, so the per-activity split collapses to
+// the single session model (see degradations()), UNLESS the host has a parallel
+// native namespace configured. On Codex that namespace is models.codex.* (OpenAI
+// model ids): once any models.codex.* key is set, the notice stays silent (the
+// user has already opted into the honoured namespace there) and only reworded
+// to point at models.codex.* while a stray Claude-id models.* key is set and
+// models.codex.* is still empty. Keyed on honorsModelKeys, NOT on
+// subagentToolkit: a host can have fan-out yet still be unable to run a
+// subagent on a Claude models.* id (Codex). Pure: returns the notice string, or
+// null when there is nothing to say (the host honours the keys, no models.* is
+// set, or models.codex.* is already set). The caller owns the "one-time"
+// bookkeeping (a marker file) and how the string is shown, so this stays pure
+// and trivially testable.
+function modelsCollapseNotice(host, config) {
+  const descriptor = resolveHost(host);
+  if (descriptor.honorsModelKeys) return null;
+  const models = config && typeof config === 'object' ? config.models : null;
+  if (!models || typeof models !== 'object') return null;
+
+  const codexModels = models.codex && typeof models.codex === 'object' ? models.codex : null;
+  const codexSet = codexModels
+    ? Object.keys(codexModels).filter(
+        (k) => codexModels[k] != null && String(codexModels[k]).trim() !== ''
+      )
+    : [];
+  if (codexSet.length > 0) return null;
+
+  // Exclude the literal 'codex' key: models.codex is a nested object, and
+  // String({}).trim() is the non-empty "[object Object]", so without this
+  // exclusion a lone models.codex.* namespace (with no Claude ids set) would
+  // mis-count as a set Claude key and mis-fire the notice below.
+  const set = Object.keys(models).filter(
+    (k) => k !== 'codex' && models[k] != null && String(models[k]).trim() !== ''
+  );
+  if (set.length === 0) return null;
+
+  return (
+    `Heads up: trailhead is running on ${descriptor.label}, whose subagents ` +
+    `run on its own OpenAI models. Your models.* setting (${set.join(', ')}) is a ` +
+    `Claude model id and cannot take effect here: every activity's subagent still ` +
+    `inherits the one session model. Set models.codex.* (OpenAI model ids) instead ` +
+    `to get the per-activity split on ${descriptor.label}. The models.* keys stay ` +
+    `in .trailhead/config.json and apply again on Claude Code.`
+  );
+}
+
+// --- Helper: updateNotice -----------------------------------------------------
+// The one-line update notice the engine surfaces at session start on a host
+// WITHOUT a hook bus (no SessionStart check-update hook, no statusline flag):
+// there the engine runs the throttled check inline and shows this. Pure: given
+// the host and a parsed update-check cache object, returns the notice string,
+// or null when nothing should be shown (the host has a hook bus, or no update
+// is available). Keying on hookBus === 'none' means it never fires on a host
+// that already notifies via the hook + statusline (no double-notify). The
+// caller owns the cache I/O and throttling, mirroring modelsCollapseNotice.
+function updateNotice(host, cache) {
+  const descriptor = resolveHost(host);
+  if (descriptor.axes.hookBus !== 'none') return null;
+  if (!cache || typeof cache !== 'object' || !cache.updateAvailable) return null;
+  const latest = String(cache.latest || '').trim();
+  const installed = String(cache.installed || '').trim();
+  const ver = latest ? ` ${latest}` : '';
+  const from = installed ? ` (you have ${installed})` : '';
+  return `Heads up: trailhead${ver} is available${from}. Run /trailhead:update to install it.`;
+}
+
+// --- Codex version floor gate (decision #27) --------------------------------
+// The install-time enforcement of CODEX_MIN_VERSION. Pure and never-throwing:
+// the installer runs `codex --version` and hands the raw output here; this
+// decides whether to project. Below the floor the multi_agent tools the
+// adapter's §D relies on are not stable, so the installer refuses (fail below
+// floor). An undeterminable version (codex absent, or unparseable output)
+// fails OPEN with a warning: a gate can't prove a violation it can't read, and
+// a false block would wrongly stop a valid install.
+
+// Extract a dotted-numeric [major, minor, patch] from any version string
+// ("codex-cli 0.149.0", "0.145.0-alpha.1", "0.149.0"), or null when absent.
+function parseVersion(str) {
+  const m = String(str == null ? '' : str).match(/(\d+)\.(\d+)\.(\d+)/);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+// -1 / 0 / 1 comparison of two [maj,min,patch] triples.
+function compareVersion(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+// Verdict the installer acts on. Given the raw `codex --version` output (or
+// null/'' when the probe failed) and the floor, returns { ok, proceed,
+// undetermined, version, floor, message }. Never throws.
+//   at/above floor      -> { ok:true,  proceed:true,  undetermined:false, message:null }
+//   parseable & below   -> { ok:false, proceed:false, undetermined:false, message:<refuse> }
+//   unparseable/absent   -> { ok:true,  proceed:true,  undetermined:true,  message:<warn> }
+function codexVersionGate(versionOutput, floor = CODEX_MIN_VERSION) {
+  const got = parseVersion(versionOutput);
+  if (!got) {
+    return {
+      ok: true, proceed: true, undetermined: true, version: null, floor,
+      message: `Could not determine the Codex version (\`codex --version\` unavailable or unrecognised). trailhead needs Codex >= ${floor} for its multi_agent fan-out; proceeding, but the subagent features will not work on an older Codex.`,
+    };
+  }
+  // A caller-supplied floor that can't be parsed can't gate anything: treat it
+  // as no constraint (proceed) rather than dereferencing null in compareVersion,
+  // honouring the "never throws" contract. The default floor is always parseable.
+  const floorV = parseVersion(floor);
+  if (floorV && compareVersion(got, floorV) < 0) {
+    return {
+      ok: false, proceed: false, undetermined: false, version: got.join('.'), floor,
+      message: `Codex ${got.join('.')} is below trailhead's floor of ${floor}: its multi_agent subagent tools are not stable, so trailhead will not install. Upgrade Codex to >= ${floor} and re-run.`,
+    };
+  }
+  return { ok: true, proceed: true, undetermined: false, version: got.join('.'), floor, message: null };
+}
+
+// --- Runtime host detection --------------------------------------------------
+// Mirrors GSD's host-runtime-detection.cjs in shape: a short signal ladder,
+// wrapped so it NEVER throws. This is what lets the engine's inline rules
+// (plain text executed by the Claude Agent tool, not compiled code) figure
+// out which host they're actually running under at runtime, independent of
+// whatever the installer laid down at install-time.
+
+// Codex sandbox env vars set by the shell tool / Seatbelt child-process spawn.
+// Best-effort: absent under sandbox_mode = "danger-full-access", so this
+// signal degrades to the next rung when unset rather than being load-bearing.
+const CODEX_SESSION_ENV_SIGNALS = Object.freeze(['CODEX_SANDBOX', 'CODEX_SANDBOX_NETWORK_DISABLED']);
+const CODEX_HOME_ENV = 'CODEX_HOME';
+const CODEX_CONFIG_MARKER = 'config.toml';
+
+// detectHost never throws: every read here (including `deps.env` itself,
+// which a caller could hand in as a throwing Proxy) is wrapped in a single
+// guarded region that degrades to 'claude' on any unexpected error. A
+// detection helper that can throw is worse than useless in an inline rule
+// that has no try/catch of its own around it: the whole point is that
+// callers can invoke this without defensive code of their own.
+function detectHost(deps = {}) {
+  try {
+    const env = deps.env || process.env;
+    const fileExists = deps.fileExists || ((p) => fs.existsSync(p));
+
+    for (const key of CODEX_SESSION_ENV_SIGNALS) {
+      const value = env[key];
+      if (typeof value === 'string' && value.trim() !== '') {
+        return 'codex';
+      }
+    }
+
+    const codexHome = env[CODEX_HOME_ENV];
+    if (typeof codexHome === 'string' && codexHome.trim() !== '') {
+      try {
+        if (fileExists(path.join(codexHome, CODEX_CONFIG_MARKER))) {
+          return 'codex';
+        }
+      } catch {
+        // Swallow probe failures (EACCES etc.) and fall through to claude.
+      }
+    }
+
+    // The DEFAULT ~/.codex/config.toml is deliberately NEVER probed here.
+    // Every machine that has ever run Codex has that file lying around, so
+    // checking it unconditionally would misreport plain Claude Code sessions
+    // as codex just because Codex was installed at some point. Only an
+    // EXPLICITLY exported CODEX_HOME counts: that's the current session
+    // designating a Codex root, not ambient machine history.
+    return 'claude';
+  } catch {
+    return 'claude';
+  }
+}
+
+module.exports = {
+  AXES,
+  HOSTS,
+  getHost,
+  configDirFor,
+  hyphenateCommand,
+  emitsAgentToml,
+  degradations,
+  modelsCollapseNotice,
+  updateNotice,
+  codexVersionGate,
+  parseVersion,
+  detectHost,
+  CODEX_MIN_VERSION,
+  CODEX_SESSION_ENV_SIGNALS,
+  CODEX_HOME_ENV,
+  CODEX_CONFIG_MARKER,
+};

package/bin/lib/host-descriptor.test.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// Tests for host-descriptor.js. Run: node host-descriptor.test.js
+// No framework: plain asserts, mirrors the style of trailhead-secret-guard.test.js.
+const assert = require('assert');
+const {
+  AXES,
+  HOSTS,
+  getHost,
+  configDirFor,
+  hyphenateCommand,
+  emitsAgentToml,
+  degradations,
+  modelsCollapseNotice,
+  updateNotice,
+  codexVersionGate,
+  parseVersion,
+  CODEX_MIN_VERSION,
+  detectHost,
+} = require('./host-descriptor.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// --- AXES ---
+ok('AXES is frozen', Object.isFrozen(AXES));
+ok('AXES.commandSurface is frozen and correct', Object.isFrozen(AXES.commandSurface) &&
+  AXES.commandSurface.length === 3 &&
+  AXES.commandSurface.includes('slash-file') && AXES.commandSurface.includes('hyphen-prompt') &&
+  AXES.commandSurface.includes('skill'));
+ok('AXES.subagentToolkit is frozen and correct', Object.isFrozen(AXES.subagentToolkit) &&
+  AXES.subagentToolkit.length === 2 &&
+  AXES.subagentToolkit.includes('full') && AXES.subagentToolkit.includes('none'));
+ok('AXES.hookBus is frozen and correct', Object.isFrozen(AXES.hookBus) &&
+  AXES.hookBus.length === 2 &&
+  AXES.hookBus.includes('host') && AXES.hookBus.includes('none'));
+
+// --- getHost ---
+const claude = getHost('claude');
+const codex = getHost('codex');
+ok('getHost(claude) has correct axes', claude.axes.commandSurface === 'slash-file' &&
+  claude.axes.subagentToolkit === 'full' && claude.axes.hookBus === 'host');
+ok('getHost(codex) has correct axes', codex.axes.commandSurface === 'skill' &&
+  codex.axes.subagentToolkit === 'full' && codex.axes.hookBus === 'host');
+ok('getHost(codex).hooks.bus === "host"', codex.hooks.bus === 'host');
+assert.throws(() => getHost('gemini'), /gemini/i, 'getHost(gemini) throws naming the unknown host');
+ok('getHost(gemini) throws', (() => {
+  try { getHost('gemini'); return false; } catch { return true; }
+})());
+// Inherited prototype keys are not hosts: getHost must throw, not hand back an
+// Object.prototype member (own-property check, not a bare index truthiness test).
+ok('getHost(toString) throws (no prototype-chain leak)', (() => {
+  try { getHost('toString'); return false; } catch { return true; }
+})());
+ok('getHost(constructor) throws (no prototype-chain leak)', (() => {
+  try { getHost('constructor'); return false; } catch { return true; }
+})());
+
+// --- frozen descriptors ---
+ok('getHost(codex) descriptor is frozen', Object.isFrozen(codex));
+ok('getHost(claude) descriptor is frozen', Object.isFrozen(claude));
+ok('HOSTS is frozen', Object.isFrozen(HOSTS));
+
+// --- emitsAgentToml ---
+ok('emitsAgentToml(claude) === false', emitsAgentToml('claude') === false);
+ok('emitsAgentToml(codex) === true', emitsAgentToml('codex') === true);
+
+// --- honorsModelKeys ---
+ok('claude honours models.* keys', claude.honorsModelKeys === true);
+ok('codex does NOT honour models.* keys (OpenAI-only subagent registry)', codex.honorsModelKeys === false);
+
+// --- hyphenateCommand ---
+ok('hyphenateCommand strips leading slash and replaces colon', hyphenateCommand('/trailhead:work') === 'trailhead-work');
+ok('hyphenateCommand handles no leading slash', hyphenateCommand('trailhead:work') === 'trailhead-work');
+ok('hyphenateCommand handles no colon', hyphenateCommand('/trailhead') === 'trailhead');
+
+// --- configDirFor ---
+ok('configDirFor(claude) uses env override', configDirFor('claude', { env: { CLAUDE_CONFIG_DIR: '/x/y' }, homedir: '/home/u' }) === '/x/y');
+ok('configDirFor(claude) falls back to homedir default', configDirFor('claude', { env: {}, homedir: '/home/u' }).endsWith('/home/u/.claude') ||
+  configDirFor('claude', { env: {}, homedir: '/home/u' }) === require('path').join('/home/u', '.claude'));
+ok('configDirFor(codex) falls back to homedir default', configDirFor('codex', { env: {}, homedir: '/home/u' }) === require('path').join('/home/u', '.codex'));
+
+// --- degradations ---
+ok('degradations(claude) is empty', Array.isArray(degradations('claude')) && degradations('claude').length === 0);
+ok('degradations(codex) is non-empty', Array.isArray(degradations('codex')) && degradations('codex').length > 0);
+ok('degradations(codex) no longer lists subagent fan-out (it has multi_agent)',
+  !degradations('codex').some((d) => /fan-out/.test(d.from)));
+ok('degradations(codex) still lists the per-activity model split collapse',
+  degradations('codex').some((d) => /model split/.test(d.from)));
+ok('degradations(codex) model-split entry points at models.codex.* recovery',
+  degradations('codex').some((d) => /model split/.test(d.from) && /models\.codex/.test(d.to)));
+ok('degradations(codex) no longer lists lifecycle hooks (it has a native hook bus)',
+  !degradations('codex').some((d) => /lifecycle hooks/.test(d.from)));
+
+// --- modelsCollapseNotice ---
+ok('modelsCollapseNotice(claude, models set) is null (has toolkit)',
+  modelsCollapseNotice('claude', { models: { execute: 'claude-sonnet-5' } }) === null);
+ok('modelsCollapseNotice(codex, no models) is null',
+  modelsCollapseNotice('codex', {}) === null);
+ok('modelsCollapseNotice(codex, empty models) is null',
+  modelsCollapseNotice('codex', { models: {} }) === null);
+ok('modelsCollapseNotice(codex, nullish/empty values) is null',
+  modelsCollapseNotice('codex', { models: { plan: '', execute: null } }) === null);
+ok('modelsCollapseNotice(codex, models set) names the set keys', (() => {
+  const msg = modelsCollapseNotice('codex', { models: { plan: 'x', execute: 'y' } });
+  return typeof msg === 'string' && msg.includes('plan') && msg.includes('execute') && msg.includes('Codex');
+})());
+ok('modelsCollapseNotice(codex, undefined config) is null',
+  modelsCollapseNotice('codex') === null);
+ok('modelsCollapseNotice(claude, models set) is null (Claude honours the keys)',
+  modelsCollapseNotice('claude', { models: { plan: 'claude-opus-5' } }) === null);
+ok('modelsCollapseNotice(codex, only Claude models.* set) mentions models.codex', (() => {
+  const msg = modelsCollapseNotice('codex', { models: { plan: 'x', execute: 'y' } });
+  return typeof msg === 'string' && msg.includes('models.codex');
+})());
+ok('modelsCollapseNotice is null once models.codex.* is set even if Claude models.* also set',
+  modelsCollapseNotice('codex', { models: { plan: 'claude-opus-5', codex: { plan: 'gpt-5.6-sol' } } }) === null);
+ok('modelsCollapseNotice: lone codex namespace, no Claude id, is null (k !== "codex" guard)',
+  modelsCollapseNotice('codex', { models: { codex: { execute: 'gpt-5.6-terra' } } }) === null);
+// Exercises the k !== 'codex' guard directly: a lone codex namespace whose
+// values are all blank leaves codexSet empty, so control reaches the Claude-key
+// filter, where the bare `codex` object key must NOT be counted (String({}) is
+// non-empty). Without the guard this returns a spurious notice instead of null.
+ok('modelsCollapseNotice: lone all-blank codex namespace, no Claude id, is null (fails without the k !== "codex" guard)',
+  modelsCollapseNotice('codex', { models: { codex: { plan: '' } } }) === null);
+ok('modelsCollapseNotice: codex namespace with only empty/nullish values does not silence a real Claude-id notice', (() => {
+  const msg = modelsCollapseNotice('codex', { models: { plan: 'claude-opus-5', codex: { plan: '' } } });
+  return typeof msg === 'string' && msg.includes('plan') && !msg.includes('codex)');
+})());
+
+// --- updateNotice ---
+// Both hosts now have a hook bus (hookBus !== 'none'), so updateNotice never
+// fires for either: the SessionStart hook + (on Codex) its stdout
+// additionalContext handle the notification instead.
+ok('updateNotice(codex, update available) is null (codex has a hook bus now)',
+  updateNotice('codex', { updateAvailable: true, latest: '9.9.9', installed: '0.0.1' }) === null);
+ok('updateNotice(codex, no update available) is null',
+  updateNotice('codex', { updateAvailable: false }) === null);
+ok('updateNotice(codex, null cache) is null',
+  updateNotice('codex', null) === null);
+ok('updateNotice(claude, update available) is null (claude has a hook bus)',
+  updateNotice('claude', { updateAvailable: true, latest: '0.3.0' }) === null);
+
+// --- detectHost ---
+ok('detectHost: CODEX_SANDBOX signals codex', detectHost({ env: { CODEX_SANDBOX: 'seatbelt' } }) === 'codex');
+ok('detectHost: CODEX_SANDBOX_NETWORK_DISABLED signals codex', detectHost({ env: { CODEX_SANDBOX_NETWORK_DISABLED: '1' } }) === 'codex');
+ok('detectHost: CODEX_HOME with marker file signals codex', detectHost({
+  env: { CODEX_HOME: '/c' },
+  fileExists: (p) => p === '/c/config.toml',
+}) === 'codex');
+ok('detectHost: CODEX_HOME without marker file falls back to claude', detectHost({
+  env: { CODEX_HOME: '/c' },
+  fileExists: () => false,
+}) === 'claude');
+ok('detectHost: no signals falls back to claude', detectHost({ env: {} }) === 'claude');
+ok('detectHost: never throws, degrades to claude', detectHost({
+  env: new Proxy({}, { get() { throw new Error('boom'); } }),
+}) === 'claude');
+
+// --- codexVersionGate (install-time floor, #27/#28) ---
+ok('CODEX_MIN_VERSION is 0.145.0', CODEX_MIN_VERSION === '0.145.0');
+ok('parseVersion extracts a dotted triple', (() => { const v = parseVersion('codex-cli 0.149.0-alpha'); return v[0] === 0 && v[1] === 149 && v[2] === 0; })());
+ok('parseVersion returns null when absent', parseVersion('no version here') === null);
+ok('codexVersionGate at the floor proceeds', codexVersionGate('0.145.0').ok === true && codexVersionGate('codex-cli 0.145.0').proceed === true);
+ok('codexVersionGate above the floor proceeds cleanly', (() => { const g = codexVersionGate('0.149.0'); return g.ok === true && g.proceed === true && g.undetermined === false; })());
+ok('codexVersionGate below the floor (patch) refuses', (() => { const g = codexVersionGate('0.144.1'); return g.ok === false && g.proceed === false && /below/.test(g.message); })());
+ok('codexVersionGate well below the floor (minor) refuses', codexVersionGate('0.120.0').proceed === false);
+ok('codexVersionGate unparseable is undetermined but proceeds (fail-open)', (() => { const g = codexVersionGate('weird output'); return g.proceed === true && g.undetermined === true && typeof g.message === 'string'; })());
+ok('codexVersionGate null (codex absent) proceeds with a warning', (() => { const g = codexVersionGate(null); return g.proceed === true && g.undetermined === true && typeof g.message === 'string'; })());
+ok('codexVersionGate honours an explicit higher floor', codexVersionGate('0.150.0', '0.200.0').proceed === false);
+ok('codexVersionGate never throws on an unparseable floor (proceeds)', (() => { const g = codexVersionGate('0.149.0', 'not-a-version'); return g.proceed === true; })());
+
+console.log(`✓ host-descriptor: ${passed} assertions passed`);