@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/ai_council/blind_review.ts

@@ -0,0 +1,212 @@
+/**
+ * Council Blind Review — Phase 1 protocol diff (road-to-council-blind-review).
+ *
+ * Three flag-gated, default-off deliberation-protocol experiments, all
+ * subordinate to the existing Iron Law of Neutrality (`docs/contracts/
+ * ai-council-config.md` § "Normative behaviour — migrated verbatim") — this
+ * module never touches that text, it only adds optional layers on top:
+ *
+ * - Ü1 (blind synthesis) — `deterministic_shuffle_indices` + `build_blind_labels`
+ *   reuse the EXISTING `consensus.anonymize_responses` seam to strip provider
+ *   identity from the chairman transcript, seeded deterministically from the
+ *   question text (no `Math.random`, no `Date`). `render_deanonymization_block`
+ *   restores the mapping AFTER the verdict — blind is only at decision time,
+ *   never the archive.
+ * - Ü2 (stance assignment) — `STANCE_DEFS` + `assign_stances` rotate five
+ *   orthogonal examine-from-perspective-Y prompts deterministically over the
+ *   config-ordered member list (never "recommend X" — that would breach the
+ *   neutrality contract). The `outsider` seat is the one stance the caller
+ *   (orchestrator `consult()`) ablates project context for.
+ * - Ü3 (chairman fields) — `CHAIRMAN_FIELDS_ADDENDUM` / `with_chairman_fields`
+ *   append two mandatory trailing sections to the synthesis template.
+ *
+ * All four exports are inert unless a CLI flag opts in (`council_cli.ts`
+ * `--chairman` / `--blind-chairman` / `--stances` / `--chairman-fields`).
+ */
+import { createHash } from 'node:crypto';
+
+import { anonymize_responses } from './consensus.js';
+
+type Dict = Record<string, unknown>;
+
+// ── deterministic seeding (sha256 of the question text — no Math.random, no Date) ──
+
+function _sha256_hex(s: string): string {
+    return createHash('sha256').update(s, 'utf-8').digest('hex');
+}
+
+/**
+ * Seeded permutation of `0..n-1`, deterministic in `seed`. Decorate-sort:
+ * each index gets `sha256(seed + NUL + index)` as its sort key, ascending.
+ */
+export function deterministic_shuffle_indices(seed: string, n: number): number[] {
+    const keyed = Array.from({ length: n }, (_, i) => ({ i, key: _sha256_hex(`${seed}\0${i}`) }));
+    keyed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    return keyed.map((k) => k.i);
+}
+
+// ── Ü1 — blind chairman transcript (reuses consensus.anonymize_responses) ──
+
+/**
+ * Build a blinded chairman transcript from `[source, text]` pairs (source =
+ * canonical `provider:model`). The pair ORDER fed to `anonymize_responses` is
+ * a deterministic shuffle seeded by `question_text` — which pair becomes
+ * `Response-A` is not simply input order, so position alone leaks nothing.
+ *
+ * Returns the rendered transcript (label-headed blocks) AND the
+ * `label -> provider:model` map the caller must keep for post-verdict
+ * de-anonymization (never fed back into the prompt).
+ */
+export function build_blind_labels(
+    question_text: string,
+    pairs: ReadonlyArray<readonly [string, string]>,
+): { transcript: string; label_to_source: Map<string, string> } {
+    const order = deterministic_shuffle_indices(question_text, pairs.length);
+    const shuffled = order.map((i) => pairs[i] as readonly [string, string]);
+    const [anon_text, label_to_source] = anonymize_responses(shuffled, { persona_labels: null });
+    const transcript = Array.from(anon_text.entries())
+        .map(([label, text]) => `## ${label}\n\n${text}`)
+        .join('\n\n---\n\n');
+    return { transcript, label_to_source };
+}
+
+/**
+ * Render the post-verdict de-anonymization map. `heading` lets callers use
+ * the member-chairman heading (`### De-anonymization (post-verdict)`) or the
+ * host-render heading (`### De-anonymization map`) — the two Phase-1 call
+ * sites use distinct wording by design.
+ */
+export function render_deanonymization_block(heading: string, label_to_source: ReadonlyMap<string, string>): string {
+    const lines = Array.from(label_to_source.entries()).map(([label, source]) => {
+        const idx = source.indexOf(':');
+        const provider = idx === -1 ? source : source.slice(0, idx);
+        const model = idx === -1 ? '' : source.slice(idx + 1);
+        return `- ${label} → ${provider} · ${model}`;
+    });
+    return `${heading}\n\n${lines.join('\n')}`;
+}
+
+// ── Ü2 — orthogonal stance assignment per seat ──
+
+export interface StanceDef {
+    readonly name: string;
+    readonly prompt: string;
+}
+
+const _EXAMINE = 'Examine the question from the perspective of';
+
+/**
+ * Five orthogonal stances, UNDER the existing neutrality contract: every
+ * prompt reads "examine from perspective Y", never "recommend X" — a stance
+ * frames the lens, it never picks the answer.
+ */
+export const STANCE_DEFS: readonly StanceDef[] = [
+    {
+        name: 'skeptic',
+        prompt:
+            `${_EXAMINE} a skeptic: name the weakest assumption underneath the ` +
+            `artefact and the failure mode most likely to be overlooked.`,
+    },
+    {
+        name: 'first-principles',
+        prompt:
+            `${_EXAMINE} first principles: decompose the artefact into its most ` +
+            `basic true statements and reason upward from there, setting existing ` +
+            `conventions aside.`,
+    },
+    {
+        name: 'opportunity',
+        prompt:
+            `${_EXAMINE} opportunity: surface the upside case and the option ` +
+            `value a narrower reading of the artefact might miss.`,
+    },
+    {
+        name: 'outsider',
+        prompt:
+            `${_EXAMINE} an outsider unfamiliar with this project's history and ` +
+            `conventions: work only from the artefact in front of you.`,
+    },
+    {
+        name: 'operator',
+        prompt:
+            `${_EXAMINE} an operator who has to run the resulting decision day to ` +
+            `day: surface the operational cost and the maintenance burden.`,
+    },
+] as const;
+
+/** The one seat whose deliberation prompt drops `project_context` (Ü2). */
+export const OUTSIDER_STANCE_NAME = 'outsider';
+
+/** `sha256(question_text)` first byte, mod `STANCE_DEFS.length` — the rotation offset. */
+export function stance_offset(question_text: string): number {
+    const hex = _sha256_hex(question_text);
+    return parseInt(hex.slice(0, 2), 16) % STANCE_DEFS.length;
+}
+
+/**
+ * Member `i` (in the given config order) gets
+ * `STANCE_DEFS[(offset + i) mod 5]`, `offset` deterministic from
+ * `question_text`. Same question → same assignment; different question →
+ * (usually) a different rotation offset.
+ */
+export function assign_stances(member_names: readonly string[], question_text: string): Map<string, StanceDef> {
+    const offset = stance_offset(question_text);
+    const out = new Map<string, StanceDef>();
+    member_names.forEach((name, i) => {
+        out.set(name, STANCE_DEFS[(offset + i) % STANCE_DEFS.length] as StanceDef);
+    });
+    return out;
+}
+
+// ── Ü3 — mandatory chairman fields ──
+
+export const CHAIRMAN_FIELDS_ADDENDUM = `## Collective blind spot
+What did ALL members miss — non-obvious, specific.
+
+## One-line verdict
+One sentence, and the single strongest reason.`;
+
+/** Append the two Ü3 sections to a synthesis template (host or member-chairman). */
+export function with_chairman_fields(template: string): string {
+    return template ? `${template}\n\n${CHAIRMAN_FIELDS_ADDENDUM}` : CHAIRMAN_FIELDS_ADDENDUM;
+}
+
+// ── `--chairman <host|auto|member:NAME>` override parsing ──
+
+export interface ChairmanOverride {
+    readonly mode: 'host' | 'auto' | 'member';
+    readonly member: string | null;
+}
+
+/** Parse the `--chairman` flag value. `null` input → `null` (no override). Throws on malformed input. */
+export function parse_chairman_override(raw: string | null): ChairmanOverride | null {
+    if (raw === null) {
+        return null;
+    }
+    if (raw === 'host' || raw === 'auto') {
+        return { mode: raw, member: null };
+    }
+    if (raw.startsWith('member:')) {
+        const member = raw.slice('member:'.length).trim();
+        if (!member) {
+            throw new Error(`--chairman member: form requires a name, got ${JSON.stringify(raw)}.`);
+        }
+        return { mode: 'member', member };
+    }
+    throw new Error(`--chairman expects host|auto|member:NAME, got ${JSON.stringify(raw)}.`);
+}
+
+/** Apply a parsed `--chairman` override to a raw `ai_council` config dict — a pure override, no config write. */
+export function apply_chairman_override(ai_cfg: Dict, override: ChairmanOverride | null): Dict {
+    if (override === null) {
+        return ai_cfg;
+    }
+    const existing = (ai_cfg['chairman'] as Dict) || {};
+    const next: Dict = { ...existing, mode: override.mode };
+    if (override.mode === 'member') {
+        next['member'] = override.member;
+    } else {
+        delete next['member'];
+    }
+    return { ...ai_cfg, chairman: next };
+}

