instar 1.3.468 → 1.3.469

package/dist/core/ModelSwapService.js

@@ -0,0 +1,266 @@
+/**
+ * ModelSwapService — §5.3 of docs/specs/FABLE-MODEL-ESCALATION-SPEC.md.
+ *
+ * The narrow, server-side mid-session model swap (Trigger #1 only). The
+ * reconciler hook only SIGNALS — this service is the single authority that
+ * performs a swap, and it verifies every swap with an independent oracle.
+ *
+ * Contract (each clause spec-cited):
+ *  - `:name` resolves by EXACT match against the live session registry —
+ *    never globbed, substring-matched, or concatenated into the tmux target
+ *    (round-2 Security-N1). The only string ever sent to the pane is the
+ *    server-derived `/model <validated-id>`.
+ *  - The model id is derived server-side via the §5.1 resolver — NEVER
+ *    accepted from the caller (Sec-F5).
+ *  - Refuses protected sessions (authorization boundary) and sessions that
+ *    are not idle-with-empty-input (round-2 Security-F6 live-input
+ *    collision window).
+ *  - Honors `enabled:false` / `dryRun:true`; dryRun evaluates every gate
+ *    but acquires nothing and injects nothing.
+ *  - Injects via tmux `send-keys -l --` + a SEPARATE Enter (SessionManager
+ *    .sendInput — the same hardened primitive the input route uses).
+ *  - **Canary read-back via an oracle independent of the Session.model
+ *    field this swap would write** (round-3 Integration-NEW-1): the pane's
+ *    own acknowledgment of the /model command, parsed to exclude the echo
+ *    of our injected input. Only on a confirmed match is Session.model
+ *    updated. Unconfirmed ⇒ Session.model untouched, behaviourally default,
+ *    ONE Attention item (round-1 Adversarial-H5 / Lessons-C3).
+ *  - **Accounting fails toward counting** (round-2 Adversarial-NEW-2): the
+ *    escalation is counted at injection, before the canary, once per
+ *    (instance, transition) episode.
+ *  - Server-side dwell guard: never swaps the same session twice within
+ *    `minTierDwellMs` (§5.5 hysteresis backstop; suppressed flaps audited).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { IDLE_PROMPT_PATTERNS } from './SessionManager.js';
+import { SWAP_CAPABILITY, escalatedModelIds, resolveTierModel, } from './ModelTierEscalation.js';
+/**
+ * Does the pane tail show a prompt-ready idle state WITH an empty input
+ * line? Fail-closed: anything ambiguous returns false and the swap is
+ * refused as retryable (round-2 Security-F6).
+ */
+export function paneIdleWithEmptyInput(tail) {
+    if (!tail)
+        return false;
+    const idle = IDLE_PROMPT_PATTERNS.some(p => tail.includes(p));
+    if (!idle)
+        return false;
+    // Empty input line: a prompt row with nothing typed after the prompt char —
+    // bare, or showing only the CLI's own placeholder hint (`Try "…`). The REAL
+    // CLI renders the prompt as `❯` (U+276F); synthetic/test panes and older
+    // renders use ASCII `>` — accept both (live-canary finding, 2026-06-09:
+    // the ASCII-only match made idle detection fail against every real
+    // session, refusing all swaps as not-idle).
+    const lines = tail.split('\n');
+    return lines.some(line => {
+        const stripped = line.replace(/[│|]/g, ' ').replace(/❯/g, '>').trim();
+        if (stripped === '>')
+            return true;
+        if (/^>\s*Try "/.test(stripped))
+            return true;
+        return false;
+    });
+}
+/**
+ * Independent-oracle parse (§5.3 canary): does the pane acknowledge that
+ * the model is now `modelId`, on a line that is NOT the echo of our own
+ * injected `/model …` input? Conservative by design: an unrecognized format
+ * reads as NOT confirmed (the spec's honest-degrade direction).
+ *
+ * The REAL CLI acks with the model's DISPLAY NAME, not the id (live-canary
+ * finding, 2026-06-09): `/model claude-fable-5` → "Set model to Fable 5 and
+ * saved as your default for new sessions". We accept the exact id OR the
+ * display form derived from the id (closed-enum ids only ever reach here,
+ * so the derivation is over a known, validated vocabulary): family token
+ * capitalized + up to two leading version components dot-joined —
+ * claude-fable-5 → "Fable 5", claude-opus-4-8 → "Opus 4.8".
+ */
+export function paneConfirmsModel(tail, modelId) {
+    if (!tail)
+        return false;
+    const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const alternatives = [escapeRe(modelId)];
+    const m = modelId.match(/^(?:claude-)?([a-z]+)((?:-[0-9]+)*)/i);
+    if (m) {
+        const family = m[1][0].toUpperCase() + m[1].slice(1).toLowerCase();
+        const version = m[2].split('-').filter(Boolean).slice(0, 2).join('.');
+        alternatives.push(escapeRe(version ? `${family} ${version}` : family));
+    }
+    const ack = new RegExp(`set model to[^\\n]*\\b(?:${alternatives.join('|')})\\b`, 'i');
+    return tail.split('\n').some(line => {
+        if (line.includes('/model'))
+            return false; // echo of our injected input
+        return ack.test(line);
+    });
+}
+export class ModelSwapService {
+    deps;
+    auditPath;
+    now;
+    wait;
+    /** In-memory per-session last-swap timestamps (dwell backstop). Reset on
+     *  restart — the safe direction (a restart may swap immediately). */
+    lastSwapAt = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.auditPath = path.join(deps.stateDir, 'state', 'model-tier-escalation', 'audit.jsonl');
+        this.now = deps.now ?? (() => Date.now());
+        this.wait = deps.wait ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    }
+    /**
+     * Swap `name`'s session to `tier`. Body-validated upstream; this method
+     * re-validates everything it relies on (defense in depth).
+     */
+    async swap(name, tier) {
+        const cfg = this.deps.getConfig();
+        // Exact-match registry lookup — by Session.name first, then by the
+        // registry's own tmuxSession value. Never partial, never globbed.
+        const running = this.deps.sessions.listRunningSessions();
+        const session = running.find(s => s.name === name) ?? running.find(s => s.tmuxSession === name);
+        if (!session) {
+            return this.refuse(name, tier, 'unknown-session');
+        }
+        const framework = (session.framework ?? 'claude-code');
+        if (SWAP_CAPABILITY[framework] !== 'mid-session') {
+            // §5.6 — declared capability honored by code, not prose.
+            return this.refuse(session.name, tier, 'launch-time-only-framework');
+        }
+        if (this.deps.protectedSessions().includes(session.tmuxSession)) {
+            return this.refuse(session.name, tier, 'protected-session');
+        }
+        // Server-derived id — the caller can only ever name a TIER.
+        const targetId = resolveTierModel(framework, tier, cfg, e => this.audit({ type: 'resolve-rejected', ...e }));
+        if (targetId == null) {
+            // Back-compat contract: no model configured ⇒ zero swaps, not an error.
+            this.audit({ type: 'noop', session: session.name, tier, reason: 'no-model-configured' });
+            return { status: 'noop', reason: 'no-model-configured' };
+        }
+        if (session.model === targetId) {
+            return { status: 'noop', reason: 'already-on-tier', model: targetId, confirmed: true };
+        }
+        // RESCUE DE-ESCALATION (Phase-5 review finding): a `tier:'default'` swap
+        // for a session CURRENTLY on an escalated id bypasses the enabled/dryRun
+        // gates. Those flags are the rollback levers — if they also refused the
+        // swap-back, an escalated session would be stranded on the ultra model in
+        // exactly the state the operator is trying to leave (the one refusal
+        // whose failure direction is MORE spend, inverting §3.5). Strictly
+        // cost-reducing, mirrors the governor exemption below; idle/protected/
+        // dwell/canary gates all still apply. Fleet installs stay inert: their
+        // sessions are never on an escalated id, so disabled still refuses.
+        const isRescueDeescalation = tier === 'default' && session.model != null && escalatedModelIds(cfg).has(session.model);
+        if (!cfg.enabled && !isRescueDeescalation) {
+            return this.refuse(session.name, tier, 'disabled');
+        }
+        // Dwell backstop (§5.5): never swap the same session twice within
+        // minTierDwellMs. Suppressed flaps are audited.
+        const last = this.lastSwapAt.get(session.id);
+        if (last != null && this.now() - last < cfg.costGuards.minTierDwellMs) {
+            this.audit({ type: 'flap-suppressed', session: session.name, tier, sinceLastSwapMs: this.now() - last });
+            return { status: 'refused', reason: 'dwell' };
+        }
+        // Idle + empty input line (round-2 Security-F6) — fail closed.
+        const tail = this.deps.sessions.captureMeaningfulTail(session.tmuxSession, 8);
+        if (!paneIdleWithEmptyInput(tail)) {
+            return this.refuse(session.name, tier, 'not-idle');
+        }
+        // §7/§8 cost gates — only escalations consume budget/lease; a swap back
+        // to default is always cost-free (it REDUCES spend).
+        const transition = `${session.model ?? 'default'}→${tier}`;
+        let admit = { allow: true };
+        if (tier === 'escalated') {
+            admit = this.deps.governor.admitEscalation({
+                instanceId: session.id,
+                accountId: session.subscriptionAccountId,
+                modelId: targetId,
+                transition,
+                dry: cfg.dryRun,
+            });
+            if (!admit.allow) {
+                return this.refuse(session.name, tier, `cost-guard:${admit.reason}`);
+            }
+        }
+        if (cfg.dryRun && !isRescueDeescalation) {
+            this.audit({
+                type: 'dry-run-would-swap',
+                session: session.name,
+                tier,
+                model: targetId,
+                freeWindow: admit.freeWindow,
+            });
+            return { status: 'dry-run', model: targetId };
+        }
+        if (isRescueDeescalation && (!cfg.enabled || cfg.dryRun)) {
+            // Loud trail: a real swap performed while the feature is off/dry is
+            // exactly the event an operator auditing a rollback wants to see.
+            this.audit({ type: 'rescue-deescalation', session: session.name, model: targetId, enabled: cfg.enabled, dryRun: cfg.dryRun });
+        }
+        // Inject: literal text + separate Enter via the hardened primitive. The
+        // ONLY pane-bound string is the server-derived, enum-validated id.
+        const sent = this.deps.sessions.sendInput(session.tmuxSession, `/model ${targetId}`);
+        if (!sent) {
+            return this.refuse(session.name, tier, 'inject-failed');
+        }
+        if (tier === 'escalated') {
+            // Fails toward counting — recorded at injection, before the canary.
+            this.deps.governor.recordInjection(session.id, transition);
+        }
+        this.audit({ type: 'injected', session: session.name, tier, model: targetId });
+        // Canary read-back — independent oracle, N attempts.
+        const attempts = this.deps.canaryAttempts ?? 5;
+        const interval = this.deps.canaryIntervalMs ?? 600;
+        for (let i = 0; i < attempts; i++) {
+            await this.wait(interval);
+            const readback = this.deps.sessions.captureMeaningfulTail(session.tmuxSession, 30);
+            if (paneConfirmsModel(readback, targetId)) {
+                session.model = targetId;
+                try {
+                    this.deps.saveSession(session);
+                }
+                catch (err) {
+                    this.audit({ type: 'save-session-failed', session: session.name, error: err.message });
+                }
+                this.lastSwapAt.set(session.id, this.now());
+                this.audit({ type: 'swap-confirmed', session: session.name, tier, model: targetId, attempts: i + 1 });
+                return { status: 'swapped', model: targetId, confirmed: true };
+            }
+        }
+        // NOT confirmed: do NOT mark reconciled, do NOT touch Session.model;
+        // behaviourally the session is treated as default. One Attention item.
+        this.lastSwapAt.set(session.id, this.now()); // still dwell — don't re-inject in a tight loop
+        this.audit({ type: 'swap-unconfirmed', session: session.name, tier, model: targetId, attempts });
+        try {
+            this.deps.attention?.({
+                id: `model-swap-unconfirmed-${session.id}-${tier}`,
+                title: `Model swap unconfirmed: ${session.name}`,
+                summary: `Injected /model ${targetId} into "${session.name}" but the independent ` +
+                    `read-back did not confirm within ${attempts} attempts. The session is ` +
+                    `treated as DEFAULT tier; the swap was still counted against the ` +
+                    `escalation budget (fails toward counting).`,
+                category: 'model-tier-escalation',
+                priority: 'NORMAL',
+            });
+        }
+        catch {
+            // attention surface unavailable — the audit record stands
+        }
+        return { status: 'unconfirmed', model: targetId, confirmed: false };
+    }
+    // ── internals ──────────────────────────────────────────────────────────
+    refuse(sessionName, tier, reason) {
+        this.audit({ type: 'refused', session: sessionName, tier, reason });
+        return { status: 'refused', reason };
+    }
+    /** Structured-fields-only audit appender (Sec-F7) — same trail as the
+     *  governor so one file tells the whole escalation story. */
+    audit(event) {
+        try {
+            fs.mkdirSync(path.dirname(this.auditPath), { recursive: true });
+            fs.appendFileSync(this.auditPath, JSON.stringify({ ts: new Date(this.now()).toISOString(), source: 'model-swap', ...event }) + '\n');
+        }
+        catch {
+            // best-effort — never throws into the swap path
+        }
+    }
+}
+//# sourceMappingURL=ModelSwapService.js.map

