@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/ai_council/transport_resolver.ts

@@ -48,10 +48,22 @@ import {
     type BillingClass,
     type EnvironmentReport,
 } from '../_lib/environment_detector.js';
+import { resolve_mode } from './modes.js';
 
 /** A concrete transport a member can actually run on. `auto` is not one. */
 export type Transport = 'api' | 'manual' | 'cli';
 
+/**
+ * Machine-readable reason a member is `absent` from a pass
+ * (road-to-always-on-orchestration Phase 3.2). The static half — `no_binary`
+ * / `no_auth` — is decided here, at resolution time, before any provider
+ * call is attempted. The runtime half — `timeout` / `quota` — only exists
+ * once a call was actually attempted and failed; see
+ * `absentReasonFromCliFailure` below for the mapping FROM the mid-flight
+ * `CliFailureClass` a caller already classifies its errors into.
+ */
+export type AbsentReason = 'no_binary' | 'no_auth' | 'timeout' | 'quota';
+
 /** The accepted values of the `mode` key, including the resolver-only `auto`. */
 export const VALID_TRANSPORT_MODES: ReadonlySet<string> = new Set([
     'api',
@@ -73,6 +85,16 @@ export interface ResolvedTransport {
     readonly makesProviderCall: boolean;
     /** One-line reason. Non-empty exactly when `available` is false. */
     readonly reason: string | null;
+    /**
+     * Machine-readable classification of `reason`, for a pass artifact that
+     * needs to bucket absent members without parsing prose (Phase 3.2).
+     * Non-null for the two STATIC auto-chain failures this function can
+     * classify (`no_binary` / `no_auth`); `null` when `available` is true,
+     * and also `null` for the "unknown mode" validation-error path below —
+     * that is a config bug, not a missing-capability finding, so it does not
+     * belong in this enum.
+     */
+    readonly absentReason: AbsentReason | null;
 }
 
 export interface ResolveTransportOptions {
@@ -149,6 +171,7 @@ export function resolveTransport(opts: ResolveTransportOptions): ResolvedTranspo
             authSource,
             makesProviderCall: false,
             reason: null,
+            absentReason: null,
         };
     }
 
@@ -160,6 +183,7 @@ export function resolveTransport(opts: ResolveTransportOptions): ResolvedTranspo
             authSource,
             makesProviderCall: true,
             reason: null,
+            absentReason: null,
         };
     }
 
@@ -185,6 +209,7 @@ export function resolveTransport(opts: ResolveTransportOptions): ResolvedTranspo
             authSource,
             makesProviderCall: true,
             reason: null,
+            absentReason: null,
         };
     }
 
@@ -197,16 +222,80 @@ export function resolveTransport(opts: ResolveTransportOptions): ResolvedTranspo
             authSource,
             makesProviderCall: true,
             reason: null,
+            absentReason: null,
         };
     }
 
