@tokenfactory/acc-runner 0.40.11 → 0.40.13

package/dist/capacity/account-window.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AS-3 (RESUME): runner-side per-account capacity WINDOW MEMORY.
+ *
+ * A durable, account-keyed memory of "is this login's subscription window
+ * capped, and until when?" keyed on the engine's `synthetic_account`. It is the
+ * piece that lets the resume policy RE-PAUSE a returning capped account FROM
+ * MEMORY without burning a request (operator scenario: swap back to a
+ * still-capped `ajay` → re-pause immediately rather than claim a task just to
+ * watch it 429 again).
+ *
+ * Two states only — `open | capped` — mirroring the server account-window fold
+ * (api/_lib/account-capacity/account-window.ts). The shape is DUPLICATED on
+ * purpose: the runner is a standalone published package and MUST NOT import from
+ * api/_lib (the cost-pricing.ts / capacity-plugin.ts precedent). Kept in sync by
+ * hand. // keep in sync
+ *
+ * The fold applies the CC-3A hysteresis rule verbatim: a capped window reopens
+ * ONLY on a tick whose clock has passed a KNOWN reset instant — never on a
+ * null-reset guess (an indefinite cap stays capped until a probe/account-change
+ * says otherwise), so a window can't flap open on a missing reset time.
+ */
+/** Whether an account's subscription window is serving or capped. */
+export type AccountWindowState = "open" | "capped";
+/** One account's remembered capacity window. */
+export interface AccountWindow {
+    state: AccountWindowState;
+    /**
+     * Absolute reset instant (epoch ms) for a capped window with a KNOWN reset;
+     * `null` means capped indefinitely (no parseable reset) — treated as the
+     * longest possible wait, so extend-only never shortens it and a tick never
+     * reopens it on a guess.
+     */
+    resetAtMs: number | null;
+    /** Epoch ms this window was last folded (audit / staleness). */
+    updatedAtMs: number;
+}
+/** An event folded into a window. */
+export type AccountWindowEvent = 
+/** The account hit a subscription/usage cap; `resetAtMs` is its stated reset (null = indefinite). */
+{
+    kind: "cap_hit";
+    resetAtMs: number | null;
+    atMs: number;
+}
+/** A clock tick — reopens a capped window iff its known reset has elapsed. */
+ | {
+    kind: "tick";
+    atMs: number;
+};
+/**
+ * Fold an event into a window. Pure. Returns a fresh window (never mutates).
+ *   - cap_hit: caps the window; extend-only on the reset instant.
+ *   - tick: reopens a capped window ONLY when a known reset has elapsed.
+ */
+export declare function foldAccountWindow(prev: AccountWindow | null, event: AccountWindowEvent): AccountWindow;
+/**
+ * True when a window is capped AND that cap has NOT yet elapsed — the condition
+ * for re-pausing a returning account from memory. An indefinite cap (null reset)
+ * is always still-capped; a finite cap is still-capped until `nowMs` reaches it.
+ * A missing window (never seen) is NOT still-capped (honest unknown → let the
+ * probe decide).
+ */
+export declare function isStillCapped(window: AccountWindow | null, nowMs: number): boolean;
+//# sourceMappingURL=account-window.d.ts.map

package/dist/capacity/account-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-window.d.ts","sourceRoot":"","sources":["../../src/capacity/account-window.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,qEAAqE;AACrE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnD,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,kBAAkB,CAAC;IAC1B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qCAAqC;AACrC,MAAM,MAAM,kBAAkB;AAC5B,qGAAqG;AACnG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC7D,8EAA8E;GAC5E;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAYnC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,aAAa,GAAG,IAAI,EAC1B,KAAK,EAAE,kBAAkB,GACxB,aAAa,CAiBf;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAGlF"}

package/dist/capacity/account-window.js

