instar 1.3.729 → 1.3.731

package/dist/core/ProactiveSwapMonitor.d.ts

@@ -13,25 +13,32 @@
  * 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.
+ * ── Anti-thrash brakes (swap-continuity-antithrash §3) ──
+ * The 2026-07-02 thrash day (36 executed proactive swaps in 8 waves, repeated
+ * kills of six parallel build subagents) proved the bare threshold loop
+ * oscillates. When an SwapAntiThrashEngine is wired (`cfg.antiThrash`), every
+ * proactive decision runs the brake pipeline at THIS chokepoint:
+ * ledger-lost pause → thrash breaker → dwell → validity gate + all-hot →
+ * filter→score→verify target selection → reversal refusal. In dryRun the
+ * legacy decision path stays byte-identical to v1.3.722 while the engine logs
+ * would-refuse rows (the rung-2 soak); live, the engine's verdict binds and
+ * UNTAGGED sessions leave the proactive candidate set entirely (Q3 — a
+ * background optimizer must never mutate the default-slot binding).
  *
- * ── 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.
+ * ── In-flight work deferral (swap-continuity-antithrash §4) ──
+ * When a SwapWorkGate is wired (`cfg.workGate`) and swapContinuity is live, a
+ * braked proactive swap whose session is BUSY (mid-turn or carrying live
+ * subagents) is DEFERRED — the intent is retried each tick through the FULL
+ * brake pipeline (I9), bounded by `deferralCeilingMs`; at the ceiling the
+ * intent is DROPPED (the wall wins; the reactive floor exists) and the
+ * session enters re-intent backoff. The monitor owns the deferral lifecycle
+ * (the gate is a stateless predicate).
  *
  * ── 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
+ * Per evaluation: candidates are sorted newest-first and capped per cycle
+ * (executed swaps only — deferrals never consume the budget); at most one
+ * executed swap per target account per tick (pile-on cap); each swapped
+ * session enters dwell (ledger-backed, restart-safe). Near the wall the
  * monitor triggers a fresh poll so a fast burn isn't missed between the
  * low-frequency baseline polls.
  *
@@ -40,6 +47,8 @@
  * (injected deps) so it tests with zero sessions and zero network.
  */
 import type { SubscriptionAccount } from './SubscriptionPool.js';