-    return unavailable(provider, billing, autoUnavailableReason(provider, binary, cliAuthed));
+    return unavailable(
+        provider,
+        billing,
+        autoUnavailableReason(provider, binary, cliAuthed),
+        classifyStaticAbsentReason(binary),
+    );
+}
+
+export interface ResolveMemberTransportOptions {
+    readonly provider: string;
+    /** The single read-only environment report `resolveTransport` needs. */
+    readonly report: EnvironmentReport;
+    /** e.g. `/council mode:manual`. Highest precedence layer. */
+    readonly invocationMode?: string | null;
+    /** The member's own config sub-dict (`ai_council.members.<name>`). */
+    readonly memberSettings?: ReadonlyMap<string, unknown> | Record<string, unknown> | null;
+    /** `ai_council.mode` / `defaults.mode`, already extracted by the caller. */
+    readonly globalMode?: string | null;
+    readonly binaryOverride?: string | null;
+    readonly apiKeyPresent?: boolean;
+}
+
+export interface ResolvedMemberTransport extends ResolvedTransport {
+    /** The mode `resolve_mode` chose BEFORE any `auto` expansion. */
+    readonly configuredMode: string;
+}
+
+/**
+ * The single reconciled entry point for "given this member's config, what
+ * transport does it actually run on" (road-to-always-on-orchestration
+ * Phase 3.1). Composes `modes.ts::resolve_mode` (which layer decided the
+ * mode) with `resolveTransport` (what `auto` expands to on THIS machine) so
+ * a caller never has to replicate either step by hand.
+ *
+ * This exists because the two functions previously lived at arm's length:
+ * `resolve_mode` can legitimately return the literal string `'auto'`, and
+ * nothing forced a caller to then route that value through
+ * `resolveTransport` — a hand-rolled `mode === 'api' | 'cli' | 'manual'`
+ * switch (the shape `council_cli.ts::build_members` still uses today) has
+ * no `'auto'` case and treats it as an unrecognised transport instead of
+ * expanding it. `resolveMemberTransport` is the fix: there is no longer a
+ * gap between "which mode was configured" and "which transport that becomes"
+ * for any caller that uses it instead of the two functions separately.
+ */
+export function resolveMemberTransport(
+    opts: ResolveMemberTransportOptions,
+): ResolvedMemberTransport {
+    const configuredMode = resolve_mode(opts.provider, {
+        invocationMode: opts.invocationMode ?? null,
+        memberSettings: opts.memberSettings ?? null,
+        globalMode: opts.globalMode ?? null,
+    });
+    const resolved = resolveTransport({
+        provider: opts.provider,
+        mode: configuredMode,
+        report: opts.report,
+        binaryOverride: opts.binaryOverride ?? null,
+        // `exactOptionalPropertyTypes` rejects an explicit `undefined` for an
+        // optional-boolean field, so the key is omitted entirely rather than
+        // forwarded as `apiKeyPresent: undefined`.
+        ...(opts.apiKeyPresent !== undefined ? { apiKeyPresent: opts.apiKeyPresent } : {}),
+    });
+    return { ...resolved, configuredMode };
 }
 
 function unavailable(
     _provider: string,
     billing: BillingClass,
     reason: string,
+    absentReason: AbsentReason | null = null,
 ): ResolvedTransport {
     return {
         available: false,
@@ -217,9 +306,21 @@ function unavailable(
         authSource: null,
         makesProviderCall: false,
         reason,
+        absentReason,
     };
 }
 
+/**
+ * `no_binary` when the CLI binary itself never resolved (whether or not a
+ * credential was found — a credential with nothing to run it against is
+ * still "the binary is missing" from the caller's point of view); `no_auth`
+ * when the binary IS present but neither the cli-auth nor the key rung
+ * resolved. Mirrors `autoUnavailableReason`'s three-way branch below.
+ */
+function classifyStaticAbsentReason(binary: string | null): AbsentReason {
+    return binary === null ? 'no_binary' : 'no_auth';
+}
+
 /** The one-line reason `auto` prints when no rung resolved. */
 function autoUnavailableReason(
     provider: string,
@@ -298,6 +399,31 @@ export function isFallbackEligible(failure: CliFailureClass): boolean {
     return FALLBACK_ELIGIBLE.has(failure);
 }
 
+/**
+ * Maps a mid-flight `CliFailureClass` (a call was actually attempted and
+ * failed) onto the same `AbsentReason` enum a static resolution failure
+ * uses (road-to-always-on-orchestration Phase 3.2/3.4), so a pass artifact
+ * can bucket every absent member — whether it never got a transport at all
+ * or lost one partway through — under one vocabulary. Returns `null` for a
+ * failure class outside the four-value enum (`cli_unsupported`,
+ * `server_error`, `other`); a caller falls back to the raw failure detail
+ * for those rather than mis-classifying them.
+ */
+export function absentReasonFromCliFailure(failure: CliFailureClass): AbsentReason | null {
+    switch (failure) {
+        case 'binary_missing':
+            return 'no_binary';
+        case 'auth_rejected':
+            return 'no_auth';
+        case 'timeout':
+            return 'timeout';
+        case 'quota_exhausted':
+            return 'quota';
+        default:
+            return null;
+    }
+}
+
 /**
  * One-shot, per-provider fallback ledger for a single invocation.
  *

package/src/scripts/ai_team/availability.ts

@@ -0,0 +1,110 @@
+/**
+ * `/team` availability — CLI-first, not settings-gated
+ * (road-to-always-on-orchestration Phase 1, Step 1.3).
+ *
+ * `ai_team.enabled` — the former master switch — was DELETED. `/team`'s
+ * on/off state is now a FACT resolved from the machine, the same doctrine
+ * already applied to the subagent and council layers (Phase 1): the codex
+ * CLI binary must resolve on `$PATH`, AND some auth for the `openai`
+ * provider must be detectable (subscription login, API key, key file, or
+ * env key — the same transport-preference order `auto` walks via
+ * `strongestAuth`). Reuses the existing, read-only, zero-spend,
+ * per-process-cached detector (`_lib/environment_detector.ts`); this module
+ * adds NO new probing and NO new cache of its own.
+ *
+ * `ai_team.allow_delegate` is UNCHANGED by this module: a distinct,
+ * write-access authorization gate that stacks ON TOP of availability, never
+ * a replacement for it (`assert_delegate_allowed` in `team_dispatch.ts`
+ * still checks it separately, after availability).
+ */
+import { detectEnvironment, strongestAuth } from '../_lib/environment_detector.js';
+import { load_agent_settings, type SettingsDict } from '../_lib/agent_settings.js';
+import { _team_codex_binary_name, shutilWhich } from '../_cli/cmd_doctor.js';
+
+/** Tool id `environment_detector` uses for the codex CLI (`install/toolDetection.ts`). */
+const CODEX_HOST_ID = 'codex';
+
+/** Provider id `environment_detector` / `PROVIDER_CLI_META` uses for the codex CLI. */
+const CODEX_PROVIDER = 'openai';
+
+/** The provider default `_team_codex_binary_name` falls back to with no override configured. */
+const DEFAULT_CODEX_BINARY = 'codex';
+
+export interface TeamAvailability {
+    readonly available: boolean;
+    /** One clear line for the user — populated only when `available` is false. */
+    readonly reason: string | null;
+}
+
+/**
+ * codex CLI binary + auth presence — the availability half of the `/team`
+ * gate. Cached per process via `detectEnvironment()`'s own no-argument memo
+ * (`resetEnvironmentCache()` in tests); this function adds no caching of
+ * its own.
+ *
+ * m5 fix (independent-review finding) — `detectEnvironment()`'s host probe
+ * is hardcoded to the literal binary name `codex`; it has no way to be told
+ * "check this other name/path instead". So an operator who set
+ * `members.openai.binary:` in `.ai-council.yml` (honoured under an
+ * effective mode of `cli` OR `auto` — `cmd_doctor.ts::_mayRunOverCli`) was
+ * invisible to this check: `/team` could report "codex CLI not available"
+ * even with a working, custom-named/pathed binary configured and
+ * functional. `_team_codex_binary_name` (shared with `cmd_doctor.ts`'s own
+ * `council-cli` / `team` checks, so the override-resolution logic has one
+ * source) resolves the SAME name `cmd_doctor` would use; when it differs
+ * from the provider default, this probes that name directly instead of
+ * trusting the fixed-name host detector.
+ */
+export function checkCodexAvailability(project_root: string = process.cwd()): TeamAvailability {
+    const report = detectEnvironment();
+    const configuredBinary = _team_codex_binary_name(project_root);
+    const installed =
+        configuredBinary !== DEFAULT_CODEX_BINARY
+            ? shutilWhich(configuredBinary) !== null
+            : (report.hosts.find((h) => h.id === CODEX_HOST_ID)?.installed ?? false);
+    if (!installed) {
+        return {
+            available: false,
+            reason:
+                'codex CLI not available — /team needs the codex CLI installed and ' +
+                'authenticated. Install: `npm install -g @openai/codex`, then run ' +
+                '`codex login`. Verify with `agent-config doctor --check team`.',
+        };
+    }
+    if (strongestAuth(report, CODEX_PROVIDER) === null) {
+        return {
+            available: false,
+            reason:
+                'codex CLI not available — no auth detected for it. Run `codex login` ' +
+                '(or set `OPENAI_API_KEY`). Verify with `agent-config doctor --check team`.',
+        };
+    }
+    return { available: true, reason: null };
+}
+
+/**
+ * `emergency.orchestration_halt` — the one audited incident switch over the
+ * always-on orchestration stack (subagents, council, TEAM). Reads the
+ * project settings cascade fresh (or an injected dict for tests) on every
+ * call — no cache of its own, so an armed halt takes effect on the very
+ * next read, same as every other `orchestration_halt` reader in the tree
+ * (`routing_doctor.ts`, `delegation_nudge_hook.ts`).
+ */
+export function isOrchestrationHalted(
+    settings?: SettingsDict | null,
+    cwd?: string | null,
+): boolean {
+    const merged = settings ?? load_agent_settings({ cwd: cwd ?? process.cwd() });
+    const emergency = (merged as Record<string, unknown>)['emergency'];
+    if (typeof emergency !== 'object' || emergency === null || Array.isArray(emergency)) {
+        return false;
+    }
+    return (emergency as Record<string, unknown>)['orchestration_halt'] === true;
+}
+
+/** The one-line halt notice — `/team` prints this verbatim when halted. */
+export const ORCHESTRATION_HALT_MESSAGE =
+    '/team is halted (`emergency.orchestration_halt: true`) — the always-on ' +
+    'orchestration stack (subagents, council, team) is paused for incident ' +
+    'response. Resume: set `orchestration_halt: false` with a non-empty ' +
+    '`orchestration_halt_justification` in `.agent-settings.yml`.';

package/src/scripts/ai_team/config.ts

@@ -4,23 +4,36 @@
  *
  * Mirrors the fail-closed validation posture of the council loader
  * (`src/scripts/ai_council/config.ts`) at a fraction of its surface: the
- * `ai_team` block has five flat keys and no nested sub-schemas, so this
- * loader is deliberately lean — defaults, per-key type checks, and hard
- * unknown-key rejection. Contract: `docs/contracts/ai-team-config.md`.
+ * `ai_team` block has a handful of flat keys and no nested sub-schemas
+ * beyond `review_gate`, so this loader is deliberately lean — defaults,
+ * per-key type checks, and hard unknown-key rejection. Contract:
+ * `docs/contracts/ai-team-config.md`.
  *
  * Unlike the council (ALWAYS user-global `.ai-council.yml`, ADR-104),
  * `ai_team` lives in the PROJECT settings cascade (`.agent-settings.yml`
- * via `load_agent_settings`) — team mode is a per-project posture
- * (default-off), not a per-developer credential store; the codex CLI
- * carries the subscription auth itself.
+ * via `load_agent_settings`) — team mode is a per-project posture, not a
+ * per-developer credential store; the codex CLI carries the subscription
+ * auth itself.
+ *
+ * `enabled` — the former master on/off switch — was DELETED
+ * (road-to-always-on-orchestration Phase 1, Step 1.3): `/team`'s
+ * availability is now a FACT resolved from the machine (codex CLI on
+ * `$PATH` + detectable auth — `src/scripts/ai_team/availability.ts`), not
+ * a settings flag, matching the doctrine already applied to the
+ * subagent/council layers. A leftover `enabled` key from an older install
+ * is accepted-and-ignored here (never rejected as unknown, never applied
+ * by any reader) so an existing project's `.agent-settings.yml` does not
+ * start failing `/team` outright; `load_agent_settings` still surfaces the
+ * one-line deprecation warning for it (`_lib/agent_settings.ts`).
  *
  * Validation contract (all enforced at load time, fail-closed):
  *
- * 1. `ai_team` absent → defaults (feature off). Non-mapping → error.
+ * 1. `ai_team` absent → defaults. Non-mapping → error.
  * 2. Unknown keys under `ai_team` are rejected — a typo must never
  *    silently disable a gate (`allow_delegate` misspelled = delegation
- *    stays off AND the load fails loudly).
- * 3. `enabled`, `allow_delegate`, `suppress_setup_hint` are booleans.
+ *    stays off AND the load fails loudly). `enabled` is the one
+ *    deliberate exception: accepted, untyped, ignored (see above).
+ * 3. `allow_delegate`, `suppress_setup_hint` are booleans.
  * 4. `model` is a non-empty string. `'auto'` = pass no `--model` flag
  *    (the codex CLI default applies); any other value passes through
  *    verbatim.
