@brunobracaioli/aibrain 0.4.0-beta.12 → 0.4.0-beta.14

package/README.md

@@ -30,6 +30,19 @@ roles. Nothing is written to `~/.codex`, `~/.agents` or the project, and the
 session's folder is deleted on exit. An older Codex starts without the pack and
 says `codex_outdated`.
 
+`aisac init [dir]` (licensed accounts, client `0.4.0-beta.14` or later) writes the
+AISAC skeleton into a new or existing project: `CLAUDE.md`, `AGENTS.md`,
+`NOTES.example.md`, the `docs/` tree with its templates, a Claude Code rules file,
+a CI workflow with pinned actions, Dependabot, `.gitignore` and the workloop
+template. The templates travel inside the licensed pack, fetched and verified like
+a launch; the command writes only files that are missing, never follows a symbolic
+link, never touches `.git/` and prints every file it wrote or skipped. Options:
+`--stack node|python|none` (otherwise detected from `package.json`, `pyproject.toml`
+or `requirements.txt`), `--lang pt-BR|en`, `--dry-run`, `--json`. Exit codes: `0`
+when every file exists or was written, `1` for a license, pack or write failure
+(nothing is written before the pack is verified), `2` for a usage error. Until the
+pack carries the templates, the command says so and writes nothing.
+
 Licensed `aisac claude` sessions also load guardrail hooks as the session plugin
 `aisac-guardrails`.
 - **Default on:** `secrets-guard` refuses secret files by name. Four more hooks
@@ -41,6 +54,12 @@ Licensed `aisac claude` sessions also load guardrail hooks as the session plugin
   them from inside a session.
 - **Code:** it ships in this package and runs locally. Nothing comes from the
   server.
+- **Codex (0.166.0 or later):** licensed `aisac codex` sessions get the same hooks
+  from session flags. Codex runs them only after you approve the AISAC hooks once
+  in `/hooks`, and you can switch each one off there too. The launch line says how
+  many are on and how many wait for that review; `aisac doctor` reports the same
+  under `extensions.codexHooks`. A new Node path (for example after an nvm or
+  Homebrew upgrade) changes the hook commands, so Codex asks for the review again.
 
 Licensed sessions of `aisac claude` and `aisac codex` can also load reviewed MCP
 servers: `github` (read-only, token in `GITHUB_PERSONAL_ACCESS_TOKEN`), `supabase`

package/dist/claude-observation.mjs

@@ -16,7 +16,7 @@ export const MAX_LOG_FILES = 3;
 const LOCK_WAIT_MS = 250;
 const LOCK_STALE_MS = 30_000;
 const ADMISSION_MS = 60 * 60 * 1000;
-export const ADAPTER_VERSION = '0.4.0-beta.12';
+export const ADAPTER_VERSION = '0.4.0-beta.14';
 const MAX_DIAGNOSTIC_COUNT = 10_000_000;
 const MAX_DIAGNOSTIC_BYTES = 128 * 1024 * 1024;
 const CHECKPOINT_BACKENDS = new Set(['native_store', 'private_file']);

package/dist/cli.mjs

@@ -37,11 +37,14 @@ import {
   resolvePackLocale,
   writeStoredLocale,
 } from './engineering-pack.mjs';
+import { initCommand } from './engineering-init.mjs';
 import { extensionsSummary, hooksCommand, mcpCommand } from './extensions-cli.mjs';
 import { sessionServers } from './mcp-servers.mjs';
 import { anyFormatter } from './guardrails/format.mjs';
+import { readCodexGuardrails } from './guardrails-plugin.mjs';
+import { codexHooksStatus, supportsCodexHooks } from './codex-hooks.mjs';
 
-const VERSION = '0.4.0-beta.12';
+const VERSION = '0.4.0-beta.14';
 // The command is `aisac`; `aibrain` is an alias installed from the same entry.
 const COMMAND = 'aisac';
 const ENDPOINT = 'https://mcp.ai-brain.aisac.cloud/mcp';