package/dist/core/ModelSwapService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelSwapService.js","sourceRoot":"","sources":["../../src/core/ModelSwapService.ts"],"names":[],"mappings":"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"}

package/dist/core/ModelTierEscalation.d.ts

@@ -0,0 +1,128 @@
+/**
+ * ModelTierEscalation — §5.1 of docs/specs/FABLE-MODEL-ESCALATION-SPEC.md.
+ *
+ * The per-framework (framework, tier) → concrete-model-id resolver plus the
+ * closed model-id enumerations and per-adapter swap-capability declarations.
+ *
+ * Core contracts (all spec-cited, all fail-closed):
+ *  - Reads ONLY trusted config (`models.tierEscalation`) — never the
+ *    mode-state file. The mode-state can request a TIER; it can never
+ *    supply a model ID (spec Sec-F3).
+ *  - `escalated: null` (or an absent framework entry) resolves to the
+ *    default ⇒ no swap ever — the backwards-compat contract for
+ *    codex/gemini/pi until they ship an ultra model (spec §5.1).
+ *  - Every id is validated by regex AND membership in the framework's
+ *    closed `knownModelIds` enumeration before it can reach a launch arg
+ *    or tmux send-keys (spec Sec-F1/F2 — keystroke-injection guard).
+ *  - Worst-case failure of every path = `null` = the session stays on its
+ *    default model (spec §3.5: a routing decision, never a block).
+ *
+ * Pure logic, no I/O. The governor (§7/§8) and swap service (§5.3) live in
+ * EscalationGovernor.ts / ModelSwapService.ts.
+ */
+/** The frameworks the escalation policy knows. Closed enum — anything else
+ *  resolves to null (spec §5.1 line 1). Kept as a literal union to avoid an
+ *  import cycle with core/types.ts (matches the inline pattern used there). */
+export type EscalationFramework = 'claude-code' | 'codex-cli' | 'gemini-cli' | 'pi-cli';
+export declare const ESCALATION_FRAMEWORKS: readonly EscalationFramework[];
+export type EscalationTier = 'default' | 'escalated';
+/** §5.6 — machine-checkable per-adapter swap capability, not prose. */
+export type SwapCapability = 'mid-session' | 'launch-time-only';
+export interface TierEscalationFrameworkEntry {
+    /** `null` ⇒ use the account default (today's behavior). */
+    default: string | null;
+    /** `null` ⇒ no ultra model ⇒ escalation is a strict no-op (back-compat). */
+    escalated: string | null;
+}
+export interface TierEscalationTriggers {
+    /** Skill names whose entry signals an escalation work-mode (§4). */
+    skills: string[];
+    /** Trigger #1 also fires on project-initiative design state (§4). */
+    projectDesign: boolean;
+    /** Optional LLM intent check for ambiguous phrasing (§5.4). Default OFF. */
+    llmIntentCheck: boolean;
+}
+export interface TierEscalationCostGuards {
+    /** Map of model id → last free-window UTC date (inclusive). §8. */
+    respectFreeWindows: Record<string, string>;
+    /** Refuse escalation without a cached quota snapshot showing headroom (§7).
+     *  Quota unavailable/errored ⇒ fail CLOSED to default. */
+    requireQuotaHeadroom: boolean;
+    /** §7 lease cap — admission control for concurrent escalated sessions. */
+    maxConcurrentEscalatedPerAccount: number;
+    /** §8 — load-bearing for Trigger #1 (short in-conversation swaps). */
+    maxEscalationsPerHour: number;
+    /** §8 — load-bearing for Trigger #2 (long spawned runs). null = disabled. */
+    dailyUltraTokenCap: number | null;
+    /** §5.5 — mode-state self-expiry. Expiry INVALIDATES (fresh trigger needed). */
+    maxEscalationTtlMs: number;
+    /** §5.5 asymmetric hysteresis — never swap twice within this window. */
+    minTierDwellMs: number;
+    /** §5.5 — de-escalate only after the condition is clear this many turns. */
+    minTierDwellTurns: number;
+}
+export interface TierEscalationConfig {
+    /** Fleet default OFF; dev agents (Echo/Codey) ship ENABLED (§10). */
+    enabled: boolean;
+    /** Log intended swaps without performing them. `enabled:false` wins. */
+    dryRun: boolean;
+    triggers: TierEscalationTriggers;
+    frameworks: Partial<Record<EscalationFramework, TierEscalationFrameworkEntry>>;
+    costGuards: TierEscalationCostGuards;
+}
+/** §9 schema defaults — exactly the converged spec's config block. */
+export declare const DEFAULT_TIER_ESCALATION_CONFIG: TierEscalationConfig;
+export declare const KNOWN_CLAUDE_MODEL_IDS: readonly ["claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", "claude-haiku-4-5-20251001", "opus", "sonnet", "haiku"];
+export declare const KNOWN_CODEX_MODEL_IDS: readonly ["gpt-5.2", "gpt-5.3-codex", "gpt-5.4", "gpt-5.4-mini", "gpt-5.5"];
+export declare const KNOWN_MODEL_IDS: Record<EscalationFramework, readonly string[]>;
+/**
+ * §5.6 — per-adapter swap capability. `claude-code` declares 'mid-session'
+ * but the §5.3 contract still verifies EVERY swap with the independent-oracle
+ * canary at runtime; the pre-enable proof is the gated live E2E
+ * (tests/e2e/model-swap-live-canary.test.ts). The other three are
+ * launch-time-only today (and strict no-ops until an escalated model is
+ * populated), so "documented, not silently dropped" is enforced by code.
+ */
+export declare const SWAP_CAPABILITY: Record<EscalationFramework, SwapCapability>;
+/** §5.1 injection-safe id shape. Anything else is audit+reject. */
+export declare const MODEL_ID_RE: RegExp;
+/** Reason codes for fail-closed resolutions — structured, audit-friendly. */
+export type ResolveRejectReason = 'unknown-framework' | 'no-framework-entry' | 'null-id' | 'invalid-id-shape' | 'id-not-in-closed-enum';
+export interface ResolveAuditEvent {
+    framework: string;
+    tier: EscalationTier;
+    reason: ResolveRejectReason;
+    /** Escaped + truncated — never the raw value verbatim past 80 chars (Sec-F7). */
+    rejectedId?: string;
+}
+/** Escape + truncate an untrusted id for audit records (spec Sec-F7). */
+export declare function escapeIdForAudit(id: string): string;
+/**
+ * §5.1 resolver — maps (framework, tier) → concrete model id | null,
+ * reading ONLY the trusted config. Every rejection fails closed to null
+ * (session stays on default) and reports a structured audit event.
+ */
+export declare function resolveTierModel(framework: string, tier: EscalationTier, config: TierEscalationConfig | undefined, audit?: (event: ResolveAuditEvent) => void): string | null;
+/**
+ * True when escalation could ever change behavior for this framework:
+ * an escalated id is configured AND resolves through the closed enum.
+ * Used by callers to keep the no-escalated-model case a true no-op.
+ */
+export declare function hasEscalatedModel(framework: string, config: TierEscalationConfig | undefined): boolean;
+/** The set of configured escalated ids across all frameworks — used by the
+ *  §11 router-exclusion guard and the §8 ultra-cap monitor. */
+export declare function escalatedModelIds(config: TierEscalationConfig | undefined): Set<string>;
+/**
+ * §8 free-window semantics: compared as a UTC date, inclusive through the
+ * named day. Returns true while the window is open. After expiry the
+ * quota/budget guards apply unchanged — the window relaxes nothing
+ * structural (informational + drives the dev-agent dogfood window).
+ */
+export declare function isWithinFreeWindow(modelId: string, guards: TierEscalationCostGuards, nowMs: number): boolean;
+/**
+ * Merge an operator's (possibly partial / absent) config block over the §9
+ * defaults. Add-missing-only semantics live in PostUpdateMigrator; this is
+ * the READ-side normalizer so every consumer sees a complete shape.
+ */
+export declare function normalizeTierEscalationConfig(raw: unknown): TierEscalationConfig;
+//# sourceMappingURL=ModelTierEscalation.d.ts.map