@@ -47,7 +60,6 @@ export interface AiTeamReviewGateConfig {
 }
 
 export interface AiTeamConfig {
-    readonly enabled: boolean;
     readonly model: string;
     readonly allow_delegate: boolean;
     readonly max_calls_per_day: number;
@@ -63,7 +75,6 @@ export const AI_TEAM_REVIEW_GATE_DEFAULTS: AiTeamReviewGateConfig = Object.freez
 
 /** Shipped defaults — byte-parity with `src/config/agent-settings.template.yml`. */
 export const AI_TEAM_DEFAULTS: AiTeamConfig = Object.freeze({
-    enabled: false,
     model: 'auto',
     allow_delegate: false,
     max_calls_per_day: 50,
@@ -79,7 +90,6 @@ export const AI_TEAM_DEFAULTS: AiTeamConfig = Object.freeze({
 export const AI_TEAM_MODEL_AUTO = 'auto';
 
 const _KNOWN_KEYS: ReadonlySet<string> = new Set([
-    'enabled',
     'model',
     'allow_delegate',
     'max_calls_per_day',
@@ -87,6 +97,14 @@ const _KNOWN_KEYS: ReadonlySet<string> = new Set([
     'review_gate',
 ]);
 
+/**
+ * Deleted key accepted-and-ignored for migration grace (see module docstring).
+ * Never added to `_KNOWN_KEYS` — it carries no validated type and is never
+ * read into `AiTeamConfig`; it exists in this set only so the unknown-key
+ * loop below does not fail-closed an existing project's leftover value.
+ */
+const _DELETED_KEYS: ReadonlySet<string> = new Set(['enabled']);
+
 const _KNOWN_REVIEW_GATE_KEYS: ReadonlySet<string> = new Set([
     'managed',
     'max_consecutive_blocks',
@@ -175,6 +193,9 @@ export function build_ai_team_config(raw: unknown): AiTeamConfig {
     }
 
     for (const key of Object.keys(raw)) {
+        if (_DELETED_KEYS.has(key)) {
+            continue; // deleted, accepted-and-ignored — see module docstring.
+        }
         if (!_KNOWN_KEYS.has(key)) {
             throw new TeamConfigError(
                 `ai_team.${key}: unknown key; valid: ` +
@@ -183,7 +204,6 @@ export function build_ai_team_config(raw: unknown): AiTeamConfig {
         }
     }
 
-    const enabled = _requireBool(raw, 'enabled', AI_TEAM_DEFAULTS.enabled);
     const allow_delegate = _requireBool(raw, 'allow_delegate', AI_TEAM_DEFAULTS.allow_delegate);
     const suppress_setup_hint = _requireBool(
         raw,
@@ -216,7 +236,7 @@ export function build_ai_team_config(raw: unknown): AiTeamConfig {
 
     const review_gate = _build_review_gate('review_gate' in raw ? raw['review_gate'] : undefined);
 
-    return { enabled, model, allow_delegate, max_calls_per_day, suppress_setup_hint, review_gate };
+    return { model, allow_delegate, max_calls_per_day, suppress_setup_hint, review_gate };
 }
 
 /**

package/src/scripts/ai_team/team_dispatch.ts

@@ -18,11 +18,20 @@
  * instead of live repo access, no background jobs, explicitly worse than the
  * plugin — pointing Claude-Code users back to the Phase 2 plugin path.
  *
- * Governance reuse (Phase 3 Step 3): same `ai_team` config (fail-closed when
- * `enabled: false`), same `cli_call_budget` openai quota bucket (the gate and
- * the recording both live in `CliClient.ask` — no new counter), same
- * `_AUTH_FAILURE_PATTERNS` classification. `--manual` renders the bundle
- * between `═` rules for paste-into-web usage — no call, no quota.
+ * Governance reuse (Phase 3 Step 3): same `ai_team` config, same
+ * `cli_call_budget` openai quota bucket (the gate and the recording both
+ * live in `CliClient.ask` — no new counter), same `_AUTH_FAILURE_PATTERNS`
+ * classification. `--manual` renders the bundle between `═` rules for
+ * paste-into-web usage — no call, no quota.
+ *
+ * Availability (road-to-always-on-orchestration Phase 1, Step 1.3):
+ * `ai_team.enabled` was DELETED. Every dispatch entry point below is
+ * fail-closed on TWO facts instead — `emergency.orchestration_halt` (the
+ * one audited incident switch over the always-on stack) and
+ * `checkCodexAvailability()` (codex CLI + auth presence,
+ * `./availability.js`) — never a settings flag. `ai_team.allow_delegate`
+ * is unchanged: a second, write-access opt-in that stacks ON TOP of
+ * availability in `assert_delegate_allowed`.
  *
  * The review system prompt is derived from the adversarial-review findings
  * shape of an Apache-2.0 upstream — attribution in the repo-root NOTICE file.
@@ -38,6 +47,12 @@ import {
     load_cli_call_counts,
     OpenAICliClient,
 } from '../ai_council/clients.js';
+import {
+    checkCodexAvailability,
+    isOrchestrationHalted,
+    ORCHESTRATION_HALT_MESSAGE,
+    type TeamAvailability,
+} from './availability.js';
 import { AI_TEAM_MODEL_AUTO, type AiTeamConfig, load_ai_team_config } from './config.js';
 
 // ── errors ──────────────────────────────────────────────────────────────
@@ -51,50 +66,67 @@ export class TeamDispatchError extends Error {
 }
 
 /**
- * Raised when `ai_team.enabled` is false — the fail-closed gate.
- * The message carries the enable pointer; callers print it verbatim.
+ * Raised when `/team` is unavailable — either `emergency.orchestration_halt`
+ * is set, or the codex CLI / auth availability check
+ * (`checkCodexAvailability`) failed. `reason` is the one-line message the
+ * relevant check produced; callers print it verbatim. There is no more
+ * settings flag behind this — see the module docstring.
  */
 export class TeamDisabledError extends TeamDispatchError {
-    constructor() {
-        super(
-            'team mode is disabled (`ai_team.enabled: false`, the shipped default). ' +
-                'Set `ai_team.enabled: true` in `.agent-settings.yml` to opt in — ' +
-                'see docs/contracts/ai-team-config.md.',
-        );
+    constructor(reason: string) {
+        super(reason);
         this.name = 'TeamDisabledError';
     }
 }
 
 /**
- * Thrown by `assert_delegate_allowed` when `ai_team.enabled` is true but the
+ * Thrown by `assert_delegate_allowed` when `/team` is available but the
  * second opt-in (`ai_team.allow_delegate`) is not. `/team delegate` is the
  * only wrapper that hands WRITE access to the second model, so it is
- * double-gated; `enabled: true` alone is never delegate authorization.
+ * double-gated; availability alone is never delegate authorization.
  */
 export class TeamDelegateDisabledError extends TeamDispatchError {
     constructor() {
         super(
             '`/team delegate` is disabled (`ai_team.allow_delegate: false`, the shipped ' +
                 'default). It is the only team-mode wrapper that hands write access to ' +
-                'the second model, so it needs its own opt-in: set both ' +
-                '`ai_team.enabled: true` and `ai_team.allow_delegate: true` in ' +
-                '`.agent-settings.yml` — see docs/contracts/ai-team-config.md.',
+                'the second model, so it needs its own opt-in: set ' +
+                '`ai_team.allow_delegate: true` in `.agent-settings.yml` (once /team ' +
+                'itself is available — codex CLI installed and authenticated) — see ' +
+                'docs/contracts/ai-team-config.md.',
         );
         this.name = 'TeamDelegateDisabledError';
     }
 }
 
+/** Test seams for the two availability facts (`assert_delegate_allowed`, `run_team_review`). */
+export interface TeamAvailabilityOverrides {
+    /** Default: `checkCodexAvailability()` — the real, cached, zero-spend probe. */
+    availability?: TeamAvailability;
+    /** Default: `isOrchestrationHalted(undefined, cwd)` — reads the real settings cascade. */
+    halted?: boolean;
+}
+
 /**
  * Deterministic mirror of the `/team delegate` double gate: throws
- * `TeamDisabledError` unless `ai_team.enabled`, then
+ * `TeamDisabledError` when halted or `/team` is unavailable, then
  * `TeamDelegateDisabledError` unless `ai_team.allow_delegate`. The command
  * doc's prose gates instruct the agent; this guard is the machine-checkable
  * contract (`--delegate-gate` CLI mode) tests pin against.
  */
-export function assert_delegate_allowed(config?: AiTeamConfig, cwd?: string | null): void {
+export function assert_delegate_allowed(
+    config?: AiTeamConfig,
+    cwd?: string | null,
+    overrides: TeamAvailabilityOverrides = {},
+): void {
     const cfg = config ?? load_ai_team_config({ cwd: cwd ?? null });
-    if (!cfg.enabled) {
-        throw new TeamDisabledError();
+    const halted = overrides.halted ?? isOrchestrationHalted(undefined, cwd ?? null);
+    if (halted) {
+        throw new TeamDisabledError(ORCHESTRATION_HALT_MESSAGE);
+    }
+    const availability = overrides.availability ?? checkCodexAvailability(cwd ?? undefined);
+    if (!availability.available) {
+        throw new TeamDisabledError(availability.reason ?? 'codex CLI not available.');
     }
     if (!cfg.allow_delegate) {
         throw new TeamDelegateDisabledError();
@@ -511,6 +543,10 @@ export interface RunTeamReviewOptions {
     cli_calls_path?: string | null;
     /** Sink for user-facing output; default `process.stdout`. */
     out?: (line: string) => void;
+    /** Test seam: override the availability check (default: the real, cached probe). */
+    availability?: TeamAvailability;
+    /** Test seam: override the halted flag (default: read from the settings cascade). */
+    halted?: boolean;
 }
 
 function _quota_snapshot(config: AiTeamConfig, cli_calls_path: string | null): TeamReviewQuota {
@@ -564,16 +600,22 @@ function _envelope_from_response(
 /**
  * Run the multi-host team-review fallback.
  *
- * Order of operations is the contract: (1) fail-closed config gate,
- * (2) capability-delta header at the top, (3) read-only bundle,
- * (4) manual render OR one synchronous `codex exec` call through the shared
- * quota/auth machinery, (5) envelope emission. Throws `TeamDisabledError`
- * when `ai_team.enabled` is false — never a silent no-op.
+ * Order of operations is the contract: (1) fail-closed availability gate —
+ * halted, then codex CLI/auth — (2) capability-delta header at the top,
+ * (3) read-only bundle, (4) manual render OR one synchronous `codex exec`
+ * call through the shared quota/auth machinery, (5) envelope emission.
+ * Throws `TeamDisabledError` when halted or unavailable — never a silent
+ * no-op.
  */
 export function run_team_review(opts: RunTeamReviewOptions = {}): TeamReviewRunResult {
     const config = opts.config ?? load_ai_team_config({ cwd: opts.cwd ?? null });
-    if (!config.enabled) {
-        throw new TeamDisabledError();
+    const halted = opts.halted ?? isOrchestrationHalted(undefined, opts.cwd ?? null);
+    if (halted) {
+        throw new TeamDisabledError(ORCHESTRATION_HALT_MESSAGE);
+    }
+    const availability = opts.availability ?? checkCodexAvailability(opts.cwd ?? undefined);
+    if (!availability.available) {
+        throw new TeamDisabledError(availability.reason ?? 'codex CLI not available.');
     }
     const out = opts.out ?? ((line: string): void => void process.stdout.write(`${line}\n`));