instar 1.3.467 → 1.3.469

package/dist/core/EscalationGovernor.d.ts

@@ -0,0 +1,138 @@
+/**
+ * EscalationGovernor — §7 (subscription envelope + lease) and §8 (cost
+ * guards) of docs/specs/FABLE-MODEL-ESCALATION-SPEC.md.
+ *
+ * Admission control for model-tier escalation. Every refusal means "the
+ * session stays on its default model" — the governor can never block a
+ * message, tool call, or session (§3.5).
+ *
+ * Invariants implemented here:
+ *  - **Lease, not bare headroom read** (round-1 Adversarial-H2): concurrent
+ *    escalation onto one account goes through a reservation with
+ *    `maxConcurrentEscalatedPerAccount`.
+ *  - **Crash-safe lease** (round-2 Security-N3 / Adversarial-NEW-1): leases
+ *    carry a TTL, are keyed on the session-instance id (the spawn-generated
+ *    INSTAR_SESSION_ID — unforgeable from outside, monotonic per spawn), are
+ *    released on session-end (SessionManager 'sessionReaped' — wired at
+ *    boot), and a lease whose holder is no longer live is reclaimable.
+ *    Expiry is evaluated lazily on read — no dedicated poller.
+ *  - **Quota fail-closed** (round-1 Adversarial-H3): `requireQuotaHeadroom`
+ *    reads the subscription pool's CACHED snapshot via an injected provider
+ *    (never a live poll on the hot path); unavailable/errored ⇒ refuse.
+ *  - **Once-per-episode counting** (round-3 Adversarial-NEW-5): an
+ *    escalation counts against `maxEscalationsPerHour` exactly once per
+ *    (instance-id, tier-transition) episode; canary retries and per-turn
+ *    re-derivations never multiply the count. **Accounting fails toward
+ *    counting** (round-2 Adversarial-NEW-2): `recordInjection` is called at
+ *    injection time, regardless of read-back outcome.
+ *  - **Free windows** (§8): UTC-date, inclusive through the named day;
+ *    informational only — crossing the expiry emits ONE audit note (no
+ *    silent cost cliff). The window relaxes nothing structural.
+ *  - **Daily ultra-token cap as admission control** (§8): refuses NEW
+ *    escalations once today's ultra spend (injected provider) crosses the
+ *    cap. Mid-run visibility is UltraSessionCapMonitor's job.
+ *
+ * State is file-backed under `<stateDir>/state/model-tier-escalation/`
+ * (atomic tmp+rename writes; single-writer — the server process). The
+ * audit trail is an append-only JSONL with structured fields only — never
+ * raw operator text (round-2 Security-F7).
+ */
+import { type TierEscalationConfig } from './ModelTierEscalation.js';
+/** Conservative "has headroom" bound: a cached window utilization at/over
+ *  this percentage is treated as capped for escalation purposes. */
+export declare const QUOTA_HEADROOM_MAX_UTILIZATION_PCT = 90;
+/** Shape-compatible with SubscriptionPool's AccountQuotaSnapshot — narrowed
+ *  to what admission needs so the provider is easy to inject/test. */
+export interface QuotaSnapshotLike {
+    fiveHour?: {
+        utilizationPct: number;
+        resetsAt?: string;
+    };
+    sevenDay?: {
+        utilizationPct: number;
+        resetsAt?: string;
+    };
+    measuredAt?: string;
+}
+export interface EscalationLease {
+    instanceId: string;
+    accountId: string;
+    acquiredAt: number;
+    ttlMs: number;
+}
+export type AdmitRefusalReason = 'disabled' | 'no-instance-id' | 'lease-capacity' | 'hourly-budget-exhausted' | 'quota-unavailable' | 'quota-capped' | 'daily-cap-exhausted';
+export interface AdmitResult {
+    allow: boolean;
+    reason?: AdmitRefusalReason;
+    /** True when the model is inside a configured free window (informational). */
+    freeWindow?: boolean;
+}
+export interface EscalationGovernorDeps {
+    /** The agent state dir (`.instar`). */
+    stateDir: string;
+    /** Live config getter — re-read per call so operator flips apply. */
+    getConfig: () => TierEscalationConfig;
+    /**
+     * CACHED quota snapshot for the account (never a live poll — §7 /
+     * round-1 Scalability-M7). Return null when no snapshot is available;
+     * with `requireQuotaHeadroom:true` that REFUSES (fail closed).
+     */
+    quotaSnapshot?: (accountId: string) => QuotaSnapshotLike | null;
+    /**
+     * Today's (UTC) ultra-model token total, from the token ledger. Used for
+     * the §8 daily-cap admission check. Return null when unavailable — with a
+     * cap configured, unavailable ⇒ refuse (fail closed).
+     */
+    ultraTokensTodayUtc?: () => number | null;
+    /** Liveness probe for lease reclaim — false ⇒ the holder crashed/ended. */
+    isHolderLive?: (instanceId: string) => boolean;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+export declare class EscalationGovernor {
+    private readonly deps;
+    private readonly dir;
+    private readonly statePath;
+    private readonly auditPath;
+    private readonly now;
+    constructor(deps: EscalationGovernorDeps);
+    /**
+     * §7/§8 admission decision for escalating `instanceId` on `accountId`.
+     * Pure cost/capacity routing — a refusal means "stay on default".
+     * Acquiring is idempotent: an instance already holding a lease is
+     * re-admitted without consuming additional capacity.
+     */
+    admitEscalation(input: {
+        instanceId: string;
+        accountId?: string;
+        modelId: string;
+        /** e.g. 'default→escalated' — the episode key half (§8 once-per-episode). */
+        transition: string;
+        /** dryRun evaluation: run every check but acquire NOTHING — a dry-run
+         *  swap must never consume lease capacity (§9 dryRun semantics). */
+        dry?: boolean;
+    }): AdmitResult;
+    /**
+     * Count the escalation against the hourly budget — called AT INJECTION
+     * time (fails toward counting, round-2 Adversarial-NEW-2), idempotent per
+     * (instance, transition) episode (round-3 Adversarial-NEW-5).
+     * Returns true when this call newly counted the episode.
+     */
+    recordInjection(instanceId: string, transition: string): boolean;
+    /** Release the instance's lease (wired to SessionManager 'sessionReaped'
+     *  at boot — the same close event that retires the session, §7). */
+    releaseLease(instanceId: string): void;
+    /** Current live leases (post-reclaim) — observability/testing surface. */
+    activeLeases(): EscalationLease[];
+    private episodeKey;
+    /** Drop expired leases and leases whose holder is no longer live. Lazy —
+     *  runs on every read; no poller (§7). Returns true when anything changed. */
+    private reclaimStale;
+    private noteFreeWindowExpiryOnce;
+    private loadState;
+    private saveState;
+    /** Structured-fields-only audit appender (Sec-F7: no raw operator text). */
+    private audit;
+    private refuse;
+}
+//# sourceMappingURL=EscalationGovernor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EscalationGovernor.d.ts","sourceRoot":"","sources":["../../src/core/EscalationGovernor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAElC;oEACoE;AACpE,eAAO,MAAM,kCAAkC,KAAK,CAAC;AAErD;sEACsE;AACtE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,QAAQ,CAAC,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAUD,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,gBAAgB,GAChB,gBAAgB,GAChB,yBAAyB,GACzB,mBAAmB,GACnB,cAAc,GACd,qBAAqB,CAAC;AAE1B,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,8EAA8E;IAC9E,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,EAAE,MAAM,oBAAoB,CAAC;IACtC;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,iBAAiB,GAAG,IAAI,CAAC;IAChE;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC1C,2EAA2E;IAC3E,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAC/C,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAID,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,IAAI,EAAE,sBAAsB;IAQxC;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,6EAA6E;QAC7E,UAAU,EAAE,MAAM,CAAC;QACnB;4EACoE;QACpE,GAAG,CAAC,EAAE,OAAO,CAAC;KACf,GAAG,WAAW;IAsHf;;;;;OAKG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAYhE;wEACoE;IACpE,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAUtC,0EAA0E;IAC1E,YAAY,IAAI,eAAe,EAAE;IASjC,OAAO,CAAC,UAAU;IAIlB;kFAC8E;IAC9E,OAAO,CAAC,YAAY;IAyBpB,OAAO,CAAC,wBAAwB;IAmBhC,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,SAAS;IAajB,4EAA4E;IAC5E,OAAO,CAAC,KAAK;IAYb,OAAO,CAAC,MAAM;CAcf"}

package/dist/core/EscalationGovernor.js

@@ -0,0 +1,308 @@
+/**
+ * EscalationGovernor — §7 (subscription envelope + lease) and §8 (cost
+ * guards) of docs/specs/FABLE-MODEL-ESCALATION-SPEC.md.
+ *
+ * Admission control for model-tier escalation. Every refusal means "the
+ * session stays on its default model" — the governor can never block a
+ * message, tool call, or session (§3.5).
+ *
+ * Invariants implemented here:
+ *  - **Lease, not bare headroom read** (round-1 Adversarial-H2): concurrent
+ *    escalation onto one account goes through a reservation with
+ *    `maxConcurrentEscalatedPerAccount`.
+ *  - **Crash-safe lease** (round-2 Security-N3 / Adversarial-NEW-1): leases
+ *    carry a TTL, are keyed on the session-instance id (the spawn-generated
+ *    INSTAR_SESSION_ID — unforgeable from outside, monotonic per spawn), are
+ *    released on session-end (SessionManager 'sessionReaped' — wired at
+ *    boot), and a lease whose holder is no longer live is reclaimable.
+ *    Expiry is evaluated lazily on read — no dedicated poller.
+ *  - **Quota fail-closed** (round-1 Adversarial-H3): `requireQuotaHeadroom`
+ *    reads the subscription pool's CACHED snapshot via an injected provider
+ *    (never a live poll on the hot path); unavailable/errored ⇒ refuse.
+ *  - **Once-per-episode counting** (round-3 Adversarial-NEW-5): an
+ *    escalation counts against `maxEscalationsPerHour` exactly once per
+ *    (instance-id, tier-transition) episode; canary retries and per-turn
+ *    re-derivations never multiply the count. **Accounting fails toward
+ *    counting** (round-2 Adversarial-NEW-2): `recordInjection` is called at
+ *    injection time, regardless of read-back outcome.
+ *  - **Free windows** (§8): UTC-date, inclusive through the named day;
+ *    informational only — crossing the expiry emits ONE audit note (no
+ *    silent cost cliff). The window relaxes nothing structural.
+ *  - **Daily ultra-token cap as admission control** (§8): refuses NEW
+ *    escalations once today's ultra spend (injected provider) crosses the
+ *    cap. Mid-run visibility is UltraSessionCapMonitor's job.
+ *
+ * State is file-backed under `<stateDir>/state/model-tier-escalation/`
+ * (atomic tmp+rename writes; single-writer — the server process). The
+ * audit trail is an append-only JSONL with structured fields only — never
+ * raw operator text (round-2 Security-F7).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { isWithinFreeWindow, } from './ModelTierEscalation.js';
+/** Conservative "has headroom" bound: a cached window utilization at/over
+ *  this percentage is treated as capped for escalation purposes. */
+export const QUOTA_HEADROOM_MAX_UTILIZATION_PCT = 90;
+const EPISODE_RETENTION_MS = 24 * 60 * 60 * 1000;
+export class EscalationGovernor {
+    deps;
+    dir;
+    statePath;
+    auditPath;
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.dir = path.join(deps.stateDir, 'state', 'model-tier-escalation');
+        this.statePath = path.join(this.dir, 'governor.json');
+        this.auditPath = path.join(this.dir, 'audit.jsonl');
+        this.now = deps.now ?? (() => Date.now());
+    }
+    /**
+     * §7/§8 admission decision for escalating `instanceId` on `accountId`.
+     * Pure cost/capacity routing — a refusal means "stay on default".
+     * Acquiring is idempotent: an instance already holding a lease is
+     * re-admitted without consuming additional capacity.
+     */
+    admitEscalation(input) {
+        const cfg = this.deps.getConfig();
+        if (!cfg.enabled) {
+            return this.refuse(input, 'disabled');
+        }
+        if (!input.instanceId) {
+            return this.refuse(input, 'no-instance-id');
+        }
+        const accountId = input.accountId ?? 'default';
+        const state = this.loadState();
+        this.reclaimStale(state);
+        const guards = cfg.costGuards;
+        // Free-window bookkeeping (informational; never gates) — §8 "no silent
+        // cost cliff": the first admission attempt after a window expires emits
+        // one audit note.
+        const freeWindow = isWithinFreeWindow(input.modelId, guards, this.now());
+        this.noteFreeWindowExpiryOnce(state, input.modelId, guards, freeWindow);
+        // 1) Lease capacity (per-account, idempotent for the same instance).
+        const holding = state.leases.find(l => l.instanceId === input.instanceId);
+        if (!holding) {
+            const accountLeases = state.leases.filter(l => l.accountId === accountId);
+            if (accountLeases.length >= guards.maxConcurrentEscalatedPerAccount) {
+                this.saveState(state); // persist any reclaim/expiry-note work
+                return this.refuse(input, 'lease-capacity');
+            }
+        }
+        // 2) Hourly escalation budget (§8 — load-bearing for Trigger #1).
+        // The episode for THIS (instance, transition) does not double-count.
+        const episodeKey = this.episodeKey(input.instanceId, input.transition);
+        const hourAgo = this.now() - 3_600_000;
+        const countedThisHour = Object.entries(state.episodes).filter(([key, at]) => at >= hourAgo && key !== episodeKey).length;
+        const alreadyCounted = Object.prototype.hasOwnProperty.call(state.episodes, episodeKey);
+        if (!alreadyCounted && countedThisHour >= guards.maxEscalationsPerHour) {
+            this.saveState(state);
+            return this.refuse(input, 'hourly-budget-exhausted');
+        }
+        // 3) Quota headroom from the CACHED snapshot — unavailable ⇒ fail closed.
+        if (guards.requireQuotaHeadroom) {
+            let snapshot = null;
+            try {
+                snapshot = this.deps.quotaSnapshot?.(accountId) ?? null;
+            }
+            catch {
+                // @silent-fallback-ok — fail-closed conversion, not a swallow: an
+                // erroring probe reads as "unavailable" and the very next branch
+                // refuses with the AUDITED structured reason 'quota-unavailable'.
+                snapshot = null;
+            }
+            if (!snapshot) {
+                this.saveState(state);
+                return this.refuse(input, 'quota-unavailable');
+            }
+            const capped = [snapshot.fiveHour, snapshot.sevenDay].some(w => w && w.utilizationPct >= QUOTA_HEADROOM_MAX_UTILIZATION_PCT);
+            if (capped) {
+                this.saveState(state);
+                return this.refuse(input, 'quota-capped');
+            }
+        }
+        // 4) Daily ultra-token cap as ADMISSION control (§8). Cap configured but
+        // spend unreadable ⇒ fail closed.
+        if (guards.dailyUltraTokenCap != null) {
+            let spent = null;
+            try {
+                spent = this.deps.ultraTokensTodayUtc?.() ?? null;
+            }
+            catch {
+                // @silent-fallback-ok — fail-closed conversion, not a swallow: an
+                // unreadable ledger reads as null and the next branch refuses with
+                // the AUDITED structured reason 'daily-cap-exhausted'.
+                spent = null;
+            }
+            if (spent == null || spent >= guards.dailyUltraTokenCap) {
+                this.saveState(state);
+                return this.refuse(input, 'daily-cap-exhausted');
+            }
+        }
+        if (input.dry) {
+            this.saveState(state); // persist reclaim/expiry-note work only
+            this.audit({
+                type: 'dry-admit',
+                instanceId: input.instanceId,
+                accountId,
+                modelId: input.modelId,
+                transition: input.transition,
+                freeWindow,
+            });
+            return { allow: true, freeWindow };
+        }
+        // Admit: acquire/refresh the lease (TTL = maxEscalationTtlMs).
+        const lease = {
+            instanceId: input.instanceId,
+            accountId,
+            acquiredAt: this.now(),
+            ttlMs: guards.maxEscalationTtlMs,
+        };
+        state.leases = state.leases.filter(l => l.instanceId !== input.instanceId);
+        state.leases.push(lease);
+        this.saveState(state);
+        this.audit({
+            type: 'admit',
+            instanceId: input.instanceId,
+            accountId,
+            modelId: input.modelId,
+            transition: input.transition,
+            freeWindow,
+        });
+        return { allow: true, freeWindow };
+    }
+    /**
+     * Count the escalation against the hourly budget — called AT INJECTION
+     * time (fails toward counting, round-2 Adversarial-NEW-2), idempotent per
+     * (instance, transition) episode (round-3 Adversarial-NEW-5).
+     * Returns true when this call newly counted the episode.
+     */
+    recordInjection(instanceId, transition) {
+        const state = this.loadState();
+        const key = this.episodeKey(instanceId, transition);
+        if (Object.prototype.hasOwnProperty.call(state.episodes, key)) {
+            return false; // already counted this episode — retries don't multiply
+        }
+        state.episodes[key] = this.now();
+        this.saveState(state);
+        this.audit({ type: 'injection-counted', instanceId, transition });
+        return true;
+    }
+    /** Release the instance's lease (wired to SessionManager 'sessionReaped'
+     *  at boot — the same close event that retires the session, §7). */
+    releaseLease(instanceId) {
+        const state = this.loadState();
+        const before = state.leases.length;
+        state.leases = state.leases.filter(l => l.instanceId !== instanceId);
+        if (state.leases.length !== before) {
+            this.saveState(state);
+            this.audit({ type: 'lease-released', instanceId });
+        }
+    }
+    /** Current live leases (post-reclaim) — observability/testing surface. */
+    activeLeases() {
+        const state = this.loadState();
+        const changed = this.reclaimStale(state);
+        if (changed)
+            this.saveState(state);
+        return [...state.leases];
+    }
+    // ── internals ──────────────────────────────────────────────────────────
+    episodeKey(instanceId, transition) {
+        return `${instanceId}::${transition}`;
+    }
+    /** Drop expired leases and leases whose holder is no longer live. Lazy —
+     *  runs on every read; no poller (§7). Returns true when anything changed. */
+    reclaimStale(state) {
+        const now = this.now();
+        const before = state.leases.length;
+        state.leases = state.leases.filter(l => {
+            if (now - l.acquiredAt >= l.ttlMs) {
+                this.audit({ type: 'lease-reclaimed', instanceId: l.instanceId, why: 'ttl-expired' });
+                return false;
+            }
+            try {
+                if (this.deps.isHolderLive && !this.deps.isHolderLive(l.instanceId)) {
+                    this.audit({ type: 'lease-reclaimed', instanceId: l.instanceId, why: 'holder-not-live' });
+                    return false;
+                }
+            }
+            catch {
+                // liveness probe errored — keep the lease (TTL still bounds it)
+            }
+            return true;
+        });
+        // Prune stale episodes while we're here (same lazy pass).
+        for (const [key, at] of Object.entries(state.episodes)) {
+            if (now - at > EPISODE_RETENTION_MS)
+                delete state.episodes[key];
+        }
+        return state.leases.length !== before;
+    }
+    noteFreeWindowExpiryOnce(state, modelId, guards, currentlyInWindow) {
+        const windows = guards.respectFreeWindows ?? {};
+        if (!Object.prototype.hasOwnProperty.call(windows, modelId))
+            return;
+        if (currentlyInWindow)
+            return;
+        if (state.freeWindowExpiryNoted[modelId] === windows[modelId])
+            return;
+        state.freeWindowExpiryNoted[modelId] = windows[modelId];
+        this.audit({
+            type: 'free-window-expired',
+            modelId,
+            window: windows[modelId],
+            note: 'free window crossed — quota/budget guards apply unchanged',
+        });
+    }
+    loadState() {
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.statePath, 'utf-8'));
+            return {
+                leases: Array.isArray(raw.leases) ? raw.leases.filter(l => l && typeof l.instanceId === 'string') : [],
+                episodes: raw.episodes && typeof raw.episodes === 'object' ? raw.episodes : {},
+                freeWindowExpiryNoted: raw.freeWindowExpiryNoted && typeof raw.freeWindowExpiryNoted === 'object'
+                    ? raw.freeWindowExpiryNoted
+                    : {},
+            };
+        }
+        catch {
+            return { leases: [], episodes: {}, freeWindowExpiryNoted: {} };
+        }
+    }
+    saveState(state) {
+        try {
+            fs.mkdirSync(this.dir, { recursive: true });
+            const tmp = `${this.statePath}.tmp`;
+            fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+            fs.renameSync(tmp, this.statePath);
+        }
+        catch (err) {
+            // State-write failure must never block the caller — but it must be
+            // loud: a governor that can't persist is a governor that can't bound.
+            console.warn(`[escalation-governor] state write failed: ${err.message}`);
+        }
+    }
+    /** Structured-fields-only audit appender (Sec-F7: no raw operator text). */
+    audit(event) {
+        try {
+            fs.mkdirSync(this.dir, { recursive: true });
+            fs.appendFileSync(this.auditPath, JSON.stringify({ ts: new Date(this.now()).toISOString(), ...event }) + '\n');
+        }
+        catch {
+            // best-effort — never throws into the routing path
+        }
+    }
+    refuse(input, reason) {
+        this.audit({
+            type: 'refuse',
+            reason,
+            instanceId: input.instanceId,
+            accountId: input.accountId ?? 'default',
+            modelId: input.modelId,
+            transition: input.transition,
+        });
+        return { allow: false, reason };
+    }
+}
+//# sourceMappingURL=EscalationGovernor.js.map