package/src/scripts/ai_council/budget_guard.ts

@@ -12,9 +12,13 @@
  * same permission discipline as the API keys). The legacy
  * `~/.config/agent-config/council-spend.jsonl` is read as a fallback.
  *
- * Contract (verbatim from the Python module):
+ * Contract (verbatim from the Python module, plus the additive TS-only
+ * cache extension below):
  * - The ledger is **append-only**. Each line is `{"ts": ISO-8601 UTC,
- *   "usd": float, "provider": str, "model": str}`.
+ *   "usd": float, "provider": str, "model": str}`, optionally followed by
+ *   `"cache_read_input_tokens": int, "cache_creation_input_tokens": int,
+ *   "cache_ttl": "5m"|"1h"` when the caller reports cache activity — absent
+ *   on every entry recorded before this extension shipped.
  * - `today_spend_usd()` sums entries within the last 24h from "now".
  * - `would_exceed(limit_usd, next_call_usd)` returns true iff the next call
  *   would push the rolling window past the limit.
@@ -75,6 +79,12 @@ export interface SpendEntry {
     usd: number;
     provider: string;
     model: string;
+    // Prompt-cache accounting (additive — absent on entries recorded before
+    // this field existed, and on calls with no cache activity to report).
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+    /** Write-multiplier TTL tier in effect when this entry was recorded. */
+    cache_ttl?: '5m' | '1h';
 }
 
 function _nowUtcMs(): number {
@@ -259,14 +269,37 @@ function _pyJsonString(s: string): string {
  * `json.dumps({"ts": ts, "usd": round(usd, 6), "provider": provider,
  * "model": model})` does: default separators (`", "`, `": "`), insertion
  * order (NOT sorted). `usd` is a float (`pyFloatRepr`); the rest are strings.
+ *
+ * The three cache params are appended only when the CALLER passed them
+ * (`!== undefined`) — a call with none of the three reproduces the original
+ * 4-key line byte-for-byte, which is what keeps every pre-existing caller
+ * (and the python3 byte-parity test, which has no Python-side cache
+ * counterpart) unaffected by this additive extension.
  */
-function _dumpEntry(ts: string, usd: number, provider: string, model: string): string {
-    return (
-        `{${_pyJsonString('ts')}: ${_pyJsonString(ts)}, ` +
+function _dumpEntry(
+    ts: string,
+    usd: number,
+    provider: string,
+    model: string,
+    cacheRead?: number,
+    cacheWrite?: number,
+    cacheTtl?: '5m' | '1h',
+): string {
+    let body =
+        `${_pyJsonString('ts')}: ${_pyJsonString(ts)}, ` +
         `${_pyJsonString('usd')}: ${pyFloatRepr(usd)}, ` +
         `${_pyJsonString('provider')}: ${_pyJsonString(provider)}, ` +
-        `${_pyJsonString('model')}: ${_pyJsonString(model)}}`
-    );
+        `${_pyJsonString('model')}: ${_pyJsonString(model)}`;
+    if (cacheRead !== undefined) {
+        body += `, ${_pyJsonString('cache_read_input_tokens')}: ${Math.trunc(cacheRead)}`;
+    }
+    if (cacheWrite !== undefined) {
+        body += `, ${_pyJsonString('cache_creation_input_tokens')}: ${Math.trunc(cacheWrite)}`;
+    }
+    if (cacheTtl !== undefined) {
+        body += `, ${_pyJsonString('cache_ttl')}: ${_pyJsonString(cacheTtl)}`;
+    }
+    return `{${body}}`;
 }
 
 /** Coerce a parsed JSON value to a float like Python's `float(obj.get(...))`. */
@@ -366,16 +399,46 @@ export function read_entries(p: string | null = null): SpendEntry[] {
         if (usd === null) {
             continue;
         }
-        out.push({
+        const entry: SpendEntry = {
             ts,
             usd,
             provider: _toStr(record.provider, ''),
             model: _toStr(record.model, ''),
-        });
+        };
+        // exactOptionalPropertyTypes forbids `key: undefined` on an object
+        // literal — assign conditionally so a legacy (or cache-less) line
+        // leaves these keys absent rather than present-but-undefined.
+        const cacheRead = _toOptionalNonNegInt(record.cache_read_input_tokens);
+        if (cacheRead !== undefined) {
+            entry.cache_read_input_tokens = cacheRead;
+        }
+        const cacheWrite = _toOptionalNonNegInt(record.cache_creation_input_tokens);
+        if (cacheWrite !== undefined) {
+            entry.cache_creation_input_tokens = cacheWrite;
+        }
+        const cacheTtl = _toOptionalTtl(record.cache_ttl);
+        if (cacheTtl !== undefined) {
+            entry.cache_ttl = cacheTtl;
+        }
+        out.push(entry);
     }
     return out;
 }
 
+/** A non-negative finite number, or `undefined` when absent/malformed. */
+function _toOptionalNonNegInt(v: unknown): number | undefined {
+    if (v === undefined || v === null) {
+        return undefined;
+    }
+    const n = _toFloat(v);
+    return n === null || n < 0 ? undefined : n;
+}
+
+/** `'5m' | '1h'`, or `undefined` for anything else (including absent). */
+function _toOptionalTtl(v: unknown): '5m' | '1h' | undefined {
+    return v === '5m' || v === '1h' ? v : undefined;
+}
+
 /** `str(obj.get("ts", ""))` — the timestamp is read as a string before parsing. */
 function _rawStr(v: unknown): string {
     if (v === undefined) {
@@ -424,7 +487,15 @@ export function record_spend(
     usd: number,
     provider: string,
     model: string,
-    options: { path?: string | null; now?: number | null } = {},
+    options: {
+        path?: string | null;
+        now?: number | null;
+        // Additive prompt-cache accounting (Step B). Omitting all three
+        // reproduces the original 4-field ledger line exactly.
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
+        cache_ttl?: '5m' | '1h';
+    } = {},
 ): boolean {
     if (usd <= 0) {
         return true; // zero-cost calls (manual mode) skip the ledger
@@ -435,7 +506,15 @@ export function record_spend(
     }
     const nowMs = options.now ?? _nowUtcMs();
     const ts = nowUtcIso(nowMs);
-    const entry = `${_dumpEntry(ts, _pyRound6(usd), provider, model)}\n`;
+    const entry = `${_dumpEntry(
+        ts,
+        _pyRound6(usd),
+        provider,
+        model,
+        options.cache_read_input_tokens,
+        options.cache_creation_input_tokens,
+        options.cache_ttl,
+    )}\n`;
     try {
         fs.appendFileSync(p, entry, { encoding: 'utf-8' });
     } catch (exc) {

package/src/scripts/ai_council/bundler.ts

@@ -263,7 +263,7 @@ export function bundle_diff_with_context(
     }
 
     const root = cwd ? cwd : '.';
-    const seen = new Set<string>(); // `${file}${signature_line}`
+    const seen = new Set<string>(); // `${file}\0${signature_line}`
     // Preserve insertion order of first-seen files (Python dict order).
     const byFile = new Map<string, Array<[number, string]>>();
 
@@ -279,7 +279,7 @@ export function bundle_diff_with_context(
         if (sig === null) {
             continue;
         }
-        const key = `${filePath}${sig[0]}`;
+        const key = `${filePath}\0${sig[0]}`;
         if (seen.has(key)) {
             continue;
         }

package/src/scripts/ai_council/clients.ts

@@ -109,7 +109,7 @@ export const UNLIMITED_TOKENS_FALLBACK = 16384;
 // OpenAI reasoning models (o1, o3, o4 families) reject `max_tokens` and the
 // `system` role; they require `max_completion_tokens` and accept only `user`
 // (and `developer`) messages.
-const _REASONING_PREFIXES: readonly string[] = ['o1', 'o3', 'o4'];
+const _REASONING_PREFIXES: readonly string[] = ['o1', 'o3', 'o4', 'gpt-5'];
 
 export function _is_reasoning_model(model: string): boolean {
     const name = model.toLowerCase();
@@ -132,6 +132,38 @@ export class CliClientError extends Error {
     }
 }
 
+/**
+ * Anthropic cache_control TTL tiers (road-to-cache-economy Phase 4).
+ * `'5m'` is the permanent default — see `prompt_cache.ttl` in
+ * `docs/contracts/ai-council-config.md` for the falsification condition
+ * that would be required before `'1h'` is ever enabled anywhere.
+ */
+export type PromptCacheTtl = '5m' | '1h';
+export const DEFAULT_PROMPT_CACHE_TTL: PromptCacheTtl = '5m';
+
+/**
+ * Anthropic's cache_control ordering rule: within one request, a 1-hour
+ * breakpoint must be positioned before any 5-minute breakpoint. This
+ * client always applies the SAME configured ttl to both of its
+ * breakpoints (see `_ask_impl`), so the two are never mixed in
+ * practice — this guard exists so a future per-breakpoint ttl never
+ * regresses that invariant silently.
+ */
+export function assertCacheBreakpointOrder(ttls: readonly PromptCacheTtl[]): void {
+    let sawFiveMinute = false;
+    for (const ttl of ttls) {
+        if (ttl === '5m') {
+            sawFiveMinute = true;
+        } else if (ttl === '1h' && sawFiveMinute) {
+            throw new TypeError(
+                `cache_control breakpoint order violation: a '1h' breakpoint ` +
+                    `followed a '5m' one (${JSON.stringify(ttls)}) — Anthropic ` +
+                    `requires every 1h breakpoint before any 5m breakpoint.`,
+            );
+        }
+    }
+}
+
 /** Normalised output from a single council member (dataclass `CouncilResponse`). */
 export class CouncilResponse {
     provider: string;
@@ -319,6 +351,10 @@ interface ApiClientOptions {
     // unless it asks — so a single call never pays the ~1.25× write premium by
     // surprise. Only AnthropicClient consumes this; other providers ignore it.
     enable_prompt_cache?: boolean | undefined;
+    // TTL tier for both cache_control breakpoints (road-to-cache-economy
+    // Phase 4). Default '5m' when omitted — see `DEFAULT_PROMPT_CACHE_TTL`.
+    // Only meaningful when `enable_prompt_cache` is true.
+    prompt_cache_ttl?: PromptCacheTtl | undefined;
 }
 
 /** Shared ctor-options shape for the CLI clients. */
@@ -380,11 +416,17 @@ export class AnthropicClient extends ExternalAIClient {
     // ApiClientOptions.enable_prompt_cache. Prevents silent activation (and the
     // write premium) for callers that don't benefit from a shared-prefix cache.
     private _enablePromptCache: boolean;
+    // TTL applied to BOTH cache_control breakpoints below. '5m' (the
+    // default) is never serialised on the wire — omitting `ttl` is the
+    // Anthropic API's own 5-minute default, so the default case stays
+    // byte-identical to the pre-Phase-4 request shape.
+    private _promptCacheTtl: PromptCacheTtl;
 
     constructor(opts: ApiClientOptions = {}) {
         super();
         this.model = opts.model ?? DEFAULT_ANTHROPIC_MODEL;
         this._enablePromptCache = opts.enable_prompt_cache ?? false;
+        this._promptCacheTtl = opts.prompt_cache_ttl ?? DEFAULT_PROMPT_CACHE_TTL;
         if (opts.client !== undefined && opts.client !== null) {
             this._client = opts.client;
             return;
@@ -455,6 +497,18 @@ export class AnthropicClient extends ExternalAIClient {
             // base_system_prompt alone is often below the model's min cacheable
             // prefix and would never cache solo — the artefact block is where
             // the real saving lands. Two breakpoints (≤ the 4 allowed).
+            //
+            // Both breakpoints share the SAME configured ttl (road-to-
+            // cache-economy Phase 4) — they never diverge, so the API's
+            // "1h before 5m" ordering rule can never be violated here; the
+            // assertion below is a regression guard, not a live branch.
+            // Default '5m' omits the `ttl` field entirely (Anthropic's own
+            // default), so an unconfigured member's wire shape is unchanged
+            // from before Phase 4.
+            const ttl = this._promptCacheTtl;
+            assertCacheBreakpointOrder([ttl, ttl]);
+            const cache_control: Record<string, unknown> =
+                ttl === '1h' ? { type: 'ephemeral', ttl: '1h' } : { type: 'ephemeral' };
             const kwargs: Record<string, unknown> = this._enablePromptCache
                 ? {
                       model: this.model,
@@ -463,7 +517,7 @@ export class AnthropicClient extends ExternalAIClient {
                           {
                               type: 'text',
                               text: system_prompt,
-                              cache_control: { type: 'ephemeral' },
+                              cache_control,
                           },
                       ],
                       messages: [
@@ -473,11 +527,13 @@ export class AnthropicClient extends ExternalAIClient {
                               // volatile suffix (round critiques) rides after
                               // it, so round N+1 reads the cached prefix
                               // instead of re-writing it (A3 read unlock).
+                              // The volatile suffix NEVER carries cache_control
+                              // — the ttl reaches only the stable prefix.
                               content: [
                                   {
                                       type: 'text',
                                       text: stable_prompt,
-                                      cache_control: { type: 'ephemeral' },
+                                      cache_control,
                                   },
                                   ...(volatile_suffix
                                       ? [{ type: 'text', text: volatile_suffix }]

package/src/scripts/ai_council/config.ts

@@ -362,6 +362,9 @@ export interface CostBudgetConfig {
     readonly max_output_tokens: number;
     readonly max_calls: number;
     readonly max_total_usd: number;
+    /** Rolling 24h cap. 0 disables it — and disabling it also disables the spend
+     * ledger, since the orchestrator only appends an entry while a cap is live. */
+    readonly daily_limit_usd: number;
 }
 
 export interface MemberConfig {
@@ -380,6 +383,13 @@ export interface MemberConfig {
      * back to deterministic config order.
      */
     readonly tier: number | null;
+    /**
+     * Cache-control TTL tier for this member's Anthropic breakpoints
+     * (road-to-cache-economy Phase 4). `'5m'` is the permanent default —
+     * see `prompt_cache.ttl` in `docs/contracts/ai-council-config.md` for
+     * the falsification condition that gates ever enabling `'1h'`.
+     */
+    readonly prompt_cache_ttl: '5m' | '1h';
 }
 
 /**
@@ -915,10 +925,15 @@ function _build_model_downgrade(d: Dict): ModelDowngradeConfig {
     if (!_isBool(enabled)) {
         throw new CouncilConfigError('`model_downgrade.enabled` must be a bool.');
     }
-    // A3 (2026-07-20): auto_apply default flipped to TRUE — auto-downgrade is
-    // the default and `auto_apply: false` (or `enabled: false`) is the opt-out.
-    // The cache-coupling gate in council_cli._size_fit_gate keeps it honest.
-    const auto_apply = _get(d, 'auto_apply', true);
+    // 2026-07-28 (road-to-feedback-9.8.0-followups Phase 3): auto_apply
+    // default downgraded back to FALSE (suggest, don't silently apply). The
+    // A3 flip to TRUE (2026-07-20) shipped without a paired quality
+    // measurement and was the only default-ON surface without one (R7
+    // watch-item); until a paired eval measures downgraded-member council
+    // quality, the downgrade surfaces as a suggestion the caller applies
+    // explicitly. Revisit: a paired eval (full-tier vs downgraded, blind
+    // judge) showing held quality re-flips this to true.
+    const auto_apply = _get(d, 'auto_apply', false);
     if (!_isBool(auto_apply)) {
         throw new CouncilConfigError('`model_downgrade.auto_apply` must be a bool.');
     }
@@ -1331,8 +1346,9 @@ function _build_lens_overrides(d: Dict): LensOverridesConfig {
                     `\`lenses.${lens_name}.model_downgrade.enabled\` must be a bool.`,
                 );
             }
