@event4u/agent-config 9.28.0 → 9.29.0

package/src/scripts/ai_council/clients.ts

@@ -1052,9 +1052,12 @@ export class SubprocessError extends Error {
  * `~/.event4u/agent-config/cli-calls.json` and resets on UTC date rollover.
  *
  * Subclass contract:
- * - `name`: provider key (`anthropic`, `openai`, `gemini`, …).
- * - `default_binary`: executable name resolved via PATH when the member-level
- *   `binary:` field is not set.
+ * - `super(opts, { name, default_binary })`: `name` is the provider key
+ *   (`anthropic`, `openai`, `gemini`, …); `default_binary` is the executable
+ *   resolved via PATH when the member-level `binary:` field is not set. Both
+ *   are passed explicitly to `super()` — not read off subclass instance
+ *   fields — because a subclass's own field initializers run only AFTER this
+ *   `super()` call returns.
  * - `_build_command(system_prompt, user_prompt, max_tokens)`: return the argv.
  * - `_parse_output(stdout, stderr)`: return a partial `CouncilResponse`.
  *
@@ -1097,8 +1100,22 @@ export abstract class CliClient extends ExternalAIClient {
         'usage limit',
     ];
 
-    constructor(opts: CliClientOptions & { model: string }) {
+    /**
+     * `identity` carries the subclass constants (`name`, `default_binary`)
+     * that construction validates against. They are passed explicitly rather
+     * than read off `this.name` / `this.default_binary` because subclass
+     * instance-field initializers (`override default_binary = 'claude'`,
+     * declared in the subclass body) run only AFTER this `super()` call
+     * returns — reading them here, before that happens, would always see the
+     * base class's own field defaults (`''`), not the subclass override.
+     */
+    constructor(
+        opts: CliClientOptions & { model: string },
+        identity: { name: string; default_binary: string },
+    ) {
         super();
+        this.name = identity.name;
+        this.default_binary = identity.default_binary;
         this.model = opts.model;
         this.timeout_seconds = opts.timeout_seconds ?? DEFAULT_CLI_TIMEOUT_SECONDS;
         this.max_calls_per_day = opts.max_calls_per_day ?? null;
@@ -1353,19 +1370,20 @@ export abstract class CliClient extends ExternalAIClient {
  * collides with argv length limits.
  */
 export class AnthropicCliClient extends CliClient {
-    override name = 'anthropic';
-    override default_binary = 'claude';
     override subscription_label = 'claude-pro';
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_ANTHROPIC_CLI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_ANTHROPIC_CLI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'anthropic', default_binary: 'claude' },
+        );
     }
 
     protected override _build_command(
@@ -1446,8 +1464,6 @@ export class AnthropicCliClient extends CliClient {
  * token usage in `usage.input_tokens` / `usage.output_tokens`.
  */
 export class OpenAICliClient extends CliClient {
-    override name = 'openai';
-    override default_binary = 'codex';
     override subscription_label = 'chatgpt-plus';
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1458,14 +1474,17 @@ export class OpenAICliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_OPENAI_CLI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_OPENAI_CLI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'openai', default_binary: 'codex' },
+        );
     }
 
     protected override _build_command(
@@ -1569,8 +1588,6 @@ export class OpenAICliClient extends CliClient {
  * stdin to dodge argv limits.
  */
 export class GeminiCliClient extends CliClient {
-    override name = 'gemini';
-    override default_binary = 'gemini';
     override subscription_label = 'gemini-pro';
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1581,14 +1598,17 @@ export class GeminiCliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_GEMINI_CLI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_GEMINI_CLI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'gemini', default_binary: 'gemini' },
+        );
     }
 
     protected override _build_command(
@@ -1686,8 +1706,6 @@ export class GeminiCliClient extends CliClient {
  * heuristically (chars / 4) for the audit-trail.
  */
 export class XAICliClient extends CliClient {
-    override name = 'xai';
-    override default_binary = 'grok';
     override billable = true; // community CLI consumes an API key — billable applies
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1698,14 +1716,17 @@ export class XAICliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_XAI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_XAI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'xai', default_binary: 'grok' },
+        );
     }
 
     protected override _build_command(
@@ -1752,8 +1773,6 @@ export class XAICliClient extends CliClient {
  * Invokes `perplexity -p <prompt>`. Output is plain text — no JSON envelope.
  */
 export class PerplexityCliClient extends CliClient {
-    override name = 'perplexity';
-    override default_binary = 'perplexity';
     override billable = true; // community CLI consumes an API key — billable applies
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1764,14 +1783,17 @@ export class PerplexityCliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_PERPLEXITY_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_PERPLEXITY_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'perplexity', default_binary: 'perplexity' },
+        );
     }
 
     protected override _build_command(

package/src/scripts/ai_council/config.ts

@@ -21,9 +21,12 @@
  *    a locally-installed CLI under subscription auth (free for
  *    first-party CLIs, billable for community wrappers); `auto` = pick
  *    per provider per invocation (cli → api → unavailable), resolved by
- *    `transport_resolver.ts`. `auto` is opt-in — it is never the shipped
- *    default, because flipping it would move an existing user's spend
- *    from per-token dollars onto subscription quota with no config edit.
+ *    `transport_resolver.ts`. `auto` is the SHIPPED DEFAULT
+ *    (road-to-always-on-orchestration Phase 3.1 — CLI-first is the
+ *    owner-set transport doctrine: ride the vendor CLI under subscription
+ *    auth first, fall to the metered API only where no CLI resolves).
+ *    `manual` and a pinned `api`/`cli` remain valid explicit per-member or
+ *    per-invocation overrides — `auto` never displaces one.
  * 3. `members.<name>` keys are restricted to the known provider set.
  * 4. `cost_budget.*` numeric fields are >= 0.
  * 5. Enabled members carry a non-empty `model` and `api_key_ref` when
@@ -37,7 +40,18 @@
  * 8. `binary:` is only valid when the member's effective mode is `cli` or
  *    `auto` (auto may resolve to the cli rung);
  *    `cli_call_budget.max_calls_per_day.<provider>` keys must be valid
- *    providers.
+ *    providers. `max_calls_per_day` SHIPS POPULATED with a generous
+ *    per-provider default (50/day, road-to-always-on-orchestration
+ *    Phase 3.4) for every known provider — a guard against a silent
+ *    always-on pass exhausting a subscription's plan quota, not a brake;
+ *    an explicit per-provider entry overrides just that provider's default.
+ * 9. `quorum` ∈ {`"majority"`, a positive integer} (default `"majority"`,
+ *    road-to-always-on-orchestration Phase 3.3). `"majority"` at n members
+ *    resolves to `ceil(n / 2)` — a SIMPLE majority, deliberately NOT
+ *    "more than half": at n=2 that is 1-of-2, because 2-of-2 turns any
+ *    single absent member into a deadlocked release gate (council-verified
+ *    2026-08-09). See `quorum.ts` for the resolver a caller applies to its
+ *    own present/total member counts.
  *
  * Parity notes (intentional, documented):
  *   - YAML is parsed with `yaml` (npm) at `version: '1.1'`, matching
@@ -562,6 +576,15 @@ export interface CliCallBudgetConfig {
     readonly warn_at: number;
 }
 
+/**
+ * `"majority"` (default) or a positive integer k — the number of members a
+ * pass needs to conclude (road-to-always-on-orchestration Phase 3.3). See
+ * `quorum.ts::resolveQuorumThreshold` for how a caller turns this into a
+ * concrete threshold against its own total-member count, and the module
+ * docstring rule 9 for why `"majority"` is `ceil(n / 2)`, not `> n / 2`.
+ */
+export type QuorumSetting = 'majority' | number;
+
 export interface CouncilConfig {
     readonly enabled: boolean;
     readonly defaults: DefaultsConfig;
@@ -570,6 +593,7 @@ export interface CouncilConfig {
     readonly advisors: ReadonlyMap<string, AdvisorConfig>;
     readonly consensus_scoring: ConsensusScoringConfig;
     readonly cli_call_budget: CliCallBudgetConfig;
+    readonly quorum: QuorumSetting;
     readonly necessity_classifier: NecessityClassifierConfig;
     readonly model_downgrade: ModelDowngradeConfig;
     readonly debate: DebateConfig;
@@ -578,6 +602,7 @@ export interface CouncilConfig {
     readonly chairman: ChairmanConfig;
     readonly debate_gates: DebateGatesConfig;
     readonly restate: RestateConfig;
+    readonly critic_protocol: CriticProtocol;
     readonly decision_resolution: DecisionResolutionConfig;
     readonly routing: RoutingConfig;
     readonly low_impact: LowImpactConfig;
@@ -796,6 +821,7 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
     const cli_call_budget = _build_cli_call_budget(
         _asDict(_getOr(raw, 'cli_call_budget', {})),
     );
+    const quorum = _build_quorum(_get(raw, 'quorum', 'majority'));
     const necessity_classifier = _build_necessity_classifier(
         _asDict(_getOr(raw, 'necessity_classifier', {})),
     );
@@ -821,6 +847,7 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
         'debate_gates',
     );
     const restate = _build_restate(_asDict(_getOr(raw, 'restate', {})), 'restate');
+    const critic_protocol = _build_critic_protocol(_getOr(raw, 'critic_protocol', 'legacy'));
     const decision_resolution = _build_decision_resolution(
         _asDict(_getOr(raw, 'decision_resolution', {})),
     );
@@ -843,6 +870,7 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
         advisors,
         consensus_scoring: consensus,
         cli_call_budget,
+        quorum,
         necessity_classifier,
         model_downgrade,
         debate,
@@ -851,6 +879,7 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
         chairman,
         debate_gates,
         restate,
+        critic_protocol,
         decision_resolution,
         routing,
         low_impact,
@@ -1115,6 +1144,27 @@ function _build_restate(d: Dict, scope: string): RestateConfig {
     return { enabled: Boolean(enabled) };
 }
 
+/**
+ * `critic_protocol` (road-to-judgment-and-forensic-evidence Phase 2) — which
+ * critic posture adversarial/skeptic review passes use. `legacy` is the
+ * shipped free-hunt skeptic; `load_bearing` is the fixed protocol that must
+ * name the single load-bearing assumption and may return "holds". Default
+ * `legacy` regardless of the A/B outcome (promotion is a separate decision).
+ */
+export type CriticProtocol = 'legacy' | 'load_bearing';
+
+const _VALID_CRITIC_PROTOCOLS: ReadonlySet<string> = new Set(['legacy', 'load_bearing']);
+
+function _build_critic_protocol(v: unknown): CriticProtocol {
+    if (v === undefined || v === null) return 'legacy';
+    if (!(_isStr(v) && _VALID_CRITIC_PROTOCOLS.has(v))) {
+        throw new CouncilConfigError(
+            `\`critic_protocol\`=${_pyRepr(v)} not in ${_sortedListRepr(_VALID_CRITIC_PROTOCOLS)}.`,
+        );
+    }
+    return v as CriticProtocol;
+}
+
 const _VALID_RESOLUTION_MODES: ReadonlySet<string> = new Set([
     'agent',
     'council',
@@ -1427,7 +1477,11 @@ function _build_defaults(d: Dict): DefaultsConfig {
     if (!_isDict(d)) {
         throw new CouncilConfigError('`defaults` must be a mapping.');
     }
-    const mode = _get(d, 'mode', 'api');
+    // road-to-always-on-orchestration Phase 3.1: CLI-first is the shipped
+    // default (was `api`) — see the module docstring rule 2. `manual` and a
+    // pinned `api`/`cli` remain valid overrides at every layer resolve_mode
+    // checks; this only changes what a config that never sets `mode` gets.
+    const mode = _get(d, 'mode', 'auto');
     if (!(_isStr(mode) && _VALID_MODES.has(mode))) {
         throw new CouncilConfigError(
             `defaults.mode=${_pyRepr(mode)} not in ${_sortedListRepr(_VALID_MODES)}.`,
@@ -1630,7 +1684,13 @@ function _build_cost_budget(d: Dict): CostBudgetConfig {
 function _build_member(
     name: string,
     cfg: Dict,
-    default_mode = 'api',
+    // road-to-always-on-orchestration Phase 3.1: kept in sync with
+    // `_build_defaults`'s `auto` default for consistency. The sole call site
+    // (`_build_config`) always passes `defaults.mode` explicitly, so this
+    // parameter default is unreachable on the live path today; it exists so
+    // a future caller that omits the third argument observes the same
+    // doctrine rather than silently reverting to the retired `api` default.
+    default_mode = 'auto',
 ): MemberConfig {
     if (!_VALID_PROVIDERS.has(name)) {
         throw new CouncilConfigError(
@@ -1775,6 +1835,18 @@ function _build_member(
     };
 }
 
+/**
+ * Generous per-provider guard for `mode: cli` / `mode: auto` members
+ * (road-to-always-on-orchestration Phase 3.4). Before this default the map
+ * shipped empty and an unlisted provider ran uncapped — a plan-quota guard
+ * that only existed if the user remembered to opt in. Every known provider
+ * now carries this floor unless a config entry overrides it; sized as a
+ * GUARD against silent quota exhaustion on an always-on pass, not a brake on
+ * normal use (see the template's own worked-example sizing for the
+ * reasoning behind a TIGHTER per-provider number).
+ */
+const _DEFAULT_CLI_CALLS_PER_DAY = 50;
+
 function _build_cli_call_budget(d: Dict): CliCallBudgetConfig {
     if (!_isDict(d)) {
         throw new CouncilConfigError('`cli_call_budget` must be a mapping.');
@@ -1786,6 +1858,9 @@ function _build_cli_call_budget(d: Dict): CliCallBudgetConfig {
         );
     }
     const caps = new Map<string, number>();
+    for (const provider of _VALID_PROVIDERS) {
+        caps.set(provider, _DEFAULT_CLI_CALLS_PER_DAY);
+    }
     for (const [provider, value] of Object.entries(raw_caps)) {
         if (!_VALID_PROVIDERS.has(provider)) {
             throw new CouncilConfigError(
@@ -1817,6 +1892,19 @@ function _build_cli_call_budget(d: Dict): CliCallBudgetConfig {
     return { max_calls_per_day: caps, warn_at };
 }
 
+function _build_quorum(raw: Json): QuorumSetting {
+    if (raw === 'majority') {
+        return 'majority';
+    }
+    if (_isInt(raw) && !_isBool(raw) && (raw as number) >= 1) {
+        return raw as number;
+    }
+    throw new CouncilConfigError(
+        `\`quorum\`=${_pyRepr(raw)} must be 'majority' or an integer >= 1 ` +
+            `(got ${_pyTypeName(raw)}).`,
+    );
+}
+
 function _build_advisor(name: string, cfg: Dict): AdvisorConfig {
     if (!_isDict(cfg)) {
         throw new CouncilConfigError(`advisors.${name}: must be a mapping.`);

package/src/scripts/ai_council/handoff.ts

@@ -0,0 +1,113 @@
+/**
+ * Verdict → handoff envelope (Phase 4.1 of road-to-always-on-orchestration).
+ *
+ * A council pass produces a verdict a human currently has to read and
+ * re-type into whatever executes next. This module is the machine-readable
+ * bridge: an additive `HandoffEnvelope` — decision, rejected alternatives
+ * with reasons, binding constraints — injectable as the dispatched work
+ * order of an implementing subagent, so deliberation output becomes
+ * execution input without a human transcription step.
+ *
+ * ## The honesty constraint
+ *
+ * A council pass has exactly ONE place in this codebase where "the
+ * decision" is a discrete, machine-parsed value rather than free-text prose
+ * a human (or an NLP guess) would have to interpret: the option-level
+ * stance tally (`stance_tally.ts`, opt-in via `ai_council.stance_tally`).
+ * Every other synthesis path — the default template, a chairman's prose
+ * verdict, consensus scoring's qualitative Strong/Findings/Minority
+ * buckets — has no comparable discrete "decision" field to extract from
+ * without parsing prose, which is exactly the kind of confident-looking
+ * fabrication this module refuses to do.
+ *
+ * So: `buildHandoffFromStanceTally` is the ONLY builder this module ships.
+ * No tally (the common case — the flag defaults off) or a tally that split
+ * (no option cleared the consensus threshold) → every field is `null`,
+ * never a guessed decision. A future builder over a different structured
+ * source (a chairman synthesis that itself emits structured fields, a
+ * consensus-scoring extension) is additive — it does not change this one.
+ *
+ * @see docs/contracts/ai-council-config.md § Handoff envelope
+ */
+
+import type { StanceTallyResult } from './stance_tally.js';
+
+/** One option the tally counted but did not conclude on. */
+export interface RejectedAlternative {
+    readonly option: string;
+    /**
+     * A factual, derived-from-the-tally sentence — never invented prose.
+     * States the option's own backer count and weight against the
+     * threshold the winner had to clear, nothing else.
+     */
+    readonly reason: string;
+}
+
+/**
+ * The machine-readable work order a council verdict hands to whatever
+ * executes next. Every field is independently nullable: `null` means "no
+ * structured source existed to populate this field this pass", never a
+ * fabricated placeholder. A consumer checks for `null`, not for an empty
+ * array — an empty array would claim "checked, found none", which this
+ * module never asserts when it never actually checked.
+ */
+export interface HandoffEnvelope {
+    readonly decision: string | null;
+    readonly rejected_alternatives: readonly RejectedAlternative[] | null;
+    /**
+     * Binding constraints the decision carries. No structured source for
+     * this exists anywhere in the current synthesis pipeline (a
+     * dealbreaker count describes objection PRESSURE on an option, not a
+     * named constraint on the winner) — always `null` until one does.
+     */
+    readonly constraints: readonly string[] | null;
+}
+
+/** An envelope with every field `null` — the honest "nothing to hand off" shape. */
+export const EMPTY_HANDOFF: HandoffEnvelope = {
+    decision: null,
+    rejected_alternatives: null,
+    constraints: null,
+};
+
+/** True when every field is `null` — nothing worth rendering or dispatching. */
+export function isEmptyHandoff(h: HandoffEnvelope): boolean {
+    return h.decision === null && h.rejected_alternatives === null && h.constraints === null;
+}
+
+/**
+ * Build a `HandoffEnvelope` from a stance tally, or the honest empty
+ * envelope when there is nothing structured to extract:
+ *
+ * - `tally` is `null` — stance tally never ran this pass (the default,
+ *   opt-in-off case).
+ * - `tally.consensus` is `null` — the tally ran but split; no option
+ *   cleared the two-thirds threshold, so there is no decision to report,
+ *   only a split (which is quorum's/the render's job to surface, not this
+ *   module's).
+ *
+ * Otherwise: `decision` is the winning option's display label;
+ * `rejected_alternatives` lists every OTHER non-abstain option the tally
+ * counted, each with a reason sentence built strictly from that option's
+ * own tally numbers (backer count, weight, the threshold the winner
+ * cleared) — never a narrative guess at WHY members backed it.
+ */
+export function buildHandoffFromStanceTally(tally: StanceTallyResult | null): HandoffEnvelope {
+    if (tally === null || tally.consensus === null) {
+        return EMPTY_HANDOFF;
+    }
+    const winner = tally.consensus;
+    const rejected: RejectedAlternative[] = tally.options
+        .filter((o) => o !== winner)
+        .map((o) => ({
+            option: o.label,
+            reason:
+                `backed by ${o.backers.length} member(s), weight ${o.weight.toFixed(2)} of ` +
+                `${tally.threshold.toFixed(2)} needed to conclude`,
+        }));
+    return {
+        decision: winner.label,
+        rejected_alternatives: rejected.length > 0 ? rejected : null,
+        constraints: null,
+    };
+}

package/src/scripts/ai_council/modes.ts

@@ -33,21 +33,36 @@
  * conflated them. They are now named separately:
  *
  * - **Loader default** — when a config file omits `defaults.mode` entirely,
- *   `config.ts::_build_defaults` fills `api`. Unchanged; this is what every
- *   real config observes, because the loader always populates the key.
+ *   `config.ts::_build_defaults` fills `auto` (road-to-always-on-orchestration
+ *   Phase 3.1 — CLI-first is now the owner-set transport doctrine; before this
+ *   flip the loader default was `api`). This is what every real config
+ *   observes, because the loader always populates the key.
  * - **Built-in fallback** — when NO layer supplies a mode at all (a settings
  *   dict handed straight to the resolver, no config file involved), the answer
  *   is `manual`, below. That is the fail-closed direction the no-silent-spend
  *   Iron Law requires: a caller who supplied no transport preference has not
  *   asked to spend money, so the free transport wins.
+ *
+ * ### Why `DEFAULT_MODE` did NOT flip to `auto` alongside the loader default
+ *
+ * `auto` still resolves to a paying rung (the api fallback) when no CLI is
+ * usable — it is a routing rule, not a free transport. `DEFAULT_MODE` is only
+ * reached by a caller that bypasses the config loader entirely (no
+ * `.ai-council.yml`, a hand-built settings dict handed straight to
+ * `resolve_mode`/`resolve_modes`). Flipping it to `auto` would let such a
+ * caller spend money on a config that never asked for `auto` in the first
+ * place — the same no-silent-spend violation the built-in fallback exists to
+ * prevent. Every real, file-backed config always has `defaults.mode`
+ * populated by the loader (now `auto`), so `DEFAULT_MODE` is never consulted
+ * on that path — verified in modes.test.ts and config.test.ts.
  */
 
 export const VALID_MODES: ReadonlySet<string> = new Set(['api', 'manual', 'cli', 'auto']);
 
 /**
  * Built-in fallback when no layer supplies a mode. `manual` — free, no key,
- * no spend. NOT the same as the loader's `defaults.mode` default (`api`); see
- * the module header.
+ * no spend. NOT the same as the loader's `defaults.mode` default (`auto`
+ * since road-to-always-on-orchestration Phase 3.1); see the module header.
  */
 export const DEFAULT_MODE = 'manual';