instar 1.3.456 → 1.3.458

package/dist/core/ProactiveSwapMonitor.d.ts

@@ -0,0 +1,149 @@
+/**
+ * ProactiveSwapMonitor — the PRE-LIMIT half of the Subscription & Auth Standard's
+ * continuity guarantee (P1.3).
+ *
+ * The reactive path (`autoSwapOnRateLimit`) only fires AFTER a session hits its
+ * account's wall: a RateLimitSentinel escalation on an ACTUAL throttle signal.
+ * So a session blips at the wall before recovering — and an UNTAGGED session
+ * (one with no `subscriptionAccountId`, e.g. the primary interactive session
+ * running on the default config) has nothing for the swap engine to grab, so it
+ * just wedges until an operator manually swaps the default login. That is the
+ * exact 2026-06-09 failure that motivated this monitor.
+ *
+ * This monitor moves a session OFF an account BEFORE it walls, at a lag-aware
+ * measured threshold below the real limit.
+ *
+ * ── Why a separate, lower threshold (lag-aware) ──
+ * The QuotaPoller reads utilization periodically, so our reading TRAILS the real
+ * usage (measured live: our ~90% == Anthropic's ~95% on the same account). A
+ * pre-emptive swap therefore triggers at a LOWER measured threshold (default 80)
+ * to leave margin for the lag — by the time we read 80%, real is higher, and the
+ * swap completes before the wall.
+ *
+ * ── Effective-account resolution (covers the session you actually use) ──
+ * A session carries `subscriptionAccountId` only if it was pinned at spawn. The
+ * primary interactive session usually runs on the DEFAULT config (untagged), so
+ * the monitor resolves an untagged session's effective account from the default
+ * config's live login (InUseAccountResolver). Without this, the session a user
+ * is actively in would be invisible to the swap engine and wedge at the wall.
+ *
+ * ── Bounded, non-storming ──
+ * Per evaluation: only accounts AT pressure that have a sub-threshold ALTERNATE
+ * are sources; candidates are sorted newest-first (the just-(re)started
+ * interactive session ranks first) and capped per cycle; each swapped session
+ * enters a cooldown so a slow restart isn't double-swapped. Near the wall the
+ * monitor triggers a fresh poll so a fast burn isn't missed between the
+ * low-frequency baseline polls.
+ *
+ * Gated OFF by default (moving live sessions is real authority — same authority
+ * as `autoSwapOnRateLimit`, just an earlier trigger). The decision core is pure
+ * (injected deps) so it tests with zero sessions and zero network.
+ */
+import type { SubscriptionAccount } from './SubscriptionPool.js';
+/** A running, swap-eligible session as the monitor sees it. */
+export interface ProactiveSwapSession {
+    /** tmux session name (what the swap path keys on). */
+    sessionName: string;
+    /** The pool account this session is tagged with, or null if untagged
+     *  (untagged ⇒ running on the default config ⇒ resolved via the default login). */
+    accountId: string | null;
+    /** ISO start time — newest-first ordering proxy for "most recently active". */
+    startedAt?: string;
+}
+/** The shape returned by the injected swap (a subset of QuotaAwareScheduler.SwapResult). */
+export interface ProactiveSwapOutcome {
+    swapped: boolean;
+    toAccountId: string | null;
+}
+export interface ProactiveSwapMonitorConfig {
+    /** Current pool accounts (e.g. () => pool.list()). */
+    listAccounts: () => SubscriptionAccount[];
+    /** Currently-running, swap-eligible (claude-code) sessions. */
+    listRunningSessions: () => ProactiveSwapSession[];
+    /** The pool account the DEFAULT config is logged into right now (or null).
+     *  Untagged sessions run here; from InUseAccountResolver in production. */
+    resolveDefaultAccountId: () => Promise<string | null>;
+    /** Performs the actual swap (wraps QuotaAwareScheduler.onQuotaPressure). */
+    swap: (args: {
+        sessionName: string;
+        exhaustedAccountId: string;
+        nowMs: number;
+    }) => Promise<ProactiveSwapOutcome>;
+    /** Optional fresh-poll trigger, awaited when an account is in the watch zone. */
+    triggerPoll?: () => Promise<unknown>;
+    /** Measured binding-window utilization % that triggers a pre-emptive swap. Default 80. */
+    thresholdPct?: number;
+    /** When an at-risk account is within this many points of the threshold, the
+     *  monitor refreshes the poll before deciding (so a fast burn isn't missed
+     *  between baseline polls). Default 15 (i.e. watch zone starts at 65%). */
+    watchMarginPct?: number;
+    /** Max sessions swapped per evaluation cycle (storm guard). Default 3. */
+    maxSwapsPerCycle?: number;
+    /** Per-session cooldown after a successful swap before it's eligible again.
+     *  Default 600000 (10m) — must exceed the swap+restart time. */
+    cooldownMs?: number;
+    /** Monitor tick cadence. Default 180000 (3m). */
+    tickMs?: number;
+    /** Injected for tests. */
+    now?: () => number;
+    logger?: {
+        log: (m: string) => void;
+        warn: (m: string) => void;
+    };
+}
+export interface ProactiveSwapTickResult {
+    /** Session names that were actually swapped this pass. */
+    swapped: string[];
+    /** How many sessions were eligible (at-pressure, has-alternate, off-cooldown). */
+    considered: number;
+    /** Whether a fresh poll was triggered before the decision (watch zone). */
+    refreshed: boolean;
+}
+export declare class ProactiveSwapMonitor {
+    private readonly cfg;
+    private readonly thresholdPct;
+    private readonly watchMarginPct;
+    private readonly maxSwapsPerCycle;
+    private readonly cooldownMs;
+    private readonly tickMs;
+    private readonly now;
+    private readonly logger;
+    /** Last successful-swap timestamp per session (cooldown bookkeeping). */
+    private readonly lastSwapAt;
+    private timer;
+    private ticking;
+    private lastResult;
+    constructor(cfg: ProactiveSwapMonitorConfig);
+    start(): void;
+    stop(): void;
+    /** Status for the read route (never throws). */
+    status(): {
+        thresholdPct: number;
+        watchPct: number;
+        maxSwapsPerCycle: number;
+        cooldownMs: number;
+        tickMs: number;
+        running: boolean;
+        lastResult: ProactiveSwapTickResult | null;
+    };
+    /**
+     * One monitor pass: if any at-risk account is in the watch zone, refresh the
+     * quota poll first (fresh data near the wall), then evaluate + swap.
+     */
+    tick(): Promise<ProactiveSwapTickResult>;
+    /**
+     * Pure-ish decision + swap on the CURRENT snapshots (no poll refresh). Exposed
+     * for tests and the on-demand check route.
+     */
+    evaluate(): Promise<{
+        swapped: string[];
+        considered: number;
+    }>;
+    /**
+     * Map running sessions to candidates whose EFFECTIVE account is at/over minPct.
+     * Effective account = the session's tag, else the default-config login (so the
+     * untagged interactive session is visible). Resolves the default login once.
+     */
+    private mapCandidates;
+}
+//# sourceMappingURL=ProactiveSwapMonitor.d.ts.map

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

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