@@ -50,7 +53,7 @@ const LEGACY_DISCLOSURE_VERSION = 'aibrain-paid-context-v1-2026-10-09';
 
 function usage() {
   console.log(
-    `${COMMAND} ${VERSION}\n\nUsage:\n  ${COMMAND} setup [--client claude|codex|both] [--context-profile upstream|conservative]\n    [--compact-at 1..95] [--keep-threshold 0..1] [--preserve-recent 1..100]\n    [--min-reduction 0..1] [--truncate-head-chars 0..4096]\n    [--max-state-tokens 1000..25000] [--max-request-tokens 1000..30000]\n    [--tool-policy compatible|read_only] [--goal TEXT]\n  ${COMMAND} doctor [--json]\n  ${COMMAND} status [--json]\n  ${COMMAND} disable\n  ${COMMAND} setup --undo\n  ${COMMAND} claude [-- native-args...]\n  ${COMMAND} codex [-- native-args...]\n\nPolicy notes:\n  Automatic monitoring asks for compaction at compact-at percent; state/request\n  limits are estimated upper bounds and do not override server quotas.\n  min-reduction, truncate-head-chars and tool-policy apply only to Claude;\n  Codex keeps native compaction and same-session recovery.`,
+    `${COMMAND} ${VERSION}\n\nUsage:\n  ${COMMAND} setup [--client claude|codex|both] [--context-profile upstream|conservative]\n    [--compact-at 1..95] [--keep-threshold 0..1] [--preserve-recent 1..100]\n    [--min-reduction 0..1] [--truncate-head-chars 0..4096]\n    [--max-state-tokens 1000..25000] [--max-request-tokens 1000..30000]\n    [--tool-policy compatible|read_only] [--goal TEXT]\n  ${COMMAND} doctor [--json]\n  ${COMMAND} status [--json]\n  ${COMMAND} disable\n  ${COMMAND} setup --undo\n  ${COMMAND} claude [-- native-args...]\n  ${COMMAND} codex [-- native-args...]\n  ${COMMAND} init [dir] [--lang pt-BR|en] [--stack node|python|none] [--dry-run] [--json]\n\nPolicy notes:\n  Automatic monitoring asks for compaction at compact-at percent; state/request\n  limits are estimated upper bounds and do not override server quotas.\n  min-reduction, truncate-head-chars and tool-policy apply only to Claude;\n  Codex keeps native compaction and same-session recovery.`,
   );
   console.log(
     'Clients: setup without --client configures the clients installed on PATH (Claude Code, Codex, or both).',
@@ -65,7 +68,10 @@ function usage() {
     'AISAC Engineering: `aisac claude` and `aisac codex` (Codex 0.164+) load the licensed method; setup --lang pt-BR|en picks its language (before the first setup it runs the full setup); setup and doctor report the license; status stays offline. `aibrain` is an alias of `aisac`.',
   );
   console.log(
-    'Guardrails: `aisac hooks` lists them (a checklist on a terminal); `aisac hooks enable|disable <id>...` and `aisac hooks reset` change the next `aisac claude` session.',
+    'Project skeleton: `aisac init [dir]` (licensed accounts) writes the AISAC skeleton from the pack into a new or existing project, only the files that are missing; `--dry-run` lists them, `--stack` picks node|python|none when detection is not enough.',
+  );
+  console.log(
+    'Guardrails: `aisac hooks` lists them (a checklist on a terminal); `aisac hooks enable|disable <id>...` and `aisac hooks reset` change the next `aisac claude` or `aisac codex` session.',
   );
   console.log(
     'MCP catalog: `aisac mcp` lists the reviewed servers (GitHub, Supabase, Vercel, Playwright, Context7); `aisac mcp enable|disable <id>...`, `aisac mcp reset`, `aisac mcp info <id>` and `aisac mcp login <id>` (Codex) change or explain the next session.',
@@ -601,8 +607,48 @@ async function setup(args) {
   if (line !== null) console.log(line);
 }
 
-/** Extension state plus whether `format-on-edit` has a formatter in this folder (FR8). */
-async function doctorExtensions() {
+/**
+ * Whether Codex runs the AISAC hooks the user has on, from Codex's own
+ * `hooks/list` in this folder (FR6, FR8, E6b). No session starts, and Codex
+ * writes no config or trust record. Codex is not asked when the last launch had
+ * no license, because the launcher then hands Codex no hook.
+ * @param {{ executable: string | null, version: string | null | undefined, licensed: boolean }} codex
+ */
+async function doctorCodexHooks({ executable, version, licensed }) {
+  if (executable === null) return { status: 'codex_not_found' };
+  if (!supportsCodexHooks(version)) return { status: 'codex_version_unsupported' };
+  if (!licensed) return { status: 'not_licensed' };
+  const read = await readCodexGuardrails({
+    root: stateRoot(),
+    packageRoot: PACKAGE_ROOT,
+    executable,
+    cwd: process.cwd(),
+    profile: undefined,
+    environment: process.env,
+  }).catch(() => undefined);
+  if (read === undefined) return { status: 'list_failed' };
+  if (read === null) return { status: 'none_enabled' };
+  const { summary } = read;
+  if (summary === null) return { status: 'list_failed' };
+  const status = codexHooksStatus(summary);
+  return {
+    status,
+    handlers: summary.handlers,
+    review: summary.review,
+    off: summary.off,
+    missing: summary.missing,
+    ...(summary.review.length > 0
+      ? { remedy: 'Run aisac codex, open /hooks and approve the AISAC hooks.' }
+      : {}),
+  };
+}
+
+/**
+ * Extension state plus whether `format-on-edit` has a formatter in this folder,
+ * and whether Codex runs the hooks (FR8).
+ * @param {{ executable: string | null, version: string | null | undefined }} codex
+ */
+async function doctorExtensions(codex) {
   const summary = await extensionsSummary(stateRoot());
   // A token server is skipped at launch when its variable is unset (names only).
   const mcpMissingEnv = sessionServers(summary.mcp, 'claude', process.env).missingEnv.map(
@@ -613,7 +659,9 @@ async function doctorExtensions() {
     : (await anyFormatter(process.cwd()))
       ? 'ready'
       : 'no_formatter_found';
-  return { ...summary, formatOnEdit, mcpMissingEnv };
+  const licensed = (await readLastLaunch(stateRoot()))?.state === 'loaded';
+  const codexHooks = await doctorCodexHooks({ ...codex, licensed });
+  return { ...summary, formatOnEdit, mcpMissingEnv, codexHooks };
 }
 
 /** @param {boolean} json */
@@ -710,7 +758,10 @@ async function doctor(json) {
     },
     engineering,
     engineeringPack: await engineeringPackState(),
-    extensions: await doctorExtensions(),
+    extensions: await doctorExtensions({
+      executable: native.codex,
+      version: codexCompatibility?.version,
+    }),
     paidOrPilot: probe?.ok
       ? 'provider_free_probe_ok; paid entitlement or pilot invitation remains server-enforced'
       : config
@@ -798,6 +849,14 @@ async function main(argv) {
   }
   if (command === 'hooks') return hooksCommand(rest);
   if (command === 'mcp') return mcpCommand(rest);
+  if (command === 'init')
+    return initCommand(rest, {
+      packageRoot: PACKAGE_ROOT,
+      readConfig,
+      stateRoot,
+      cwd: process.cwd(),
+      env: process.env,
+    });
   if (command === 'disable') {
     if (rest.length > 0) throw new Error('disable_does_not_accept_options');
     return removeOwnedSetup();
@@ -850,5 +909,7 @@ main(cliArgs).catch((error) => {
     const guide = /** @type {{ guide?: unknown }} */ (error ?? {}).guide;
     if (typeof guide === 'string') console.error(`\n${guide}`);
   }
-  process.exitCode = 1;
+  // Usage errors of `aisac init` exit 2 (spec FR3); everything else exits 1.
+  const exitCode = /** @type {{ exitCode?: unknown }} */ (error ?? {}).exitCode;
+  process.exitCode = exitCode === 2 ? 2 : 1;
 });

package/dist/codex-hooks.mjs

@@ -0,0 +1,411 @@
+// @ts-check
+/**
+ * AISAC guardrails in Codex (spec aisac-engineering-extensions FR6, E6b).
+ *
+ * Codex loads session-flag hooks as `untrusted`. The user approves them once in
+ * `/hooks`, and Codex keys that approval, and the off switch, by position
+ * (`<event>:<group>:<handler>`) and command line (measured on 0.166.0). So:
+ * - the launch emits every catalog hook, in CODEX_HOOK_POSITIONS order, each with
+ *   a byte-stable command: the Node executable, the dispatcher, the event and the
+ *   hook id. No launch directory, version, locale or random value goes in it;
+ * - what changes per launch (the enabled hooks, the locale, the launch's state
+ *   folder, the preferences file) reaches the hook process through the
+ *   app-server's environment, which Codex hook processes inherit (measured on
+ *   0.166.0), as one JSON value in GUARDRAILS_SESSION_ENV.
+ * The launcher hands the monitor CODEX_HOOKS_ENV (enabled ids and locale). The
+ * monitor validates it against its own catalog and builds the flags and the
+ * session value itself, so the variable can never inject a command or a path.
+ * This module imports only the catalog and the TOML helper, so the monitor stays
+ * small.
+ */
+import { isAbsolute, join, resolve } from 'node:path';
+import { CODEX_HOOK_POSITIONS, HOOK_CATALOG, hookById } from './extensions-catalog.mjs';
+import { tomlBasicString } from './codex-engineering.mjs';
+
+/** Launcher to monitor: the enabled hook ids and the locale. */
+export const CODEX_HOOKS_ENV = 'AISAC_EXTENSIONS_CODEX_HOOKS';
+/** Monitor to hook processes, through the app-server's environment. */
+export const GUARDRAILS_SESSION_ENV = 'AISAC_GUARDRAILS_SESSION';
+const SCHEMA_VERSION = 1;
+// Same names as the Claude session plugin (guardrails-plugin.mjs) and the
+// preferences module (EXTENSIONS_FILE); a test keeps them equal.
+const STATE_DIRECTORY = 'guardrails-state';
+const PREFERENCES_FILE = 'extensions.json';
+const MAX_VALUE_BYTES = 8 * 1024;
+const MAX_PATH_LENGTH = 4096;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/u;
+const LOCALES = /** @type {const} */ (['pt-BR', 'en']);
+/** First Codex release whose hooks were measured with real turns (spike part 2). */
+const MIN_CODEX_HOOKS_VERSION = /** @type {const} */ ([0, 166, 0]);
+/** @type {Readonly<Record<string, number>>} */
+const TIMEOUT_SECONDS = Object.freeze({
+  PreToolUse: 5,
+  PostToolUse: 5,
+  UserPromptSubmit: 5,
+  Stop: 5,
+  SessionStart: 10,
+  PreCompact: 10,
+});
+// Codex reports camelCase event names in hooks/list.
+/** @type {Readonly<Record<string, string>>} */
+const LISTED_EVENT = Object.freeze({
+  PreToolUse: 'preToolUse',
+  PostToolUse: 'postToolUse',
+  UserPromptSubmit: 'userPromptSubmit',
+  SessionStart: 'sessionStart',
+  PreCompact: 'preCompact',
+  Stop: 'stop',
+});
+
+/** @typedef {import('./extensions-catalog.mjs').HookEvent} HookEvent */
+/** @typedef {'pt-BR' | 'en'} HookLocale */
+/** @typedef {{ node: string, dispatcher: string }} HookCommandPaths */
+/** @typedef {{ schemaVersion: 1, hooks: string[], locale: HookLocale }} CodexHooksValue */
+/**
+ * @typedef {object} GuardrailsSession
+ * @property {1} schemaVersion
+ * @property {string[]} hooks The hooks the user had on when the session started.
+ * @property {HookLocale} locale
+ * @property {string} stateDir The launch's guardrail state folder, deleted on exit.
+ * @property {string} prefsPath The preferences file (FR2.2).
+ */
+/**
+ * @typedef {object} CodexHookHandler
+ * @property {HookEvent} event
+ * @property {string} id
+ * @property {string | undefined} matcher
+ * @property {string} command
+ * @property {number} timeout
+ */
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {value is string} */
+function isCleanAbsolutePath(value) {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value.length <= MAX_PATH_LENGTH &&
+    !CONTROL_CHARACTERS.test(value) &&
+    isAbsolute(value) &&
+    resolve(value) === value
+  );
+}
+
+/** @param {unknown} value @returns {value is HookLocale} */
+function isLocale(value) {
+  return typeof value === 'string' && LOCALES.includes(/** @type {HookLocale} */ (value));
+}
+
+/** POSIX single-quote quoting for the shell that runs the hook command. @param {string} value */
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/** Ids that are Codex catalog hooks, in catalog order, without repeats. @param {unknown} ids */
+function codexHookIds(ids) {
+  if (!Array.isArray(ids)) return null;
+  const wanted = new Set(ids);
+  if (ids.length !== wanted.size) return null;
+  for (const id of wanted)
+    if (typeof id !== 'string' || hookById(id)?.clients.includes('codex') !== true) return null;
+  return HOOK_CATALOG.map((entry) => entry.id).filter((id) => wanted.has(id));
+}
+
+/**
+ * Whether this Codex version gets the guardrails. A null or malformed version
+ * never does.
+ * @param {string | null | undefined} version
+ */
+export function supportsCodexHooks(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/u.exec(version ?? '');
+  if (match === null) return false;
+  const parts = match.slice(1).map(Number);
+  for (let index = 0; index < MIN_CODEX_HOOKS_VERSION.length; index += 1) {
+    const part = /** @type {number} */ (parts[index]);
+    const minimum = MIN_CODEX_HOOKS_VERSION[index] ?? 0;
+    if (part !== minimum) return part > minimum;
+  }
+  return true;
+}
+
+/** The catalog matcher of a hook's binding for one event. @param {string} id @param {string} event */
+function bindingMatcher(id, event) {
+  return hookById(id)?.bindings.find((binding) => binding.event === event)?.matcher;
+}
+
+/**
+ * The byte-stable command of one Codex hook.
+ * @param {HookCommandPaths} paths @param {string} event @param {string} id
+ */
+export function codexHookCommand(paths, event, id) {
+  if (!isCleanAbsolutePath(paths.node) || !isCleanAbsolutePath(paths.dispatcher))
+    throw new Error('codex_hooks_path');
+  return [
+    shellQuote(paths.node),
+    shellQuote(paths.dispatcher),
+    '--client',
+    'codex',
+    '--event',
+    event,
+    '--hooks',
+    id,
+  ].join(' ');
+}
+
+/**
+ * Every Codex hook handler, in position order: one matcher group per hook, so
+ * the user can switch each one off in `/hooks`.
+ * @param {HookCommandPaths} paths
+ * @returns {CodexHookHandler[]}
+ */
+export function codexHookHandlers(paths) {
+  return Object.entries(CODEX_HOOK_POSITIONS).flatMap(([event, ids]) =>
+    ids.map((id) => ({
+      event: /** @type {HookEvent} */ (event),
+      id,
+      matcher: bindingMatcher(id, event),
+      command: codexHookCommand(paths, event, id),
+      timeout: TIMEOUT_SECONDS[event] ?? 5,
+    })),
+  );
+}
+
+/**
+ * Session-only `-c` flags for the owned app-server, one per event.
+ * @param {HookCommandPaths} paths
+ * @returns {string[]}
+ */
+export function codexHookConfigArgs(paths) {
+  /** @type {Map<string, string[]>} */
+  const groups = new Map();
+  for (const handler of codexHookHandlers(paths)) {
+    const matcher =
+      handler.matcher === undefined ? '' : `matcher=${tomlBasicString(handler.matcher)},`;
+    const group = `{${matcher}hooks=[{type="command",command=${tomlBasicString(handler.command)},timeout=${handler.timeout}}]}`;
+    groups.set(handler.event, [...(groups.get(handler.event) ?? []), group]);
+  }
+  return [...groups].flatMap(([event, list]) => ['-c', `hooks.${event}=[${list.join(',')}]`]);
+}
+
+/**
+ * The launcher's value for the monitor. Ids that are not Codex catalog hooks
+ * are dropped.
+ * @param {string[]} hooks @param {HookLocale} locale
+ */
+export function codexHooksValue(hooks, locale) {
+  const ids = codexHookIds([
+    ...new Set(hooks.filter((id) => hookById(id)?.clients.includes('codex') === true)),
+  ]);
+  return JSON.stringify({
+    schemaVersion: SCHEMA_VERSION,
+    hooks: ids ?? [],
+    locale: isLocale(locale) ? locale : 'en',
+  });
+}
+
+/**
+ * Parse the monitor's value; null when absent or when no hook is on.
+ * @param {string | undefined} raw
+ * @returns {CodexHooksValue | null}
+ */
+export function parseCodexHooks(raw) {
+  if (raw === undefined || raw === '') return null;
+  if (Buffer.byteLength(raw, 'utf8') > MAX_VALUE_BYTES) throw new Error('codex_hooks_too_large');
+  /** @type {unknown} */
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error('codex_hooks_invalid');
+  }
+  if (
+    !isRecord(value) ||
+    Object.keys(value).sort().join(',') !== 'hooks,locale,schemaVersion' ||
+    value.schemaVersion !== SCHEMA_VERSION ||
+    !isLocale(value.locale)
+  )
+    throw new Error('codex_hooks_invalid');
+  const hooks = codexHookIds(value.hooks);
+  if (hooks === null) throw new Error('codex_hooks_invalid');
+  return hooks.length === 0 ? null : { schemaVersion: SCHEMA_VERSION, hooks, locale: value.locale };
+}
+
+/**
+ * The value the hook processes read, built by the monitor: the launcher's
+ * choices plus the launch's own state folder (deleted with the launch on exit)
+ * and the preferences file of the state root the pack was checked against.
+ * @param {CodexHooksValue} value
+ * @param {{ launchDirectory: string, stateRoot: string }} paths
+ */
+export function guardrailsSessionValue(value, paths) {
+  const parsed = parseGuardrailsSession(
+    JSON.stringify({
+      schemaVersion: SCHEMA_VERSION,
+      hooks: value.hooks,
+      locale: value.locale,
+      stateDir: join(paths.launchDirectory, STATE_DIRECTORY),
+      prefsPath: join(resolve(paths.stateRoot), PREFERENCES_FILE),
+    }),
+  );
+  if (parsed === null) throw new Error('codex_hooks_session_invalid');
+  return JSON.stringify(parsed);
+}
+
+/**
+ * Parse the session value inside a hook process; null when absent or invalid,
+ * so the hook does nothing.
+ * @param {string | undefined} raw
+ * @returns {GuardrailsSession | null}
+ */
+export function parseGuardrailsSession(raw) {
+  if (raw === undefined || raw === '' || Buffer.byteLength(raw, 'utf8') > MAX_VALUE_BYTES)
+    return null;
+  /** @type {unknown} */
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (
+    !isRecord(value) ||
+    Object.keys(value).sort().join(',') !== 'hooks,locale,prefsPath,schemaVersion,stateDir' ||
+    value.schemaVersion !== SCHEMA_VERSION ||
+    !isLocale(value.locale) ||
+    !isCleanAbsolutePath(value.stateDir) ||
+    !isCleanAbsolutePath(value.prefsPath)
+  )
+    return null;
+  const hooks = codexHookIds(value.hooks);
+  if (hooks === null) return null;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    hooks,
+    locale: value.locale,
+    stateDir: value.stateDir,
+    prefsPath: value.prefsPath,
+  };
+}
+
+/**
+ * @typedef {object} CodexHooksSummary
+ * @property {{ total: number, trusted: number, untrusted: number, modified: number, disabled: number, missing: number }} handlers
+ *   Every AISAC hook Codex was given, by what `hooks/list` reports.
+ * @property {string[]} on Enabled guardrails whose hooks are all trusted and on.
+ * @property {string[]} review Enabled guardrails with a hook that waits for review in `/hooks`.
+ * @property {string[]} off Enabled guardrails switched off in Codex (`/hooks` or config.toml).
+ * @property {string[]} missing Enabled guardrails Codex did not load.
+ */
+
+/**
+ * What `hooks/list` says about the AISAC hooks. A guardrail counts as on only
+ * when every one of its hooks is trusted and enabled (spec FR6: an untrusted
+ * guardrail is never reported as on).
+ * @param {unknown} listed The `hooks/list` result.
+ * @param {HookCommandPaths} paths
+ * @param {string[]} enabled The guardrails the user has on.
+ * @returns {CodexHooksSummary}
+ */
+export function summarizeCodexHooks(listed, paths, enabled) {
+  const rows = (isRecord(listed) && Array.isArray(listed.data) ? listed.data : []).flatMap(
+    (entry) => (isRecord(entry) && Array.isArray(entry.hooks) ? entry.hooks : []),
+  );
+  /** @type {Map<string, Record<string, unknown>>} */
+  const byCommand = new Map();
+  for (const row of rows)
+    if (isRecord(row) && row.source === 'sessionFlags' && typeof row.command === 'string')
+      byCommand.set(`${String(row.eventName)}\u0000${row.command}`, row);
+  const handlers = codexHookHandlers(paths);
+  const counts = {
+    total: handlers.length,
+    trusted: 0,
+    untrusted: 0,
+    modified: 0,
+    disabled: 0,
+    missing: 0,
+  };
+  /** @type {Map<string, 'on' | 'review' | 'off' | 'missing'>} */
+  const states = new Map();
+  const rank = { on: 0, off: 1, review: 2, missing: 3 };
+  for (const handler of handlers) {
+    const row = byCommand.get(`${LISTED_EVENT[handler.event]}\u0000${handler.command}`);
+    /** @type {'on' | 'review' | 'off' | 'missing'} */
+    let state;
+    if (row === undefined) {
+      counts.missing += 1;
+      state = 'missing';
+    } else if (row.trustStatus === 'untrusted' || row.trustStatus === 'modified') {
+      counts[row.trustStatus] += 1;
+      state = 'review';
+    } else if (row.trustStatus !== 'trusted' && row.trustStatus !== 'managed') {
+      counts.untrusted += 1;
+      state = 'review';
+    } else if (row.enabled === false) {
+      counts.trusted += 1;
+      counts.disabled += 1;
+      state = 'off';
+    } else {
+      counts.trusted += 1;
+      state = 'on';
+    }
+    const previous = states.get(handler.id);
+    if (previous === undefined || rank[state] > rank[previous]) states.set(handler.id, state);
+  }
+  const ids =
+    codexHookIds([
+      ...new Set(enabled.filter((id) => hookById(id)?.clients.includes('codex') === true)),
+    ]) ?? [];
+  return {
+    handlers: counts,
+    on: ids.filter((id) => states.get(id) === 'on'),
+    review: ids.filter((id) => states.get(id) === 'review'),
+    off: ids.filter((id) => states.get(id) === 'off'),
+    missing: ids.filter((id) => states.get(id) === 'missing'),
+  };
+}
+
+/**
+ * The doctor's one-word state for the AISAC hooks in Codex, worst first: a
+ * guardrail waiting for review outranks one Codex did not load, which outranks
+ * one switched off in Codex.
+ * @param {CodexHooksSummary} summary
+ * @returns {'needs_review' | 'not_loaded' | 'off_in_codex' | 'on'}
+ */
+export function codexHooksStatus(summary) {
+  if (summary.review.length > 0) return 'needs_review';
+  if (summary.missing.length > 0) return 'not_loaded';
+  if (summary.off.length > 0) return 'off_in_codex';
+  return 'on';
+}
+
+/** @param {number} count */
+function guardrails(count) {
+  return `${count} guardrail${count === 1 ? '' : 's'}`;
+}
+
+/**
+ * The launch line for Codex. With no summary (the listing failed), it says the
+ * guardrails were handed to Codex and names the review, never "on".
+ * @param {number} enabledCount
+ * @param {CodexHooksSummary | null} summary
+ */
+export function codexHooksLine(enabledCount, summary) {
+  const change = '(aisac hooks to change them)';
+  if (summary === null)
+    return `AISAC Engineering: ${guardrails(enabledCount)} loaded for Codex; Codex runs them only after you approve the AISAC hooks once in /hooks ${change}.`;
+  const total =
+    summary.on.length + summary.review.length + summary.off.length + summary.missing.length;
+  if (summary.on.length === total) return `AISAC Engineering: ${guardrails(total)} on ${change}.`;
+  const parts = [`AISAC Engineering: ${summary.on.length} of ${guardrails(total)} on`];
+  if (summary.review.length > 0)
+    parts.push(
+      `${summary.review.length} wait for your review: open /hooks in Codex and approve the AISAC hooks`,
+    );
+  if (summary.off.length > 0) parts.push(`${summary.off.length} switched off in Codex (/hooks)`);
+  if (summary.missing.length > 0) parts.push(`${summary.missing.length} not loaded by Codex`);
+  return `${parts.join('; ')} ${change}.`;
+}