+import type { SwapAntiThrashEngine, AntiThrashKnobs } from './SwapAntiThrash.js';
+import type { WorkProbeResult } from './SwapWorkGate.js';
 /** A running, swap-eligible session as the monitor sees it. */
 export interface ProactiveSwapSession {
     /** tmux session name (what the swap path keys on). */
@@ -54,6 +63,15 @@ export interface ProactiveSwapSession {
 export interface ProactiveSwapOutcome {
     swapped: boolean;
     toAccountId: string | null;
+    reason?: string;
+}
+/** swapContinuity knobs as the monitor consumes them (resolved by the wiring). */
+export interface SwapContinuityKnobs {
+    enabled: boolean;
+    dryRun: boolean;
+    deferralCeilingMs: number;
+    reactiveGraceMs: number;
+    recheckMs: number;
 }
 export interface ProactiveSwapMonitorConfig {
     /** Current pool accounts (e.g. () => pool.list()). */
@@ -63,11 +81,16 @@ export interface ProactiveSwapMonitorConfig {
     /** 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). */
+    /** Performs the actual swap (wraps QuotaAwareScheduler.onQuotaPressure).
+     *  When the brakes are LIVE the monitor passes the authoritative
+     *  `targetAccountId` through (§3.3 — the checked target IS the executed
+     *  target, I1) plus `callerClass: 'proactive-swap'`. */
     swap: (args: {
         sessionName: string;
         exhaustedAccountId: string;
         nowMs: number;
+        targetAccountId?: string;
+        callerClass?: 'proactive-swap';
     }) => Promise<ProactiveSwapOutcome>;
     /** Optional fresh-poll trigger, awaited when an account is in the watch zone. */
     triggerPoll?: () => Promise<unknown>;
@@ -80,10 +103,21 @@ export interface ProactiveSwapMonitorConfig {
     /** 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. */
+     *  Default 600000 (10m) — must exceed the swap+restart time. SUBSUMED by
+     *  antiThrash dwell when the brakes are live (§9). */
     cooldownMs?: number;
     /** Monitor tick cadence. Default 180000 (3m). */
     tickMs?: number;
+    /** Anti-thrash brakes (Piece 1). Knobs read LIVE per tick (§7.1). */
+    antiThrash?: {
+        engine: SwapAntiThrashEngine;
+        getKnobs: () => AntiThrashKnobs;
+    };
+    /** In-flight work deferral (Piece 2). Knobs read live per evaluation. */
+    workGate?: {
+        probe: (sessionName: string) => Promise<WorkProbeResult>;
+        getContinuity: () => SwapContinuityKnobs;
+    };
     /** Injected for tests. */
     now?: () => number;
     logger?: {
@@ -108,15 +142,18 @@ export declare class ProactiveSwapMonitor {
     private readonly tickMs;
     private readonly now;
     private readonly logger;
-    /** Last successful-swap timestamp per session (cooldown bookkeeping). */
+    /** Last successful-swap timestamp per session (legacy cooldown bookkeeping). */
     private readonly lastSwapAt;
+    /** Pending deferred proactive intents (Piece 2 — monitor-owned lifecycle). */
+    private readonly deferrals;
     private timer;
     private ticking;
     private lastResult;
     constructor(cfg: ProactiveSwapMonitorConfig);
     start(): void;
     stop(): void;
-    /** Status for the read route (never throws). */
+    /** Status for the read route (never throws). Additive `brakes`/`deferrals`
+     *  blocks per swap-continuity-antithrash §6.3 (all fields LOCAL-SCOPE). */
     status(): {
         thresholdPct: number;
         watchPct: number;
@@ -125,6 +162,15 @@ export declare class ProactiveSwapMonitor {
         tickMs: number;
         running: boolean;
         lastResult: ProactiveSwapTickResult | null;
+        antiThrash?: {
+            enabled: boolean;
+            dryRun: boolean;
+        };
+        brakes?: Record<string, unknown>;
+        deferrals?: {
+            active: number;
+            sessions: string[];
+        };
     };
     /**
      * One monitor pass: if any at-risk account is in the watch zone, refresh the
@@ -134,11 +180,19 @@ export declare class ProactiveSwapMonitor {
     /**
      * Pure-ish decision + swap on the CURRENT snapshots (no poll refresh). Exposed
      * for tests and the on-demand check route.
+     *
+     * With the anti-thrash brakes LIVE the braked pipeline binds; in dryRun (or
+     * with no engine wired) the legacy v1.3.722 decision path is byte-identical
+     * while the engine (when present) logs would-decisions for the soak.
      */
     evaluate(): Promise<{
         swapped: string[];
         considered: number;
     }>;
+    private evaluateBraked;
+    private evaluateLegacy;
+    private safeKnobs;
+    private safeContinuity;
     /**
      * 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

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

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

package/dist/core/ProactiveSwapMonitor.js

@@ -13,25 +13,32 @@
  * 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.
+ * ── Anti-thrash brakes (swap-continuity-antithrash §3) ──
+ * The 2026-07-02 thrash day (36 executed proactive swaps in 8 waves, repeated
+ * kills of six parallel build subagents) proved the bare threshold loop
+ * oscillates. When an SwapAntiThrashEngine is wired (`cfg.antiThrash`), every
+ * proactive decision runs the brake pipeline at THIS chokepoint:
+ * ledger-lost pause → thrash breaker → dwell → validity gate + all-hot →
+ * filter→score→verify target selection → reversal refusal. In dryRun the
+ * legacy decision path stays byte-identical to v1.3.722 while the engine logs
+ * would-refuse rows (the rung-2 soak); live, the engine's verdict binds and
+ * UNTAGGED sessions leave the proactive candidate set entirely (Q3 — a
+ * background optimizer must never mutate the default-slot binding).
  *
- * ── 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.
+ * ── In-flight work deferral (swap-continuity-antithrash §4) ──
+ * When a SwapWorkGate is wired (`cfg.workGate`) and swapContinuity is live, a
+ * braked proactive swap whose session is BUSY (mid-turn or carrying live
+ * subagents) is DEFERRED — the intent is retried each tick through the FULL
+ * brake pipeline (I9), bounded by `deferralCeilingMs`; at the ceiling the
+ * intent is DROPPED (the wall wins; the reactive floor exists) and the
+ * session enters re-intent backoff. The monitor owns the deferral lifecycle
+ * (the gate is a stateless predicate).
  *
  * ── 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
+ * Per evaluation: candidates are sorted newest-first and capped per cycle
+ * (executed swaps only — deferrals never consume the budget); at most one
+ * executed swap per target account per tick (pile-on cap); each swapped
+ * session enters dwell (ledger-backed, restart-safe). Near the wall the
  * monitor triggers a fresh poll so a fast burn isn't missed between the
  * low-frequency baseline polls.
  *
@@ -49,8 +56,10 @@ export class ProactiveSwapMonitor {
     tickMs;
     now;
     logger;
-    /** Last successful-swap timestamp per session (cooldown bookkeeping). */
+    /** Last successful-swap timestamp per session (legacy cooldown bookkeeping). */
     lastSwapAt = new Map();
+    /** Pending deferred proactive intents (Piece 2 — monitor-owned lifecycle). */
+    deferrals = new Map();
     timer = null;
     ticking = false;
     lastResult = null;
@@ -80,9 +89,10 @@ export class ProactiveSwapMonitor {
             this.timer = null;
         }
     }
-    /** Status for the read route (never throws). */
+    /** Status for the read route (never throws). Additive `brakes`/`deferrals`
+     *  blocks per swap-continuity-antithrash §6.3 (all fields LOCAL-SCOPE). */
     status() {
-        return {
+        const base = {
             thresholdPct: this.thresholdPct,
             watchPct: Math.max(0, this.thresholdPct - this.watchMarginPct),
             maxSwapsPerCycle: this.maxSwapsPerCycle,
@@ -91,6 +101,15 @@ export class ProactiveSwapMonitor {
             running: this.timer !== null,
             lastResult: this.lastResult,
         };
+        if (!this.cfg.antiThrash)
+            return base;
+        const knobs = this.safeKnobs();
+        return {
+            ...base,
+            ...(knobs ? { antiThrash: { enabled: knobs.enabled, dryRun: knobs.dryRun } } : {}),
+            brakes: this.cfg.antiThrash.engine.status(this.now()),
+            deferrals: { active: this.deferrals.size, sessions: [...this.deferrals.keys()] },
+        };
     }
     /**
      * One monitor pass: if any at-risk account is in the watch zone, refresh the
@@ -128,10 +147,260 @@ export class ProactiveSwapMonitor {
     /**
      * Pure-ish decision + swap on the CURRENT snapshots (no poll refresh). Exposed
      * for tests and the on-demand check route.
+     *
+     * With the anti-thrash brakes LIVE the braked pipeline binds; in dryRun (or
+     * with no engine wired) the legacy v1.3.722 decision path is byte-identical
+     * while the engine (when present) logs would-decisions for the soak.
      */
     async evaluate() {
         const nowMs = this.now();
         const accounts = this.cfg.listAccounts();
+        const knobs = this.safeKnobs();
+        const engine = this.cfg.antiThrash?.engine ?? null;
+        const engineActive = !!(engine && knobs?.enabled);
+        const live = !!(engineActive && knobs && !knobs.dryRun);
+        if (engine && knobs?.enabled)
+            engine.beginTick(accounts, nowMs, true);
+        try {
+            if (live && engine && knobs) {
+                return await this.evaluateBraked(engine, accounts, nowMs);
+            }
+            return await this.evaluateLegacy(accounts, nowMs, engineActive ? engine : null);
+        }
+        finally {
+            if (engine && knobs?.enabled)
+                engine.endTick(nowMs);
+        }
+    }
+    // ── The LIVE braked pipeline (§3 + §4 proactive arm) ─────────────────────
+    async evaluateBraked(engine, accounts, nowMs) {
+        const byId = new Map(accounts.map((a) => [a.id, a]));
+        // Candidate set: TAGGED sessions only (Q3 — untagged sessions are outside
+        // the proactive candidate set by construction, I10), whose source account
+        // carries a VALID fresh reading at/over the threshold (§3.3 source leg).
+        const candidates = [];
+        const currentAccountBySession = new Map();
+        for (const s of this.cfg.listRunningSessions()) {
+            currentAccountBySession.set(s.sessionName, s.accountId);
+            if (!s.accountId)
+                continue;
+            const acct = byId.get(s.accountId);
+            if (!acct)
+                continue;
+            if (!engine.sourceEligible(acct, nowMs))
+                continue;
+            const startedMs = s.startedAt ? Date.parse(s.startedAt) : NaN;
+            candidates.push({
+                sessionName: s.sessionName,
+                accountId: s.accountId,
+                startedMs: Number.isFinite(startedMs) ? startedMs : 0,
+                untagged: false,
+            });
+        }
+        candidates.sort((a, b) => b.startedMs - a.startedMs);
+        // Deferral invalidation sweep (I9): an intent whose session's account
+        // changed underneath it (a reactive swap moved it), or whose session left
+        // candidacy (wave subsided / session gone), is INVALIDATED — never
+        // executed as a second kill inside the dwell window.
+        for (const [session, d] of [...this.deferrals]) {
+            const stillCandidate = candidates.some((c) => c.sessionName === session);
+            const currentAcct = currentAccountBySession.get(session);
+            if (!stillCandidate || currentAcct !== d.from) {
+                engine.recordInvalidated({
+                    session,
+                    from: d.from,
+                    to: d.to,
+                    nowMs,
+                    deferralAgeMs: nowMs - d.firstAtMs,
+                    deferCount: d.count,
+                });
+                this.deferrals.delete(session);
+            }
+        }
+        const targetsUsedThisTick = new Set();
+        const swapped = [];
+        let considered = 0;
+        const continuity = this.safeContinuity();
+        for (const c of candidates) {
+            if (swapped.length >= this.maxSwapsPerCycle)
+                break;
+            considered += 1;
+            const deferral = this.deferrals.get(c.sessionName);
+            const deferralAgeMs = deferral ? nowMs - deferral.firstAtMs : undefined;
+            // Full brake pipeline — re-run on every deferred retry too (I9: the
+            // intent that finally fires is one that would have been approved fresh).
+            const verdict = engine.evaluateIntent({
+                session: c.sessionName,
+                fromAccountId: c.accountId,
+                accounts,
+                nowMs,
+                targetsUsedThisTick,
+                ...(deferralAgeMs !== undefined ? { deferralAgeMs } : {}),
+                ...(deferral ? { deferCount: deferral.count } : {}),
+            });
+            if (verdict.action !== 'execute')
+                continue; // refusal rows already written by the engine
+            // Piece 2: the work gate (proactive arm — defer, ceiling-drop).
+            if (this.cfg.workGate && continuity?.enabled) {
+                let probe = null;
+                try {
+                    probe = await this.cfg.workGate.probe(c.sessionName);
+                }
+                catch {
+                    // @silent-fallback-ok: probe machinery itself failed → indeterminate,
+                    // which resolves BUSY (I7) — the swap is DEFERRED, the safe direction;
+                    // the deferral is recorded on the anti-thrash engine below.
+                    probe = null;
+                }
+                const busy = probe ? probe.busy : true;
+                if (busy) {
+                    const reason = probe?.reason ?? 'busy-indeterminate';
+                    const inFlight = { turn: probe?.turnInFlight ?? false, subagents: probe?.subagents?.length ?? 0 };
+                    const subagentLeg = probe?.subagentLeg ?? 'indeterminate';
+                    if (continuity.dryRun) {
+                        // Would-defer (rung-2 soak): log the row, change nothing.
+                        engine.recordDeferred({
+                            session: c.sessionName,
+                            from: c.accountId,
+                            to: verdict.targetAccountId,
+                            nowMs,
+                            reason,
+                            inFlight,
+                            subagentLeg,
+                            deferralAgeMs: 0,
+                            deferCount: 1,
+                            dryRun: true,
+                            rowKind: 'first',
+                        });
+                        // fall through to execute (dryRun changes nothing)
+                    }
+                    else {
+                        const d = deferral ?? {
+                            firstAtMs: nowMs,
+                            count: 0,
+                            from: c.accountId,
+                            to: verdict.targetAccountId,
+                        };
+                        d.count += 1;
+                        d.to = verdict.targetAccountId; // ceiling clock carries across target re-selection (§4.2)
+                        this.deferrals.set(c.sessionName, d);
+                        const age = nowMs - d.firstAtMs;
+                        if (age >= continuity.deferralCeilingMs) {
+                            // At the ceiling: the wall wins — DROP the intent; the session
+                            // keeps working and the reactive floor absorbs a genuine wall.
+                            engine.recordDropped({
+                                session: c.sessionName,
+                                from: d.from,
+                                to: d.to,
+                                nowMs,
+                                deferralAgeMs: age,
+                                deferCount: d.count,
+                                inFlight,
+                                subagentLeg,
+                            });
+                            this.deferrals.delete(c.sessionName);
+                        }
+                        else if (d.count === 1) {
+                            // Dedup (§4.2): FIRST row only; the final row is the eventual
+                            // swapped/dropped/invalidated row carrying deferCount.
+                            engine.recordDeferred({
+                                session: c.sessionName,
+                                from: d.from,
+                                to: d.to,
+                                nowMs,
+                                reason,
+                                inFlight,
+                                subagentLeg,
+                                deferralAgeMs: age,
+                                deferCount: d.count,
+                                rowKind: 'first',
+                            });
+                        }
+                        continue;
+                    }
+                }
+            }
+            // Execute — the checked target IS the executed target (I1); the
+            // scheduler revalidates the WHOLE decision at execute time (§3.3).
+            try {
+                const outcome = await this.cfg.swap({
+                    sessionName: c.sessionName,
+                    exhaustedAccountId: c.accountId,
+                    nowMs,
+                    targetAccountId: verdict.targetAccountId,
+                    callerClass: 'proactive-swap',
+                });
+                if (outcome.swapped) {
+                    engine.recordProactiveExecuted({
+                        session: c.sessionName,
+                        from: c.accountId,
+                        to: outcome.toAccountId ?? verdict.targetAccountId,
+                        nowMs,
+                        fromUtilPct: verdict.fromUtilPct,
+                        toUtilPct: verdict.toUtilPct,
+                        ...(deferral ? { deferralAgeMs: nowMs - deferral.firstAtMs, deferCount: deferral.count } : {}),
+                    });
+                    this.lastSwapAt.set(c.sessionName, nowMs);
+                    this.deferrals.delete(c.sessionName);
+                    targetsUsedThisTick.add(verdict.targetAccountId);
+                    swapped.push(c.sessionName);
+                    this.logger.log(`[ProactiveSwap] ${c.sessionName}: pre-emptively swapped off ${c.accountId} → ${outcome.toAccountId ?? verdict.targetAccountId} ` +
+                        `(account ≥${this.thresholdPct}% measured — moved before the wall, conversation preserved)`);
+                }
+                else if (outcome.reason === 'target-revalidation-failed') {
+                    engine.recordRevalidationRefusal({
+                        session: c.sessionName,
+                        from: c.accountId,
+                        to: verdict.targetAccountId,
+                        nowMs,
+                        reason: 'target-revalidation-failed',
+                    });
+                }
+                else if (outcome.reason === 'intent-stale') {
+                    engine.recordRevalidationRefusal({
+                        session: c.sessionName,
+                        from: c.accountId,
+                        to: verdict.targetAccountId,
+                        nowMs,
+                        reason: 'intent-stale',
+                    });
+                    this.deferrals.delete(c.sessionName);
+                }
+                else if (outcome.reason === 'session-busy') {
+                    // Funnel-gate race: the SessionRefresh work gate saw busy after our
+                    // probe. Treat exactly like a busy probe (deferral bookkeeping).
+                    const d = deferral ?? { firstAtMs: nowMs, count: 0, from: c.accountId, to: verdict.targetAccountId };
+                    d.count += 1;
+                    this.deferrals.set(c.sessionName, d);
+                }
+                else {
+                    engine.recordExecFailure({
+                        session: c.sessionName,
+                        from: c.accountId,
+                        to: verdict.targetAccountId,
+                        kind: 'proactive',
+                        errorClass: outcome.reason ?? 'refresh-failed',
+                        nowMs,
+                    });
+                }
+            }
+            catch (err) {
+                // §3.6: a swap execution that THROWS is a failed row + backoff — never
+                // a silent every-tick retry.
+                engine.recordExecFailure({
+                    session: c.sessionName,
+                    from: c.accountId,
+                    to: verdict.targetAccountId,
+                    kind: 'proactive',
+                    errorClass: err instanceof Error ? err.constructor.name : 'Error',
+                    nowMs,
+                });
+            }
+        }
+        return { swapped, considered };
+    }
+    // ── The legacy v1.3.722 decision path (dark / dryRun — byte-identical) ───
+    async evaluateLegacy(accounts, nowMs, shadowEngine) {
         const atPressure = await this.mapCandidates(this.thresholdPct);
         const eligible = atPressure.filter((c) => {
             const last = this.lastSwapAt.get(c.sessionName);
@@ -146,13 +415,28 @@ export class ProactiveSwapMonitor {
         // (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);
-        // TODO(follow-up, 2026-06-09 incident): a proactive cycle moving MANY
-        // sessions at once is itself disruptive — every swap is a kill+respawn
-        // ("Session respawned" + interruption) even when it succeeds. Beyond the
-        // per-cycle cap + cooldown, consider gating on session ACTIVITY: only
-        // swap sessions that are actually burning quota (recent pane activity),
-        // and let idle sessions wall reactively instead of being preemptively
-        // interrupted in bulk.
+        // Rung-2 dry-run shadow (§10): the engine evaluates the LIVE rule's
+        // candidate set (tagged only) and writes would-refuse/would-defer rows —
+        // observability with ZERO decision change.
+        if (shadowEngine) {
+            const shadowTargets = new Set();
+            for (const c of atPressure) {
+                if (c.untagged)
+                    continue; // Q3 — untagged is outside the live candidate set
+                try {
+                    shadowEngine.evaluateIntent({
+                        session: c.sessionName,
+                        fromAccountId: c.accountId,
+                        accounts,
+                        nowMs,
+                        targetsUsedThisTick: shadowTargets,
+                    });
+                }
+                catch {
+                    // @silent-fallback-ok: the shadow must never affect the legacy path
+                }
+            }
+        }
         const toSwap = eligible.slice(0, this.maxSwapsPerCycle);
         const swapped = [];
         for (const c of toSwap) {
@@ -162,21 +446,57 @@ export class ProactiveSwapMonitor {
                     sessionName: c.sessionName,
                     exhaustedAccountId: c.accountId,
                     nowMs,
+                    callerClass: 'proactive-swap',
                 });
             }
-            catch {
-                // @silent-fallback-ok: a swap failure is retried next cycle (no cooldown set)
+            catch (err) {
+                // Legacy behavior: retried next cycle (no cooldown set). With the
+                // engine present the failure is at least RECORDED (§3.6 observability;
+                // decision behavior unchanged in dryRun — no backoff binds here).
+                shadowEngine?.recordExecFailure({
+                    session: c.sessionName,
+                    from: c.accountId,
+                    kind: 'proactive',
+                    errorClass: err instanceof Error ? err.constructor.name : 'Error',
+                    nowMs,
+                });
                 continue;
             }
             if (outcome.swapped) {
                 this.lastSwapAt.set(c.sessionName, nowMs);
                 swapped.push(c.sessionName);
+                shadowEngine?.recordProactiveExecuted({
+                    session: c.sessionName,
+                    from: c.accountId,
+                    to: outcome.toAccountId ?? '',
+                    nowMs,
+                    ...(c.untagged ? { defaultAccountChanged: true } : {}),
+                });
                 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 };
     }
+    safeKnobs() {
+        try {
+            return this.cfg.antiThrash?.getKnobs() ?? null;
+        }
+        catch {
+            // @silent-fallback-ok: a broken knob getter reads as feature-dark (null)
+            // — the brakes simply stay out of the path; legacy swap behavior holds.
+            return null;
+        }
+    }
+    safeContinuity() {
+        try {
+            return this.cfg.workGate?.getContinuity() ?? null;
+        }
+        catch {
+            // @silent-fallback-ok: same feature-dark degrade as safeKnobs above.
+            return null;
+        }
+    }
     /**
      * 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
@@ -207,6 +527,7 @@ export class ProactiveSwapMonitor {
                 sessionName: s.sessionName,
                 accountId: eff,
                 startedMs: Number.isFinite(startedMs) ? startedMs : 0,
+                untagged: s.accountId === null,
             });
         }
         return out;