@@ -0,0 +1,66 @@
+/**
+ * AS-3 (RESUME): runner-side per-account capacity WINDOW MEMORY.
+ *
+ * A durable, account-keyed memory of "is this login's subscription window
+ * capped, and until when?" keyed on the engine's `synthetic_account`. It is the
+ * piece that lets the resume policy RE-PAUSE a returning capped account FROM
+ * MEMORY without burning a request (operator scenario: swap back to a
+ * still-capped `ajay` → re-pause immediately rather than claim a task just to
+ * watch it 429 again).
+ *
+ * Two states only — `open | capped` — mirroring the server account-window fold
+ * (api/_lib/account-capacity/account-window.ts). The shape is DUPLICATED on
+ * purpose: the runner is a standalone published package and MUST NOT import from
+ * api/_lib (the cost-pricing.ts / capacity-plugin.ts precedent). Kept in sync by
+ * hand. // keep in sync
+ *
+ * The fold applies the CC-3A hysteresis rule verbatim: a capped window reopens
+ * ONLY on a tick whose clock has passed a KNOWN reset instant — never on a
+ * null-reset guess (an indefinite cap stays capped until a probe/account-change
+ * says otherwise), so a window can't flap open on a missing reset time.
+ */
+/**
+ * Extend-only reset merge: a straggler cap can only push a window's reset LATER,
+ * never earlier (mirrors watch.ts enterCapacityPause's extend-only rule). `null`
+ * (indefinite) is the longest wait, so it dominates any finite reset.
+ */
+function mergeResetLater(prev, next) {
+    if (prev === null || next === null)
+        return null;
+    return Math.max(prev, next);
+}
+/**
+ * Fold an event into a window. Pure. Returns a fresh window (never mutates).
+ *   - cap_hit: caps the window; extend-only on the reset instant.
+ *   - tick: reopens a capped window ONLY when a known reset has elapsed.
+ */
+export function foldAccountWindow(prev, event) {
+    if (event.kind === "cap_hit") {
+        const resetAtMs = prev && prev.state === "capped"
+            ? mergeResetLater(prev.resetAtMs, event.resetAtMs)
+            : event.resetAtMs;
+        return { state: "capped", resetAtMs, updatedAtMs: event.atMs };
+    }
+    // tick
+    if (!prev || prev.state !== "capped") {
+        return prev ?? { state: "open", resetAtMs: null, updatedAtMs: event.atMs };
+    }
+    // Reopen only on a KNOWN, elapsed reset — never on a null-reset guess.
+    if (prev.resetAtMs !== null && event.atMs >= prev.resetAtMs) {
+        return { state: "open", resetAtMs: null, updatedAtMs: event.atMs };
+    }
+    return { ...prev, updatedAtMs: event.atMs };
+}
+/**
+ * True when a window is capped AND that cap has NOT yet elapsed — the condition
+ * for re-pausing a returning account from memory. An indefinite cap (null reset)
+ * is always still-capped; a finite cap is still-capped until `nowMs` reaches it.
+ * A missing window (never seen) is NOT still-capped (honest unknown → let the
+ * probe decide).
+ */
+export function isStillCapped(window, nowMs) {
+    if (!window || window.state !== "capped")
+        return false;
+    return window.resetAtMs === null || nowMs < window.resetAtMs;
+}
+//# sourceMappingURL=account-window.js.map

package/dist/capacity/account-window.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-window.js","sourceRoot":"","sources":["../../src/capacity/account-window.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0BH;;;;GAIG;AACH,SAAS,eAAe,CAAC,IAAmB,EAAE,IAAmB;IAC/D,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAA0B,EAC1B,KAAyB;IAEzB,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,SAAS,GACb,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ;YAC7B,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC;YAClD,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IACjE,CAAC;IACD,OAAO;IACP,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,OAAO,IAAI,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7E,CAAC;IACD,uEAAuE;IACvE,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAA4B,EAAE,KAAa;IACvE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACvD,OAAO,MAAM,CAAC,SAAS,KAAK,IAAI,IAAI,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC;AAC/D,CAAC"}