package/dist/core/ModelTierEscalation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelTierEscalation.d.ts","sourceRoot":"","sources":["../../src/core/ModelTierEscalation.ts"],"names":[],"mappings":"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"}

package/dist/core/ModelTierEscalation.js

@@ -0,0 +1,232 @@
+/**
+ * ModelTierEscalation — §5.1 of docs/specs/FABLE-MODEL-ESCALATION-SPEC.md.
+ *
+ * The per-framework (framework, tier) → concrete-model-id resolver plus the
+ * closed model-id enumerations and per-adapter swap-capability declarations.
+ *
+ * Core contracts (all spec-cited, all fail-closed):
+ *  - Reads ONLY trusted config (`models.tierEscalation`) — never the
+ *    mode-state file. The mode-state can request a TIER; it can never
+ *    supply a model ID (spec Sec-F3).
+ *  - `escalated: null` (or an absent framework entry) resolves to the
+ *    default ⇒ no swap ever — the backwards-compat contract for
+ *    codex/gemini/pi until they ship an ultra model (spec §5.1).
+ *  - Every id is validated by regex AND membership in the framework's
+ *    closed `knownModelIds` enumeration before it can reach a launch arg
+ *    or tmux send-keys (spec Sec-F1/F2 — keystroke-injection guard).
+ *  - Worst-case failure of every path = `null` = the session stays on its
+ *    default model (spec §3.5: a routing decision, never a block).
+ *
+ * Pure logic, no I/O. The governor (§7/§8) and swap service (§5.3) live in
+ * EscalationGovernor.ts / ModelSwapService.ts.
+ */
+export const ESCALATION_FRAMEWORKS = [
+    'claude-code',
+    'codex-cli',
+    'gemini-cli',
+    'pi-cli',
+];
+/** §9 schema defaults — exactly the converged spec's config block. */
+export const DEFAULT_TIER_ESCALATION_CONFIG = {
+    enabled: false,
+    dryRun: true,
+    triggers: {
+        skills: ['build', 'autonomous', 'instar-dev', 'spec-converge'],
+        projectDesign: true,
+        llmIntentCheck: false,
+    },
+    frameworks: {
+        'claude-code': { default: 'claude-opus-4-8', escalated: 'claude-fable-5' },
+        'codex-cli': { default: null, escalated: null },
+        'gemini-cli': { default: null, escalated: null },
+        'pi-cli': { default: null, escalated: null },
+    },
+    costGuards: {
+        respectFreeWindows: { 'claude-fable-5': '2026-06-22' },
+        requireQuotaHeadroom: true,
+        maxConcurrentEscalatedPerAccount: 2,
+        maxEscalationsPerHour: 8,
+        dailyUltraTokenCap: null,
+        maxEscalationTtlMs: 21_600_000, // 6h
+        minTierDwellMs: 300_000, // 5min
+        minTierDwellTurns: 1,
+    },
+};
+/**
+ * Closed model-id enumerations per launch adapter (§5.2(c), net-new).
+ * A config value outside its framework's list NEVER reaches a launch arg or
+ * send-keys — resolveTierModel fails closed to null instead.
+ *
+ * claude-code: concrete ids the Claude CLI accepts via `--model`, plus the
+ * CLI tier aliases it documents (haiku/sonnet/opus). Includes the ultra
+ * model `claude-fable-5` — the first populated escalation target.
+ * codex-cli: mirror of CODEX_MODELS_SUBSCRIPTION (routes.ts spawn allowlist).
+ * gemini-cli: re-exported from the adapter's own closed list.
+ * pi-cli: CLOSED-EMPTY by design — pi model ids are `provider/id` patterns
+ * whose provider half is per-agent config; there is no universal closed
+ * enumeration, so the escalation policy refuses ALL pi ids (strict no-op,
+ * §5.6) until a real enumeration is populated. The `/` also fails the id
+ * regex — two independent fail-closed layers.
+ */
+import { KNOWN_GEMINI_MODELS } from '../providers/adapters/gemini-cli/models.js';
+export const KNOWN_CLAUDE_MODEL_IDS = [
+    'claude-fable-5',
+    'claude-opus-4-8',
+    'claude-opus-4-7',
+    'claude-opus-4-6',
+    'claude-sonnet-4-6',
+    'claude-haiku-4-5',
+    'claude-haiku-4-5-20251001',
+    'opus',
+    'sonnet',
+    'haiku',
+];
+export const KNOWN_CODEX_MODEL_IDS = [
+    'gpt-5.2',
+    'gpt-5.3-codex',
+    'gpt-5.4',
+    'gpt-5.4-mini',
+    'gpt-5.5',
+];
+export const KNOWN_MODEL_IDS = {
+    'claude-code': KNOWN_CLAUDE_MODEL_IDS,
+    'codex-cli': KNOWN_CODEX_MODEL_IDS,
+    'gemini-cli': KNOWN_GEMINI_MODELS,
+    'pi-cli': [],
+};
+/**
+ * §5.6 — per-adapter swap capability. `claude-code` declares 'mid-session'
+ * but the §5.3 contract still verifies EVERY swap with the independent-oracle
+ * canary at runtime; the pre-enable proof is the gated live E2E
+ * (tests/e2e/model-swap-live-canary.test.ts). The other three are
+ * launch-time-only today (and strict no-ops until an escalated model is
+ * populated), so "documented, not silently dropped" is enforced by code.
+ */
+export const SWAP_CAPABILITY = {
+    'claude-code': 'mid-session',
+    'codex-cli': 'launch-time-only',
+    'gemini-cli': 'launch-time-only',
+    'pi-cli': 'launch-time-only',
+};
+/** §5.1 injection-safe id shape. Anything else is audit+reject. */
+export const MODEL_ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+/** Escape + truncate an untrusted id for audit records (spec Sec-F7). */
+export function escapeIdForAudit(id) {
+    const escaped = JSON.stringify(id).slice(1, -1); // escape control chars/quotes
+    return escaped.length > 80 ? `${escaped.slice(0, 80)}…(truncated)` : escaped;
+}
+/**
+ * §5.1 resolver — maps (framework, tier) → concrete model id | null,
+ * reading ONLY the trusted config. Every rejection fails closed to null
+ * (session stays on default) and reports a structured audit event.
+ */
+export function resolveTierModel(framework, tier, config, audit) {
+    if (!ESCALATION_FRAMEWORKS.includes(framework)) {
+        audit?.({ framework, tier, reason: 'unknown-framework' });
+        return null;
+    }
+    const fw = framework;
+    const frameworks = config?.frameworks ?? {};
+    // Own-property lookup only — a polluted Object.prototype key can never
+    // smuggle an entry in (§5.1 "Object.create(null) / hasOwnProperty lookup").
+    const entry = Object.prototype.hasOwnProperty.call(frameworks, fw)
+        ? frameworks[fw]
+        : undefined;
+    if (!entry) {
+        audit?.({ framework, tier, reason: 'no-framework-entry' });
+        return null;
+    }
+    const id = tier === 'escalated' ? (entry.escalated ?? entry.default) : entry.default;
+    if (id == null) {
+        // Not an anomaly: `default: null` means "use the account default"
+        // (today's behavior) and `escalated: null` means strict no-op.
+        return null;
+    }
+    if (typeof id !== 'string' || !MODEL_ID_RE.test(id)) {
+        audit?.({ framework, tier, reason: 'invalid-id-shape', rejectedId: escapeIdForAudit(String(id)) });
+        return null;
+    }
+    if (!KNOWN_MODEL_IDS[fw].includes(id)) {
+        audit?.({ framework, tier, reason: 'id-not-in-closed-enum', rejectedId: escapeIdForAudit(id) });
+        return null;
+    }
+    return id;
+}
+/**
+ * True when escalation could ever change behavior for this framework:
+ * an escalated id is configured AND resolves through the closed enum.
+ * Used by callers to keep the no-escalated-model case a true no-op.
+ */
+export function hasEscalatedModel(framework, config) {
+    const escalated = resolveTierModel(framework, 'escalated', config);
+    const dflt = resolveTierModel(framework, 'default', config);
+    return escalated != null && escalated !== dflt;
+}
+/** The set of configured escalated ids across all frameworks — used by the
+ *  §11 router-exclusion guard and the §8 ultra-cap monitor. */
+export function escalatedModelIds(config) {
+    const ids = new Set();
+    for (const fw of ESCALATION_FRAMEWORKS) {
+        const id = resolveTierModel(fw, 'escalated', config);
+        const dflt = resolveTierModel(fw, 'default', config);
+        if (id != null && id !== dflt)
+            ids.add(id);
+    }
+    return ids;
+}
+/**
+ * §8 free-window semantics: compared as a UTC date, inclusive through the
+ * named day. Returns true while the window is open. After expiry the
+ * quota/budget guards apply unchanged — the window relaxes nothing
+ * structural (informational + drives the dev-agent dogfood window).
+ */
+export function isWithinFreeWindow(modelId, guards, nowMs) {
+    const windows = guards.respectFreeWindows ?? {};
+    if (!Object.prototype.hasOwnProperty.call(windows, modelId))
+        return false;
+    const dateStr = windows[modelId];
+    if (typeof dateStr !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(dateStr))
+        return false;
+    // Inclusive through the named UTC day: open until the start of the next day.
+    const endExclusive = Date.parse(`${dateStr}T00:00:00.000Z`) + 24 * 60 * 60 * 1000;
+    return Number.isFinite(endExclusive) && nowMs < endExclusive;
+}
+/**
+ * Merge an operator's (possibly partial / absent) config block over the §9
+ * defaults. Add-missing-only semantics live in PostUpdateMigrator; this is
+ * the READ-side normalizer so every consumer sees a complete shape.
+ */
+export function normalizeTierEscalationConfig(raw) {
+    const d = DEFAULT_TIER_ESCALATION_CONFIG;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return {
+            ...d,
+            triggers: { ...d.triggers, skills: [...d.triggers.skills] },
+            frameworks: { ...d.frameworks },
+            costGuards: { ...d.costGuards, respectFreeWindows: { ...d.costGuards.respectFreeWindows } },
+        };
+    }
+    const r = raw;
+    return {
+        enabled: typeof r.enabled === 'boolean' ? r.enabled : d.enabled,
+        dryRun: typeof r.dryRun === 'boolean' ? r.dryRun : d.dryRun,
+        triggers: {
+            skills: Array.isArray(r.triggers?.skills)
+                ? r.triggers.skills.filter((s) => typeof s === 'string')
+                : [...d.triggers.skills],
+            projectDesign: typeof r.triggers?.projectDesign === 'boolean' ? r.triggers.projectDesign : d.triggers.projectDesign,
+            llmIntentCheck: typeof r.triggers?.llmIntentCheck === 'boolean' ? r.triggers.llmIntentCheck : d.triggers.llmIntentCheck,
+        },
+        frameworks: { ...d.frameworks, ...(r.frameworks && typeof r.frameworks === 'object' ? r.frameworks : {}) },
+        costGuards: {
+            ...d.costGuards,
+            ...(r.costGuards && typeof r.costGuards === 'object' ? r.costGuards : {}),
+            respectFreeWindows: {
+                ...(r.costGuards?.respectFreeWindows && typeof r.costGuards.respectFreeWindows === 'object'
+                    ? r.costGuards.respectFreeWindows
+                    : d.costGuards.respectFreeWindows),
+            },
+        },
+    };
+}
+//# sourceMappingURL=ModelTierEscalation.js.map