package/dist/core/EscalationGovernor.js.map

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

package/dist/core/ModelSwapService.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 type { Session } from './types.js';
+import { type EscalationTier, type TierEscalationConfig } from './ModelTierEscalation.js';
+import type { EscalationGovernor } from './EscalationGovernor.js';
+/** The narrow SessionManager surface the swap service is allowed to touch. */
+export interface SwapSessionFacade {
+    listRunningSessions(): Session[];
+    captureMeaningfulTail(tmuxSession: string, lines: number): string | null;
+    sendInput(tmuxSession: string, input: string): boolean;
+}
+export interface AttentionItemLike {
+    id: string;
+    title: string;
+    summary: string;
+    category: string;
+    priority: 'URGENT' | 'HIGH' | 'NORMAL' | 'LOW';
+}
+export interface ModelSwapServiceDeps {
+    stateDir: string;
+    sessions: SwapSessionFacade;
+    /** Persist a mutated Session record (StateManager.saveSession). */
+    saveSession: (session: Session) => void;
+    protectedSessions: () => string[];
+    getConfig: () => TierEscalationConfig;
+    governor: Pick<EscalationGovernor, 'admitEscalation' | 'recordInjection'>;
+    /** Raise an Attention item (TelegramAdapter.createAttentionItem). Optional —
+     *  absence degrades to audit-only, never throws. */
+    attention?: (item: AttentionItemLike) => unknown;
+    /** Canary attempts/cadence — injectable for tests. */
+    canaryAttempts?: number;
+    canaryIntervalMs?: number;
+    wait?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+export type SwapStatus = 'swapped' | 'unconfirmed' | 'dry-run' | 'noop' | 'refused';
+export interface SwapResult {
+    status: SwapStatus;
+    reason?: string;
+    /** The server-derived target model id (when one resolved). */
+    model?: string;
+    /** True only when the independent oracle confirmed the live model. */
+    confirmed?: boolean;
+}
+/**
+ * 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 declare function paneIdleWithEmptyInput(tail: string | null): boolean;
+/**
+ * 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 declare function paneConfirmsModel(tail: string | null, modelId: string): boolean;
+export declare class ModelSwapService {
+    private readonly deps;
+    private readonly auditPath;
+    private readonly now;
+    private readonly wait;
+    /** In-memory per-session last-swap timestamps (dwell backstop). Reset on
+     *  restart — the safe direction (a restart may swap immediately). */
+    private readonly lastSwapAt;
+    constructor(deps: ModelSwapServiceDeps);
+    /**
+     * Swap `name`'s session to `tier`. Body-validated upstream; this method
+     * re-validates everything it relies on (defense in depth).
+     */
+    swap(name: string, tier: EscalationTier): Promise<SwapResult>;
+    private refuse;
+    /** Structured-fields-only audit appender (Sec-F7) — same trail as the
+     *  governor so one file tells the whole escalation story. */
+    private audit;
+}
+//# sourceMappingURL=ModelSwapService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ModelSwapService.d.ts","sourceRoot":"","sources":["../../src/core/ModelSwapService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE/E,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,mBAAmB,IAAI,OAAO,EAAE,CAAC;IACjC,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACzE,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACxD;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CAChD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,mEAAmE;IACnE,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC,iBAAiB,EAAE,MAAM,MAAM,EAAE,CAAC;IAClC,SAAS,EAAE,MAAM,oBAAoB,CAAC;IACtC,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,iBAAiB,GAAG,iBAAiB,CAAC,CAAC;IAC1E;wDACoD;IACpD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC;IACjD,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,aAAa,GACb,SAAS,GACT,MAAM,GACN,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAiBnE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAe/E;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IACrD;yEACqE;IACrE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;gBAE5C,IAAI,EAAE,oBAAoB;IAOtC;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IA0JnE,OAAO,CAAC,MAAM;IAKd;iEAC6D;IAC7D,OAAO,CAAC,KAAK;CAWd"}