package/dist/capacity/fleet-pause-verbs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * AS-3 (RESUME): the activity-event verbs that drive the server-side FLEET
+ * PAUSE picture.
+ *
+ * "fleet_pause" is NOT a table — the server DERIVES the live paused-fleet set
+ * from `activity_events` (api/_lib/fleet-pause.ts): a runner counts as paused
+ * while its LATEST capacity event is a `runner.capacity_paused` whose
+ * `resume_at` is absent or still future, and it CLEARS the moment a
+ * `runner.capacity_resume` lands. So the resume path "clears the server-side
+ * fleet_pause row" by emitting `runner.capacity_resume` for this runner.
+ *
+ * These strings are DUPLICATED from api/_lib/fleet-pause.ts on purpose (the
+ * runner is a standalone published package and must not import from api/_lib —
+ * the capacity-plugin.ts precedent). Kept in sync by hand. // keep in sync
+ *
+ * NOTE (drift the wiring must fix): watch.ts today emits `runner.paused_capacity`
+ * / `runner.resume_capacity`, which the loader does NOT read — so the current
+ * fixed-timer pause is invisible to fleet_pause. The AS-3 controller emits these
+ * canonical verbs through its `setServerPause` / `clearServerPause` seams so the
+ * server sees the pause AND its clear.
+ */
+/** Verb a runner emits when it enters a capacity pause. Payload: `{ runner_id, resume_at?: ISO|null, reason?: string }`. */
+export declare const RUNNER_CAPACITY_PAUSED_VERB = "runner.capacity_paused";
+/** Verb a runner emits to clear its server-side fleet pause. Payload: `{ runner_id }`. */
+export declare const RUNNER_CAPACITY_RESUME_VERB = "runner.capacity_resume";
+/** Shape of the `runner.capacity_paused` payload the wiring should emit. */
+export interface FleetPausePayload {
+    runner_id: string;
+    /** ISO reset instant, or null for an indefinite pause. */
+    resume_at: string | null;
+    /** Non-secret cause. */
+    reason?: string;
+}
+/** Shape of the `runner.capacity_resume` payload the wiring should emit. */
+export interface FleetResumePayload {
+    runner_id: string;
+}
+//# sourceMappingURL=fleet-pause-verbs.d.ts.map

package/dist/capacity/fleet-pause-verbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-pause-verbs.d.ts","sourceRoot":"","sources":["../../src/capacity/fleet-pause-verbs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,4HAA4H;AAC5H,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE,0FAA0F;AAC1F,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/capacity/fleet-pause-verbs.js

@@ -0,0 +1,26 @@
+/**
+ * AS-3 (RESUME): the activity-event verbs that drive the server-side FLEET
+ * PAUSE picture.
+ *
+ * "fleet_pause" is NOT a table — the server DERIVES the live paused-fleet set
+ * from `activity_events` (api/_lib/fleet-pause.ts): a runner counts as paused
+ * while its LATEST capacity event is a `runner.capacity_paused` whose
+ * `resume_at` is absent or still future, and it CLEARS the moment a
+ * `runner.capacity_resume` lands. So the resume path "clears the server-side
+ * fleet_pause row" by emitting `runner.capacity_resume` for this runner.
+ *
+ * These strings are DUPLICATED from api/_lib/fleet-pause.ts on purpose (the
+ * runner is a standalone published package and must not import from api/_lib —
+ * the capacity-plugin.ts precedent). Kept in sync by hand. // keep in sync
+ *
+ * NOTE (drift the wiring must fix): watch.ts today emits `runner.paused_capacity`
+ * / `runner.resume_capacity`, which the loader does NOT read — so the current
+ * fixed-timer pause is invisible to fleet_pause. The AS-3 controller emits these
+ * canonical verbs through its `setServerPause` / `clearServerPause` seams so the
+ * server sees the pause AND its clear.
+ */
+/** Verb a runner emits when it enters a capacity pause. Payload: `{ runner_id, resume_at?: ISO|null, reason?: string }`. */
+export const RUNNER_CAPACITY_PAUSED_VERB = "runner.capacity_paused";
+/** Verb a runner emits to clear its server-side fleet pause. Payload: `{ runner_id }`. */
+export const RUNNER_CAPACITY_RESUME_VERB = "runner.capacity_resume";
+//# sourceMappingURL=fleet-pause-verbs.js.map