-            // Lens overrides inherit the A3 auto-by-default posture.
-            const md_auto = _get(md_block, 'auto_apply', true);
+            // Lens overrides inherit the suggest-by-default posture
+            // (2026-07-28 downgrade of the unmeasured A3 auto-default).
+            const md_auto = _get(md_block, 'auto_apply', false);
             if (!_isBool(md_auto)) {
                 throw new CouncilConfigError(
                     `\`lenses.${lens_name}.model_downgrade.auto_apply\` must be a bool.`,
@@ -1585,12 +1601,14 @@ function _build_cost_budget(d: Dict): CostBudgetConfig {
         max_output_tokens: _pyInt(_get(d, 'max_output_tokens', 200_000)),
         max_calls: _pyInt(_get(d, 'max_calls', 50)),
         max_total_usd: _pyFloat(_get(d, 'max_total_usd', 20.0)),
+        daily_limit_usd: _pyFloat(_get(d, 'daily_limit_usd', 0.0)),
     };
     const fields: Array<[keyof CostBudgetConfig, boolean]> = [
         ['max_input_tokens', false],
         ['max_output_tokens', false],
         ['max_calls', false],
         ['max_total_usd', true],
+        ['daily_limit_usd', true],
     ];
     for (const [fname, isFloat] of fields) {
         const val = cb[fname];
@@ -1710,6 +1728,31 @@ function _build_member(
         }
         tier = tier_raw;
     }
+    // road-to-cache-economy Phase 4: `prompt_cache` stays accepted as a
+    // bare bool (the pre-existing, undocumented enable/disable form —
+    // untouched here) OR as a mapping carrying `ttl`. '5m' is the
+    // permanent default; see docs/contracts/ai-council-config.md
+    // § Prompt cache TTL for the falsification condition on '1h'.
+    const prompt_cache_raw = _get(cfg, 'prompt_cache', null);
+    let prompt_cache_ttl: '5m' | '1h' = '5m';
+    if (prompt_cache_raw !== null && prompt_cache_raw !== undefined && !_isBool(prompt_cache_raw)) {
+        if (!_isDict(prompt_cache_raw)) {
+            throw new CouncilConfigError(
+                `members.${name}.prompt_cache must be a bool or a mapping ` +
+                    `(got ${_pyTypeName(prompt_cache_raw)}).`,
+            );
+        }
+        const ttl_raw = _get(prompt_cache_raw, 'ttl', '5m');
+        if (ttl_raw !== '5m' && ttl_raw !== '1h') {
+            throw new CouncilConfigError(
+                `members.${name}.prompt_cache.ttl must be '5m' or '1h' (got ` +
+                    `${_pyRepr(ttl_raw)}). '5m' remains the default until a ` +
+                    `pre-registered 30-debate gap sample clears 40% at ` +
+                    `>=5-minute inter-round gaps.`,
+            );
+        }
+        prompt_cache_ttl = ttl_raw;
+    }
     return {
         name,
         enabled: member_enabled,
@@ -1720,6 +1763,7 @@ function _build_member(
         model_ladder: ladder,
         participate_low_impact: participate_raw,
         tier,
+        prompt_cache_ttl,
     };
 }