package/dist/core/ProactiveSwapMonitor.js

@@ -0,0 +1,208 @@
+/**
+ * ProactiveSwapMonitor — the PRE-LIMIT half of the Subscription & Auth Standard's
+ * continuity guarantee (P1.3).
+ *
+ * The reactive path (`autoSwapOnRateLimit`) only fires AFTER a session hits its
+ * account's wall: a RateLimitSentinel escalation on an ACTUAL throttle signal.
+ * So a session blips at the wall before recovering — and an UNTAGGED session
+ * (one with no `subscriptionAccountId`, e.g. the primary interactive session
+ * running on the default config) has nothing for the swap engine to grab, so it
+ * just wedges until an operator manually swaps the default login. That is the
+ * exact 2026-06-09 failure that motivated this monitor.
+ *
+ * This monitor moves a session OFF an account BEFORE it walls, at a lag-aware
+ * measured threshold below the real limit.
+ *
+ * ── Why a separate, lower threshold (lag-aware) ──
+ * The QuotaPoller reads utilization periodically, so our reading TRAILS the real
+ * usage (measured live: our ~90% == Anthropic's ~95% on the same account). A
+ * pre-emptive swap therefore triggers at a LOWER measured threshold (default 80)
+ * to leave margin for the lag — by the time we read 80%, real is higher, and the
+ * swap completes before the wall.
+ *
+ * ── Effective-account resolution (covers the session you actually use) ──
+ * A session carries `subscriptionAccountId` only if it was pinned at spawn. The
+ * primary interactive session usually runs on the DEFAULT config (untagged), so
+ * the monitor resolves an untagged session's effective account from the default
+ * config's live login (InUseAccountResolver). Without this, the session a user
+ * is actively in would be invisible to the swap engine and wedge at the wall.
+ *
+ * ── Bounded, non-storming ──
+ * Per evaluation: only accounts AT pressure that have a sub-threshold ALTERNATE
+ * are sources; candidates are sorted newest-first (the just-(re)started
+ * interactive session ranks first) and capped per cycle; each swapped session
+ * enters a cooldown so a slow restart isn't double-swapped. Near the wall the
+ * monitor triggers a fresh poll so a fast burn isn't missed between the
+ * low-frequency baseline polls.
+ *
+ * Gated OFF by default (moving live sessions is real authority — same authority
+ * as `autoSwapOnRateLimit`, just an earlier trigger). The decision core is pure
+ * (injected deps) so it tests with zero sessions and zero network.
+ */
+import { selectAccount, accountAtPressure, } from './QuotaAwareScheduler.js';
+export class ProactiveSwapMonitor {
+    cfg;
+    thresholdPct;
+    watchMarginPct;
+    maxSwapsPerCycle;
+    cooldownMs;
+    tickMs;
+    now;
+    logger;
+    /** Last successful-swap timestamp per session (cooldown bookkeeping). */
+    lastSwapAt = new Map();
+    timer = null;
+    ticking = false;
+    lastResult = null;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.thresholdPct = cfg.thresholdPct ?? 80;
+        this.watchMarginPct = cfg.watchMarginPct ?? 15;
+        this.maxSwapsPerCycle = cfg.maxSwapsPerCycle ?? 3;
+        this.cooldownMs = cfg.cooldownMs ?? 600_000;
+        this.tickMs = cfg.tickMs ?? 180_000;
+        this.now = cfg.now ?? (() => Date.now());
+        this.logger = cfg.logger ?? { log: () => { }, warn: () => { } };
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            if (this.ticking)
+                return; // never overlap ticks
+            void this.tick();
+        }, this.tickMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Status for the read route (never throws). */
+    status() {
+        return {
+            thresholdPct: this.thresholdPct,
+            watchPct: Math.max(0, this.thresholdPct - this.watchMarginPct),
+            maxSwapsPerCycle: this.maxSwapsPerCycle,
+            cooldownMs: this.cooldownMs,
+            tickMs: this.tickMs,
+            running: this.timer !== null,
+            lastResult: this.lastResult,
+        };
+    }
+    /**
+     * One monitor pass: if any at-risk account is in the watch zone, refresh the
+     * quota poll first (fresh data near the wall), then evaluate + swap.
+     */
+    async tick() {
+        if (this.ticking) {
+            return this.lastResult ?? { swapped: [], considered: 0, refreshed: false };
+        }
+        this.ticking = true;
+        try {
+            let refreshed = false;
+            if (this.cfg.triggerPoll) {
+                const watchPct = Math.max(0, this.thresholdPct - this.watchMarginPct);
+                const near = (await this.mapCandidates(watchPct)).length > 0;
+                if (near) {
+                    try {
+                        await this.cfg.triggerPoll();
+                        refreshed = true;
+                    }
+                    catch {
+                        // @silent-fallback-ok: a poll blip just means we decide on prior data
+                    }
+                }
+            }
+            const evaluated = await this.evaluate();
+            const result = { ...evaluated, refreshed };
+            this.lastResult = result;
+            return result;
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+    /**
+     * Pure-ish decision + swap on the CURRENT snapshots (no poll refresh). Exposed
+     * for tests and the on-demand check route.
+     */
+    async evaluate() {
+        const nowMs = this.now();
+        const accounts = this.cfg.listAccounts();
+        const atPressure = await this.mapCandidates(this.thresholdPct);
+        const eligible = atPressure.filter((c) => {
+            const last = this.lastSwapAt.get(c.sessionName);
+            if (last !== undefined && nowMs - last < this.cooldownMs)
+                return false;
+            // Only swap when there's an alternate BELOW the proactive threshold — never
+            // move a session onto an account that is itself nearly full (anti-thrash).
+            const alt = selectAccount(accounts, { softThresholdPct: this.thresholdPct, nowMs }, c.accountId);
+            return alt !== null;
+        });
+        // Newest-(re)started first: the interactive session a user is actively in
+        // (it just restarted on compaction/recovery) ranks ahead of idle background
+        // sessions, so under the per-cycle cap it is rescued first.
+        eligible.sort((a, b) => b.startedMs - a.startedMs);
+        const toSwap = eligible.slice(0, this.maxSwapsPerCycle);
+        const swapped = [];
+        for (const c of toSwap) {
+            let outcome;
+            try {
+                outcome = await this.cfg.swap({
+                    sessionName: c.sessionName,
+                    exhaustedAccountId: c.accountId,
+                    nowMs,
+                });
+            }
+            catch {
+                // @silent-fallback-ok: a swap failure is retried next cycle (no cooldown set)
+                continue;
+            }
+            if (outcome.swapped) {
+                this.lastSwapAt.set(c.sessionName, nowMs);
+                swapped.push(c.sessionName);
+                this.logger.log(`[ProactiveSwap] ${c.sessionName}: pre-emptively swapped off ${c.accountId} → ${outcome.toAccountId} ` +
+                    `(account ≥${this.thresholdPct}% measured — moved before the wall, conversation preserved)`);
+            }
+        }
+        return { swapped, considered: eligible.length };
+    }
+    /**
+     * Map running sessions to candidates whose EFFECTIVE account is at/over minPct.
+     * Effective account = the session's tag, else the default-config login (so the
+     * untagged interactive session is visible). Resolves the default login once.
+     */
+    async mapCandidates(minPct) {
+        const accounts = this.cfg.listAccounts();
+        const byId = new Map(accounts.map((a) => [a.id, a]));
+        let defaultAcctId = null;
+        try {
+            defaultAcctId = await this.cfg.resolveDefaultAccountId();
+        }
+        catch {
+            defaultAcctId = null; // @silent-fallback-ok: unknown default login → tagged-only
+        }
+        const out = [];
+        for (const s of this.cfg.listRunningSessions()) {
+            const eff = s.accountId ?? defaultAcctId;
+            if (!eff)
+                continue;
+            const acct = byId.get(eff);
+            if (!acct)
+                continue;
+            if (!accountAtPressure(acct, minPct))
+                continue;
+            const startedMs = s.startedAt ? Date.parse(s.startedAt) : NaN;
+            out.push({
+                sessionName: s.sessionName,
+                accountId: eff,
+                startedMs: Number.isFinite(startedMs) ? startedMs : 0,
+            });
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=ProactiveSwapMonitor.js.map

package/dist/core/ProactiveSwapMonitor.js.map

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

package/dist/core/devGatedFeatures.d.ts

@@ -0,0 +1,41 @@
+/**
+ * devGatedFeatures.ts — the registry of features that follow the
+ * standard_development_agent_dark_feature_gate convention: config OMITS
+ * `enabled`, the runtime resolves it via `resolveDevAgentGate` (live on a
+ * development agent, dark on the fleet).
+ *
+ * WHY (DEV-AGENT-DARK-GATE-CONFORMANCE-SPEC, Slice 2): Slice 1's lint catches a
+ * hand-rolled gate and a hardcoded `enabled: false` under a marker comment, but
+ * it cannot prove that a feature's *actual config + construction* resolves live
+ * on a dev agent. This registry drives the both-sides wiring test
+ * (`tests/unit/devGatedFeatures-wiring.test.ts`): for each entry, the REAL
+ * ConfigDefaults are applied and `resolveDevAgentGate(<configPath>)` must be
+ * true under a dev-agent config and false under a fleet config. A feature whose
+ * default hardcodes `enabled: false` (the literal #1001 mechanism — `applyDefaults`
+ * would inject the `false`) fails the test. Adding a dev-gated feature here is
+ * the natural checklist step; the test then guards it permanently.
+ *
+ * NOT every site that calls `resolveDevAgentGate` belongs here — only features
+ * whose intent is "dark fleet / LIVE on dev". Deliberately EXCLUDED:
+ *   - `monitoring.mcpProcessReaper` — destructive (kills processes); ships OFF +
+ *     dry-run for EVERYONE incl. dev agents by design (`enabled: false` default).
+ *   - `monitoring.resourceLedger` — the ledger itself defaults `enabled: true`
+ *     (on for everyone); only its sampling rides the gate off the same key, so
+ *     it is not cleanly a dark-on-fleet feature.
+ */
+/** A feature governed by the developmentAgent dark-feature gate. */
+export interface DevGatedFeature {
+    /** Stable identifier (matches the feature's name in code/docs). */
+    name: string;
+    /** Dotted path to the feature's `enabled` flag in the agent config. */
+    configPath: string;
+    /** One-line description of what runs live on a dev agent. */
+    description: string;
+}
+export declare const DEV_GATED_FEATURES: DevGatedFeature[];
+/**
+ * Read a dotted path off a config object, returning the value or undefined.
+ * Used by the wiring test and the spec-intent cross-check (Slice 3).
+ */
+export declare function getConfigByPath(config: unknown, dottedPath: string): unknown;
+//# sourceMappingURL=devGatedFeatures.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"devGatedFeatures.d.ts","sourceRoot":"","sources":["../../src/core/devGatedFeatures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,kBAAkB,EAAE,eAAe,EAoC/C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAO5E"}

package/dist/core/devGatedFeatures.js

@@ -0,0 +1,76 @@
+/**
+ * devGatedFeatures.ts — the registry of features that follow the
+ * standard_development_agent_dark_feature_gate convention: config OMITS
+ * `enabled`, the runtime resolves it via `resolveDevAgentGate` (live on a
+ * development agent, dark on the fleet).
+ *
+ * WHY (DEV-AGENT-DARK-GATE-CONFORMANCE-SPEC, Slice 2): Slice 1's lint catches a
+ * hand-rolled gate and a hardcoded `enabled: false` under a marker comment, but
+ * it cannot prove that a feature's *actual config + construction* resolves live
+ * on a dev agent. This registry drives the both-sides wiring test
+ * (`tests/unit/devGatedFeatures-wiring.test.ts`): for each entry, the REAL
+ * ConfigDefaults are applied and `resolveDevAgentGate(<configPath>)` must be
+ * true under a dev-agent config and false under a fleet config. A feature whose
+ * default hardcodes `enabled: false` (the literal #1001 mechanism — `applyDefaults`
+ * would inject the `false`) fails the test. Adding a dev-gated feature here is
+ * the natural checklist step; the test then guards it permanently.
+ *
+ * NOT every site that calls `resolveDevAgentGate` belongs here — only features
+ * whose intent is "dark fleet / LIVE on dev". Deliberately EXCLUDED:
+ *   - `monitoring.mcpProcessReaper` — destructive (kills processes); ships OFF +
+ *     dry-run for EVERYONE incl. dev agents by design (`enabled: false` default).
+ *   - `monitoring.resourceLedger` — the ledger itself defaults `enabled: true`
+ *     (on for everyone); only its sampling rides the gate off the same key, so
+ *     it is not cleanly a dark-on-fleet feature.
+ */
+export const DEV_GATED_FEATURES = [
+    {
+        name: 'growthAnalyst',
+        configPath: 'monitoring.growthAnalyst.enabled',
+        description: 'Proactive growth & milestone analyst (/growth/*).',
+    },
+    {
+        name: 'coherenceJournal',
+        configPath: 'multiMachine.coherenceJournal.enabled',
+        description: 'Cross-machine coherence journal.',
+    },
+    {
+        name: 'warmSessionA2A',
+        configPath: 'threadline.warmSessionA2A.enabled',
+        description: 'Warm-session pool for agent-to-agent delivery.',
+    },
+    {
+        name: 'secretSync',
+        configPath: 'multiMachine.secretSync.enabled',
+        description: 'Cross-machine secret sync (receive side).',
+    },
+    {
+        name: 'geminiLoopDriver',
+        configPath: 'autonomousSessions.geminiLoopDriver.enabled',
+        description: 'Gemini autonomous-loop driver.',
+    },
+    {
+        name: 'respawnBuildContext',
+        configPath: 'sessions.respawnBuildContext.enabled',
+        description: 'Respawn build-context capture on session restart.',
+    },
+    {
+        name: 'selfKnowledgeSessionContext',
+        configPath: 'selfKnowledge.sessionContext.enabled',
+        description: 'Session-boot self-knowledge context injection.',
+    },
+];
+/**
+ * Read a dotted path off a config object, returning the value or undefined.
+ * Used by the wiring test and the spec-intent cross-check (Slice 3).
+ */
+export function getConfigByPath(config, dottedPath) {
+    let cur = config;
+    for (const key of dottedPath.split('.')) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+//# sourceMappingURL=devGatedFeatures.js.map

package/dist/core/devGatedFeatures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devGatedFeatures.js","sourceRoot":"","sources":["../../src/core/devGatedFeatures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAYH,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD;QACE,IAAI,EAAE,eAAe;QACrB,UAAU,EAAE,kCAAkC;QAC9C,WAAW,EAAE,mDAAmD;KACjE;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,UAAU,EAAE,uCAAuC;QACnD,WAAW,EAAE,kCAAkC;KAChD;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,UAAU,EAAE,mCAAmC;QAC/C,WAAW,EAAE,gDAAgD;KAC9D;IACD;QACE,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE,iCAAiC;QAC7C,WAAW,EAAE,2CAA2C;KACzD;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,UAAU,EAAE,6CAA6C;QACzD,WAAW,EAAE,gCAAgC;KAC9C;IACD;QACE,IAAI,EAAE,qBAAqB;QAC3B,UAAU,EAAE,sCAAsC;QAClD,WAAW,EAAE,mDAAmD;KACjE;IACD;QACE,IAAI,EAAE,6BAA6B;QACnC,UAAU,EAAE,sCAAsC;QAClD,WAAW,EAAE,gDAAgD;KAC9D;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAe,EAAE,UAAkB;IACjE,IAAI,GAAG,GAAY,MAAM,CAAC;IAC1B,KAAK,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACxC,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC7D,GAAG,GAAI,GAA+B,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/core/types.d.ts

@@ -2409,6 +2409,33 @@ export interface InstarConfig {
          *  auto-swap functional (a session must carry which account it's on for the
          *  swap engine to move it). Unset → spawns use the default config (no-op). */
         pinSessionsToPool?: boolean;
+        /**
+         * DARK by default: the PRE-LIMIT swap. When enabled, the ProactiveSwapMonitor
+         * moves a session OFF an account that crosses `thresholdPct` on its binding
+         * window BEFORE it walls — vs. the reactive `autoSwapOnRateLimit`, which only
+         * fires AFTER the wall. Same authority as the reactive swap (it moves live
+         * sessions), earlier trigger → opt-in. Covers untagged sessions too by
+         * resolving the default-config login (so the primary interactive session is
+         * swap-visible instead of wedging at the wall).
+         */
+        proactiveSwap?: {
+            /** Master switch. Default false (dark). */
+            enabled?: boolean;
+            /** Measured binding-window utilization % that triggers a pre-emptive swap.
+             *  Default 80 — below the real wall to absorb poll-lag (measured trails
+             *  real ~5%), so the swap completes with margin. */
+            thresholdPct?: number;
+            /** Refresh the poll before deciding when an at-risk account is within this
+             *  many points of the threshold (catch a fast burn between baseline polls).
+             *  Default 15. */
+            watchMarginPct?: number;
+            /** Max sessions swapped per evaluation cycle (storm guard). Default 3. */
+            maxSwapsPerCycle?: number;
+            /** Per-session cooldown (ms) after a successful swap. Default 600000 (10m). */
+            cooldownMs?: number;
+            /** Monitor tick cadence (ms). Default 180000 (3m). */
+            tickMs?: number;
+        };
         /** P2.1 enrollment wizard knobs (all optional). */
         enrollment?: {
             /** Per-framework login command override (defaults: claude-code →