package/dist/capacity/fleet-pause-verbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-pause-verbs.js","sourceRoot":"","sources":["../../src/capacity/fleet-pause-verbs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,4HAA4H;AAC5H,MAAM,CAAC,MAAM,2BAA2B,GAAG,wBAAwB,CAAC;AAEpE,0FAA0F;AAC1F,MAAM,CAAC,MAAM,2BAA2B,GAAG,wBAAwB,CAAC"}

package/dist/capacity/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AS-3 (RESUME): the runner capacity RESUME surface.
+ *
+ * Public entry point for the pause-until-(reset OR account-change OR ping-ok)
+ * engine: the stateful `ResumeController`, the pure `evaluateResume` decision
+ * core, the per-account window memory, and the fleet-pause verbs the wiring
+ * emits to set/clear the server-side pause. Wiring these onto watch.ts's pause
+ * path and the companion turn loop is a follow-up (those files are outside this
+ * track's scope); this barrel is what that follow-up imports.
+ */
+export { ResumeController, type ResumeControllerDeps, type ResumeTransition, } from "./resume-controller.js";
+export { evaluateResume, type CapacityMode, type ResumeDecision, type ResumeEvalInput, type ResumeReason, } from "./resume-policy.js";
+export { foldAccountWindow, isStillCapped, type AccountWindow, type AccountWindowEvent, type AccountWindowState, } from "./account-window.js";
+export { RUNNER_CAPACITY_PAUSED_VERB, RUNNER_CAPACITY_RESUME_VERB, type FleetPausePayload, type FleetResumePayload, } from "./fleet-pause-verbs.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/capacity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capacity/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAC"}

package/dist/capacity/index.js

@@ -0,0 +1,15 @@
+/**
+ * AS-3 (RESUME): the runner capacity RESUME surface.
+ *
+ * Public entry point for the pause-until-(reset OR account-change OR ping-ok)
+ * engine: the stateful `ResumeController`, the pure `evaluateResume` decision
+ * core, the per-account window memory, and the fleet-pause verbs the wiring
+ * emits to set/clear the server-side pause. Wiring these onto watch.ts's pause
+ * path and the companion turn loop is a follow-up (those files are outside this
+ * track's scope); this barrel is what that follow-up imports.
+ */
+export { ResumeController, } from "./resume-controller.js";
+export { evaluateResume, } from "./resume-policy.js";
+export { foldAccountWindow, isStillCapped, } from "./account-window.js";
+export { RUNNER_CAPACITY_PAUSED_VERB, RUNNER_CAPACITY_RESUME_VERB, } from "./fleet-pause-verbs.js";
+//# sourceMappingURL=index.js.map

package/dist/capacity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capacity/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,gBAAgB,GAGjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,GAKf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,iBAAiB,EACjB,aAAa,GAId,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,GAG5B,MAAM,wBAAwB,CAAC"}

package/dist/capacity/resume-controller.d.ts

@@ -0,0 +1,150 @@
+/**
+ * AS-3 (RESUME): the capacity RESUME CONTROLLER.
+ *
+ * The stateful governor that replaces watch.ts's fixed pause-until-reset
+ * `setTimeout` with pause-until-(reset OR account-change OR ping-ok), and adds
+ * the symmetric re-pause-from-memory for a returning still-capped account.
+ * It owns the per-account window memory + the pure resume policy
+ * (resume-policy.ts) and drives them off:
+ *
+ *   - `reportCapacity()` — a task/review hit a subscription cap (watch.ts's
+ *     `enterCapacityPause` trigger). Folds a cap onto the account and, if it is
+ *     the current account, ENTERS the pause.
+ *   - `observeAccount()` — the account probe (AS-1 `AccountProbeScheduler` →
+ *     AS-2 broadcaster) saw the logged-in account. The fast path for a login
+ *     swap: fires an immediate re-evaluation so a swap converges within one
+ *     probe cycle rather than waiting on the stale account's reset.
+ *   - an internal POLL (armed only while paused, at `pollIntervalMs`) that
+ *     re-checks the reset instant + fires the cheap probe ping.
+ *
+ * On RESUME it does the three things the plan pins to the SAME TICK: clears the
+ * server-side fleet pause (`clearServerPause`), restarts task+review claim
+ * scans (`restartClaims`), and kicks the companion turn loop (`kickCompanion`)
+ * so queued chat turns drain — then leaves the pause. In-flight sessions are
+ * never touched: the controller only gates CLAIMING, it has no abort seam.
+ *
+ * FULLY injectable (clock / timer / probe / every side-effect seam) and every
+ * action is serialized onto one tail promise so overlapping triggers can't race
+ * — so the whole lifecycle is exercised with a fake clock, no wall-clock sleep,
+ * no real binary, no network.
+ */
+import type { ProbeTimer } from "../engines/account-probe.js";
+import { type AccountWindow } from "./account-window.js";
+import { type CapacityMode, type ResumeReason } from "./resume-policy.js";
+/** A pause/resume transition, handed to the audit sink. */
+export interface ResumeTransition {
+    from: CapacityMode;
+    to: CapacityMode;
+    /** Why the transition fired. */
+    reason: ResumeReason | "cap-hit" | "returning-capped-account";
+    /** The account the runner is anchored to after the transition. */
+    account: string | null;
+    /** Which driver produced it. */
+    trigger: "cap-report" | "observe-account" | "poll";
+    at: number;
+}
+export interface ResumeControllerDeps {
+    /** Clock (test seam). Default `Date.now`. */
+    now?: () => number;
+    /** Timer seam (test seam). Default `setTimeout`/`clearTimeout`. */
+    timer?: ProbeTimer;
+    /** While-paused re-check cadence (ms). Default 60s. */
+    pollIntervalMs?: number;
+    /** Min gap between account-change adoptions (flap protection). Default 60s. */
+    adoptionDebounceMs?: number;
+    /**
+     * Cheap serve-check for the observed account while paused:
+     *   true = can serve now, false = still capped, null = can't tell.
+     * Omit to disable ping-based resume (reset + account-change still apply).
+     */
+    probePing?: () => Promise<boolean | null>;
+    /** Clear the server-side fleet pause (emit `runner.capacity_resume`). */
+    clearServerPause: () => void | Promise<void>;
+    /** Set the server-side fleet pause (emit `runner.capacity_paused`). Optional. */
+    setServerPause?: (ctx: {
+        account: string;
+        resetAtMs: number | null;
+    }) => void | Promise<void>;
+    /** Restart task + review claim scans (watch.ts: pollOnce + pump + pumpReviews). */
+    restartClaims: () => void | Promise<void>;
+    /** Stop claiming tasks + reviews (watch.ts: pausedCapacity = true). Optional. */
+    stopClaims?: () => void | Promise<void>;
+    /** Kick the companion turn loop so queued chat turns drain. Optional. */
+    kickCompanion?: () => void | Promise<void>;
+    /** Freeze the companion turn loop on (re-)pause. Optional. */
+    freezeCompanion?: () => void | Promise<void>;
+    /** Best-effort audit/log sink. */
+    onLog?: (line: string) => void;
+    /** Transition audit hook. */
+    onTransition?: (t: ResumeTransition) => void;
+}
+/**
+ * Drives the pause-until-(reset OR account-change OR ping-ok) lifecycle. Start
+ * it once the runner knows its account (`start`), feed it cap reports and
+ * account observations, and it clears/sets the server pause and restarts claims
+ * through the injected seams at the right moment.
+ */
+export declare class ResumeController {
+    private readonly deps;
+    private readonly now;
+    private readonly timer;
+    private readonly pollIntervalMs;
+    private readonly adoptionDebounceMs;
+    private started;
+    private stopped;
+    private mode;
+    /** The account the current state is anchored to (capped account while paused). */
+    private anchorAccountKey;
+    /** The account the probe last observed. */
+    private observedAccountKey;
+    /** Per-account remembered capacity windows. */
+    private readonly windows;
+    /** Epoch ms of the last account-change adoption (null = none yet). */
+    private lastAdoptionAtMs;
+    private pollHandle;
+    /** Serial action chain so overlapping triggers never race. */
+    private tail;
+    constructor(deps: ResumeControllerDeps);
+    /** Current mode. */
+    currentMode(): CapacityMode;
+    /** The remembered window for an account (test/inspection seam). */
+    windowFor(accountKey: string): AccountWindow | null;
+    /** Note the runner's starting account. Idempotent. */
+    start(accountKey: string | null): void;
+    /**
+     * A task/review reported a subscription cap on `accountKey`. Folds the cap
+     * into that account's window and, when it is the current account and we are
+     * still claiming, enters the pause. Extend-only: a straggler cap on the
+     * already-paused account only pushes its reset later.
+     */
+    reportCapacity(input: {
+        accountKey: string;
+        resetAtMs: number | null;
+        detail?: string;
+    }): void;
+    /**
+     * The account probe observed the logged-in account. The fast path for a login
+     * swap — fires an immediate re-evaluation so a swap converges within one probe
+     * cycle. A same-account observation is a cheap no-op re-check.
+     */
+    observeAccount(accountKey: string | null): void;
+    /** Cancel the poll timer; in-flight actions still settle. */
+    stop(): void;
+    /** Resolve once every queued action has settled (test seam). */
+    settle(): Promise<void>;
+    private enqueue;
+    private armPoll;
+    private disarmPoll;
+    private onPollFire;
+    /** Evaluate the resume policy and act on it. */
+    private evaluate;
+    /** Enter (or re-enter) the capacity pause on `account`. */
+    private enterPause;
+    /**
+     * Leave the pause: clear the server fleet pause, restart claim scans, and kick
+     * the companion turn loop — all in this one tick (queued chat turns then drain
+     * on their own). In-flight sessions are never touched.
+     */
+    private doResume;
+}
+//# sourceMappingURL=resume-controller.d.ts.map

package/dist/capacity/resume-controller.d.ts.map

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

package/dist/capacity/resume-controller.js

@@ -0,0 +1,229 @@
+import { foldAccountWindow } from "./account-window.js";
+import { evaluateResume, } from "./resume-policy.js";
+const DEFAULT_POLL_INTERVAL_MS = 60_000; // one probe cycle
+const DEFAULT_ADOPTION_DEBOUNCE_MS = 60_000; // CC-3A cooldownMinDwellMs
+const DEFAULT_TIMER = {
+    setTimer: (fn, ms) => setTimeout(fn, ms),
+    clearTimer: (h) => clearTimeout(h),
+};
+/**
+ * Drives the pause-until-(reset OR account-change OR ping-ok) lifecycle. Start
+ * it once the runner knows its account (`start`), feed it cap reports and
+ * account observations, and it clears/sets the server pause and restarts claims
+ * through the injected seams at the right moment.
+ */
+export class ResumeController {
+    deps;
+    now;
+    timer;
+    pollIntervalMs;
+    adoptionDebounceMs;
+    started = false;
+    stopped = false;
+    mode = "active";
+    /** The account the current state is anchored to (capped account while paused). */
+    anchorAccountKey = null;
+    /** The account the probe last observed. */
+    observedAccountKey = null;
+    /** Per-account remembered capacity windows. */
+    windows = new Map();
+    /** Epoch ms of the last account-change adoption (null = none yet). */
+    lastAdoptionAtMs = null;
+    pollHandle = null;
+    /** Serial action chain so overlapping triggers never race. */
+    tail = Promise.resolve();
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.timer = deps.timer ?? DEFAULT_TIMER;
+        this.pollIntervalMs = Math.max(1, deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+        this.adoptionDebounceMs = Math.max(0, deps.adoptionDebounceMs ?? DEFAULT_ADOPTION_DEBOUNCE_MS);
+    }
+    /** Current mode. */
+    currentMode() {
+        return this.mode;
+    }
+    /** The remembered window for an account (test/inspection seam). */
+    windowFor(accountKey) {
+        return this.windows.get(accountKey) ?? null;
+    }
+    /** Note the runner's starting account. Idempotent. */
+    start(accountKey) {
+        if (this.started || this.stopped)
+            return;
+        this.started = true;
+        this.anchorAccountKey = accountKey;
+        this.observedAccountKey = accountKey;
+    }
+    /**
+     * A task/review reported a subscription cap on `accountKey`. Folds the cap
+     * into that account's window and, when it is the current account and we are
+     * still claiming, enters the pause. Extend-only: a straggler cap on the
+     * already-paused account only pushes its reset later.
+     */
+    reportCapacity(input) {
+        if (this.stopped)
+            return;
+        if (!this.started)
+            this.start(input.accountKey);
+        const at = this.now();
+        this.windows.set(input.accountKey, foldAccountWindow(this.windows.get(input.accountKey) ?? null, {
+            kind: "cap_hit",
+            resetAtMs: input.resetAtMs,
+            atMs: at,
+        }));
+        // Only the CURRENT account's cap pauses the runner.
+        if (input.accountKey !== (this.observedAccountKey ?? this.anchorAccountKey))
+            return;
+        if (this.mode === "paused") {
+            // Already paused: the window was extended above; nothing else to do.
+            return;
+        }
+        this.enqueue(() => this.enterPause(input.accountKey, input.resetAtMs, "cap-hit", "cap-report"));
+    }
+    /**
+     * The account probe observed the logged-in account. The fast path for a login
+     * swap — fires an immediate re-evaluation so a swap converges within one probe
+     * cycle. A same-account observation is a cheap no-op re-check.
+     */
+    observeAccount(accountKey) {
+        if (this.stopped || !this.started)
+            return;
+        this.observedAccountKey = accountKey;
+        this.enqueue(() => this.evaluate("observe-account"));
+    }
+    /** Cancel the poll timer; in-flight actions still settle. */
+    stop() {
+        this.stopped = true;
+        this.disarmPoll();
+    }
+    /** Resolve once every queued action has settled (test seam). */
+    async settle() {
+        await this.tail;
+    }
+    enqueue(fn) {
+        this.tail = this.tail.then(fn).catch((err) => {
+            this.deps.onLog?.(`[acc-runner] resume-controller action failed: ${err?.message ?? String(err)}`);
+        });
+    }
+    armPoll() {
+        this.disarmPoll();
+        if (this.stopped)
+            return;
+        this.pollHandle = this.timer.setTimer(() => this.onPollFire(), this.pollIntervalMs);
+    }
+    disarmPoll() {
+        if (this.pollHandle !== null) {
+            this.timer.clearTimer(this.pollHandle);
+            this.pollHandle = null;
+        }
+    }
+    onPollFire() {
+        if (this.stopped || this.mode !== "paused")
+            return;
+        // Re-arm BEFORE the async evaluation so the cadence is decoupled from probe
+        // latency and stays deterministic under a fake clock.
+        this.armPoll();
+        this.enqueue(() => this.evaluate("poll"));
+    }
+    /** Evaluate the resume policy and act on it. */
+    async evaluate(trigger) {
+        if (this.stopped)
+            return;
+        let pingOk = null;
+        if (this.mode === "paused" && this.deps.probePing) {
+            // Only ping when the same account is still observed — a swap resolves via
+            // the account-change branch and needs no request.
+            const swapped = this.observedAccountKey !== null && this.observedAccountKey !== this.anchorAccountKey;
+            if (!swapped) {
+                try {
+                    pingOk = await this.deps.probePing();
+                }
+                catch (err) {
+                    this.deps.onLog?.(`[acc-runner] resume probe ping failed: ${err?.message ?? String(err)}`);
+                }
+            }
+            if (this.stopped)
+                return;
+        }
+        const decision = evaluateResume({
+            mode: this.mode,
+            nowMs: this.now(),
+            observedAccountKey: this.observedAccountKey,
+            anchorAccountKey: this.anchorAccountKey,
+            windows: this.windows,
+            pingOk,
+            lastAdoptionAtMs: this.lastAdoptionAtMs,
+            adoptionDebounceMs: this.adoptionDebounceMs,
+        });
+        switch (decision.action) {
+            case "stay":
+                return;
+            case "defer":
+                this.deps.onLog?.(`[acc-runner] account change to ${decision.account} deferred (adoption debounce)`);
+                return;
+            case "resume":
+                await this.doResume(decision.reason, decision.account, trigger);
+                return;
+            case "pause":
+                await this.enterPause(decision.account, decision.resetAtMs, "returning-capped-account", trigger);
+                return;
+        }
+    }
+    /** Enter (or re-enter) the capacity pause on `account`. */
+    async enterPause(account, resetAtMs, reason, trigger) {
+        if (this.stopped)
+            return;
+        const from = this.mode;
+        const at = this.now();
+        // Ensure the account's window reflects this cap.
+        this.windows.set(account, foldAccountWindow(this.windows.get(account) ?? null, {
+            kind: "cap_hit",
+            resetAtMs,
+            atMs: at,
+        }));
+        this.mode = "paused";
+        this.anchorAccountKey = account;
+        // An account-change re-pause counts as an adoption (flap protection); a
+        // plain cap-hit does not, so the first swap after it is never debounced.
+        if (reason === "returning-capped-account")
+            this.lastAdoptionAtMs = at;
+        this.armPoll();
+        if (this.deps.setServerPause) {
+            await this.deps.setServerPause({ account, resetAtMs });
+        }
+        if (this.deps.stopClaims)
+            await this.deps.stopClaims();
+        if (this.deps.freezeCompanion)
+            await this.deps.freezeCompanion();
+        this.deps.onTransition?.({ from, to: "paused", reason, account, trigger, at });
+        this.deps.onLog?.(`[acc-runner] capacity PAUSE (${reason}) on ${account}` +
+            (resetAtMs !== null ? ` until ${new Date(resetAtMs).toISOString()}` : " (indefinite)"));
+    }
+    /**
+     * Leave the pause: clear the server fleet pause, restart claim scans, and kick
+     * the companion turn loop — all in this one tick (queued chat turns then drain
+     * on their own). In-flight sessions are never touched.
+     */
+    async doResume(reason, account, trigger) {
+        if (this.stopped)
+            return;
+        const from = this.mode;
+        const at = this.now();
+        this.mode = "active";
+        this.anchorAccountKey = account;
+        this.lastAdoptionAtMs = at;
+        // We are now serving on this account, so its window is open in memory — a
+        // later swap back to it resumes (not re-pauses) until it caps again.
+        this.windows.set(account, { state: "open", resetAtMs: null, updatedAtMs: at });
+        this.disarmPoll();
+        // Same tick: clear server pause → restart task+review claims → drain companion.
+        await this.deps.clearServerPause();
+        await this.deps.restartClaims();
+        if (this.deps.kickCompanion)
+            await this.deps.kickCompanion();
+        this.deps.onTransition?.({ from, to: "active", reason, account, trigger, at });
+        this.deps.onLog?.(`[acc-runner] capacity RESUME (${reason}) on ${account}`);
+    }
+}
+//# sourceMappingURL=resume-controller.js.map