@tokenfactory/acc-runner 0.40.24 → 0.40.26

package/dist/chat-poll/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * CHAT-HYGIENE AC2 — the companion/fleet DB-POLL FALLBACK
+ * for chat turn discovery.
+ *
+ * WHY THIS EXISTS. A companion (chat-companion.ts) / fleet lane
+ * (watch-chat/fleet-chat-lane.ts) discovers which conversations to serve from
+ * TWO Realtime-backed signals: the browser's `conversation_active` announce on
+ * the `identity:<user>` topic (companion.ts createConversationListener, FU-4)
+ * and the `chat:<conversation_id>` turn broadcasts. Both ride Supabase Realtime,
+ * which is BEST-EFFORT (no ack, no retry). During a Realtime DELIVERY BLACKOUT —
+ * a dropped socket, a Realtime outage, a missed announce — a freshly queued turn
+ * is never surfaced, so the companion never claims it and the operator's chat
+ * hangs with no reply (the 2026-07-21/22 incident shape).
+ *
+ * The claim PUMP already runs on its own interval, but it only claims across the
+ * conversations already in the served set — a conversation the blackout hid from
+ * discovery is never pumped. This module closes that gap with a discovery path
+ * that does NOT depend on Realtime at all: a heartbeat poller that queries the DB
+ * directly for the bound identity's OWNED conversations carrying a `queued` turn,
+ * and feeds them to a sink (in production: fold into the owner-affinity source +
+ * nudge the pump). It is the DB twin of the Realtime discovery signals — the
+ * safety net that guarantees a queued turn is served within one poll interval
+ * even with Realtime entirely dead.
+ *
+ * Pure primitive: every I/O seam (the DB query, the on-due sink, the clock) is
+ * injected, so the whole fallback is exercised deterministically
+ * (tests/unit/chat-hygiene, tests/e2e/chat-hygiene) with no network and no
+ * Supabase Realtime. Wiring it into `acc-runner companion` / `watch` is a
+ * follow-up (mirrors the FLEET-SERVE watch-chat primitives-then-wire split); the
+ * primitive + chaos proof land here.
+ */
+/** Env var that opts OUT of the DB-poll fallback (default: on). */
+export declare const CHAT_POLL_ENABLED_ENV = "ACC_RUNNER_CHAT_POLL";
+/** Env var carrying the DB-poll heartbeat cadence (ms). */
+export declare const CHAT_POLL_INTERVAL_MS_ENV = "ACC_RUNNER_CHAT_POLL_MS";
+/**
+ * Default poll cadence (ms). Sits in the same ~15-30s band as the companion's
+ * FU-10 rescan backstop: short enough that a Realtime-lost queued turn is
+ * served within a barely-perceptible delay, long enough that the bounded
+ * owner-affinity scan stays trivially cheap.
+ */
+export declare const DEFAULT_CHAT_POLL_INTERVAL_MS = 15000;
+/** Clamp bounds so a fat-fingered env can't hammer the DB or effectively disable the net. */
+export declare const MIN_CHAT_POLL_INTERVAL_MS = 2000;
+export declare const MAX_CHAT_POLL_INTERVAL_MS = 300000;
+/** The queued-turn status the fallback polls for (the only one the pump can act on). */
+export declare const CHAT_POLL_QUEUED_STATUS: "queued";
+/** Is the DB-poll fallback enabled? Disabled by `ACC_RUNNER_CHAT_POLL=0`. */
+export declare function chatPollEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve the poll cadence (ms). Blank/absent/non-numeric ⇒ default; a numeric
+ * value is clamped to [MIN, MAX] so a typo can neither DDoS the DB nor make the
+ * fallback effectively never fire.
+ */
+export declare function resolveChatPollIntervalMs(raw: string | undefined | null): number;
+/**
+ * Minimal structural shape of the Supabase client the poll query needs — the
+ * PostgREST query-builder chain used by companion.ts's backfill. A real
+ * RunnerSupabaseClient satisfies it; tests inject a recording fake.
+ */
+export interface ChatPollClient {
+    from(table: string): any;
+}
+export interface PollQueuedConversationsOpts {
+    /** Best-effort log sink. */
+    onLog?: (line: string) => void;
+    /** Override the queued-turn status filter (defaults to CHAT_POLL_QUEUED_STATUS). */
+    status?: string;
+}
+/**
+ * Query the DB for the conversations OWNED BY the bound user that currently have
+ * a `queued` chat turn — the Realtime-independent discovery read at the heart of
+ * the fallback.
+ *
+ * Owner-affinity: acc.chat_turns' SELECT policy is ORG-scoped (0254), so a
+ * candidate conversation_id may belong to a fellow org member. We re-confirm
+ * ownership against acc.chat_conversations (filtered to the bound user) exactly
+ * as backfillActiveConversations does, so a companion never surfaces — and never
+ * claims — another operator's conversation. Best-effort: any query error is
+ * logged and yields an empty result (the fallback is a safety net; it must never
+ * throw into the poll loop).
+ */
+export declare function pollQueuedConversations(client: ChatPollClient, boundUserId: string, opts?: PollQueuedConversationsOpts): Promise<string[]>;
+export interface ChatTurnPollerDeps {
+    /**
+     * Discover the conversation ids that currently have queued work for the bound
+     * identity — Realtime-independent. Typically
+     * `() => pollQueuedConversations(client, boundUserId, { onLog })`.
+     */
+    poll: () => Promise<string[]>;
+    /**
+     * Act on the discovered conversations: fold them into the served set and nudge
+     * the claim pump so their queued turns drain this interval. Best-effort — a
+     * throw is caught and logged; the next tick retries. Omit ⇒ discovery-only
+     * (the poller just reports what it found, for observability/tests).
+     */
+    onDue?: (conversationIds: string[]) => Promise<void> | void;
+    /** Poll cadence (ms). Default DEFAULT_CHAT_POLL_INTERVAL_MS; clamped to a sane floor. */
+    intervalMs?: number;
+    /** Best-effort log sink. */
+    onLog?: (line: string) => void;
+}
+/** The result of one poll pass, for observability + tests. */
+export interface ChatPollResult {
+    /** Conversation ids the DB reported as carrying queued work this pass. */
+    due: string[];
+    /** True when the onDue sink ran without throwing (or was absent). */
+    handled: boolean;
+}
+/**
+ * The DB-poll fallback loop. `pollOnce()` runs exactly one Realtime-independent
+ * discovery pass (query → onDue); `start()` schedules it on the heartbeat
+ * interval; `stop()` halts the loop. Single-flight: a slow pass can never stack
+ * on the next tick — an overlapping tick is coalesced. The whole loop is
+ * best-effort: a query or sink throw is caught + logged and the loop rides on,
+ * so the fallback can never crash the companion process.
+ */
+export declare class ChatTurnPoller {
+    private readonly deps;
+    private timer;
+    private stopped;
+    private polling;
+    private readonly intervalMs;
+    constructor(deps: ChatTurnPollerDeps);
+    /** Run one discovery pass. Best-effort + single-flight; never throws. */
+    pollOnce(): Promise<ChatPollResult>;
+    /** Start the heartbeat poll loop (does not block; timer is unref'd). */
+    start(): void;
+    /** Stop the loop. Idempotent. */
+    stop(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/chat-poll/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/chat-poll/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,yBAAyB,CAAC;AAC5D,2DAA2D;AAC3D,eAAO,MAAM,yBAAyB,4BAA4B,CAAC;AACnE;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AACpD,6FAA6F;AAC7F,eAAO,MAAM,yBAAyB,OAAQ,CAAC;AAC/C,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAEjD,wFAAwF;AACxF,eAAO,MAAM,uBAAuB,EAAG,QAAiB,CAAC;AAQzD,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAIhF;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAE7B,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,4BAA4B;IAC5B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,2BAAgC,GACrC,OAAO,CAAC,MAAM,EAAE,CAAC,CAoDnB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5D,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;IAMb,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAEP,IAAI,EAAE,kBAAkB;IAOrD,yEAAyE;IACnE,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC;IAmCzC,wEAAwE;IACxE,KAAK,IAAI,IAAI;IAWb,iCAAiC;IACjC,IAAI,IAAI,IAAI;CAOb"}

package/dist/chat-poll/index.js

@@ -0,0 +1,200 @@
+/**
+ * CHAT-HYGIENE AC2 — the companion/fleet DB-POLL FALLBACK
+ * for chat turn discovery.
+ *
+ * WHY THIS EXISTS. A companion (chat-companion.ts) / fleet lane
+ * (watch-chat/fleet-chat-lane.ts) discovers which conversations to serve from
+ * TWO Realtime-backed signals: the browser's `conversation_active` announce on
+ * the `identity:<user>` topic (companion.ts createConversationListener, FU-4)
+ * and the `chat:<conversation_id>` turn broadcasts. Both ride Supabase Realtime,
+ * which is BEST-EFFORT (no ack, no retry). During a Realtime DELIVERY BLACKOUT —
+ * a dropped socket, a Realtime outage, a missed announce — a freshly queued turn
+ * is never surfaced, so the companion never claims it and the operator's chat
+ * hangs with no reply (the 2026-07-21/22 incident shape).
+ *
+ * The claim PUMP already runs on its own interval, but it only claims across the
+ * conversations already in the served set — a conversation the blackout hid from
+ * discovery is never pumped. This module closes that gap with a discovery path
+ * that does NOT depend on Realtime at all: a heartbeat poller that queries the DB
+ * directly for the bound identity's OWNED conversations carrying a `queued` turn,
+ * and feeds them to a sink (in production: fold into the owner-affinity source +
+ * nudge the pump). It is the DB twin of the Realtime discovery signals — the
+ * safety net that guarantees a queued turn is served within one poll interval
+ * even with Realtime entirely dead.
+ *
+ * Pure primitive: every I/O seam (the DB query, the on-due sink, the clock) is
+ * injected, so the whole fallback is exercised deterministically
+ * (tests/unit/chat-hygiene, tests/e2e/chat-hygiene) with no network and no
+ * Supabase Realtime. Wiring it into `acc-runner companion` / `watch` is a
+ * follow-up (mirrors the FLEET-SERVE watch-chat primitives-then-wire split); the
+ * primitive + chaos proof land here.
+ */
+/** Env var that opts OUT of the DB-poll fallback (default: on). */
+export const CHAT_POLL_ENABLED_ENV = "ACC_RUNNER_CHAT_POLL";
+/** Env var carrying the DB-poll heartbeat cadence (ms). */
+export const CHAT_POLL_INTERVAL_MS_ENV = "ACC_RUNNER_CHAT_POLL_MS";
+/**
+ * Default poll cadence (ms). Sits in the same ~15-30s band as the companion's
+ * FU-10 rescan backstop: short enough that a Realtime-lost queued turn is
+ * served within a barely-perceptible delay, long enough that the bounded
+ * owner-affinity scan stays trivially cheap.
+ */
+export const DEFAULT_CHAT_POLL_INTERVAL_MS = 15_000;
+/** Clamp bounds so a fat-fingered env can't hammer the DB or effectively disable the net. */
+export const MIN_CHAT_POLL_INTERVAL_MS = 2_000;
+export const MAX_CHAT_POLL_INTERVAL_MS = 300_000;
+/** The queued-turn status the fallback polls for (the only one the pump can act on). */
+export const CHAT_POLL_QUEUED_STATUS = "queued";
+/** True when the value is a recognised falsy flag ("0"/"false"/"no"/"off"). */
+function isFalsyFlag(raw) {
+    const v = (raw ?? "").trim().toLowerCase();
+    return v === "0" || v === "false" || v === "no" || v === "off";
+}
+/** Is the DB-poll fallback enabled? Disabled by `ACC_RUNNER_CHAT_POLL=0`. */
+export function chatPollEnabled(env = process.env) {
+    return !isFalsyFlag(env[CHAT_POLL_ENABLED_ENV]);
+}
+/**
+ * Resolve the poll cadence (ms). Blank/absent/non-numeric ⇒ default; a numeric
+ * value is clamped to [MIN, MAX] so a typo can neither DDoS the DB nor make the
+ * fallback effectively never fire.
+ */
+export function resolveChatPollIntervalMs(raw) {
+    const n = Number.parseInt((raw ?? "").trim(), 10);
+    if (!Number.isFinite(n))
+        return DEFAULT_CHAT_POLL_INTERVAL_MS;
+    return Math.min(MAX_CHAT_POLL_INTERVAL_MS, Math.max(MIN_CHAT_POLL_INTERVAL_MS, n));
+}
+/**
+ * Query the DB for the conversations OWNED BY the bound user that currently have
+ * a `queued` chat turn — the Realtime-independent discovery read at the heart of
+ * the fallback.
+ *
+ * Owner-affinity: acc.chat_turns' SELECT policy is ORG-scoped (0254), so a
+ * candidate conversation_id may belong to a fellow org member. We re-confirm
+ * ownership against acc.chat_conversations (filtered to the bound user) exactly
+ * as backfillActiveConversations does, so a companion never surfaces — and never
+ * claims — another operator's conversation. Best-effort: any query error is
+ * logged and yields an empty result (the fallback is a safety net; it must never
+ * throw into the poll loop).
+ */
+export async function pollQueuedConversations(client, boundUserId, opts = {}) {
+    const status = opts.status ?? CHAT_POLL_QUEUED_STATUS;
+    try {
+        const turnsRes = await client
+            .from("chat_turns")
+            .select("conversation_id")
+            .eq("status", status);
+        if (turnsRes?.error) {
+            opts.onLog?.(`[acc-runner] chat-poll: chat_turns scan failed: ${turnsRes.error.message}`);
+            return [];
+        }
+        const turnRows = Array.isArray(turnsRes?.data) ? turnsRes.data : [];
+        const candidateIds = [
+            ...new Set(turnRows
+                .map((r) => {
+                const v = r?.conversation_id;
+                return typeof v === "string" ? v.trim() : "";
+            })
+                .filter((id) => id.length > 0)),
+        ];
+        if (candidateIds.length === 0)
+            return [];
+        const ownedRes = await client
+            .from("chat_conversations")
+            .select("id")
+            .eq("user_id", boundUserId)
+            .in("id", candidateIds);
+        if (ownedRes?.error) {
+            opts.onLog?.(`[acc-runner] chat-poll: ownership check failed: ${ownedRes.error.message}`);
+            return [];
+        }
+        const ownedRows = Array.isArray(ownedRes?.data) ? ownedRes.data : [];
+        return [
+            ...new Set(ownedRows
+                .map((r) => {
+                const v = r?.id;
+                return typeof v === "string" ? v.trim() : "";
+            })
+                .filter((id) => id.length > 0)),
+        ];
+    }
+    catch (err) {
+        opts.onLog?.(`[acc-runner] chat-poll query failed: ${err.message}`);
+        return [];
+    }
+}
+/**
+ * The DB-poll fallback loop. `pollOnce()` runs exactly one Realtime-independent
+ * discovery pass (query → onDue); `start()` schedules it on the heartbeat
+ * interval; `stop()` halts the loop. Single-flight: a slow pass can never stack
+ * on the next tick — an overlapping tick is coalesced. The whole loop is
+ * best-effort: a query or sink throw is caught + logged and the loop rides on,
+ * so the fallback can never crash the companion process.
+ */
+export class ChatTurnPoller {
+    deps;
+    timer = null;
+    stopped = false;
+    polling = false;
+    intervalMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.intervalMs = Math.max(MIN_CHAT_POLL_INTERVAL_MS, deps.intervalMs ?? DEFAULT_CHAT_POLL_INTERVAL_MS);
+    }
+    /** Run one discovery pass. Best-effort + single-flight; never throws. */
+    async pollOnce() {
+        if (this.stopped || this.polling)
+            return { due: [], handled: false };
+        this.polling = true;
+        try {
+            let due = [];
+            try {
+                due = await this.deps.poll();
+            }
+            catch (err) {
+                this.deps.onLog?.(`[acc-runner] chat-poll pass failed: ${err.message}`);
+                return { due: [], handled: false };
+            }
+            if (this.stopped)
+                return { due, handled: false };
+            if (due.length === 0 || !this.deps.onDue) {
+                return { due, handled: true };
+            }
+            try {
+                await this.deps.onDue(due);
+                this.deps.onLog?.(`[acc-runner] chat-poll fallback surfaced ${due.length} queued conversation(s) ` +
+                    `(Realtime-independent)`);
+                return { due, handled: true };
+            }
+            catch (err) {
+                this.deps.onLog?.(`[acc-runner] chat-poll onDue sink failed: ${err.message}`);
+                return { due, handled: false };
+            }
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    /** Start the heartbeat poll loop (does not block; timer is unref'd). */
+    start() {
+        if (this.timer || this.stopped)
+            return;
+        this.timer = setInterval(() => {
+            void this.pollOnce();
+        }, this.intervalMs);
+        this.timer.unref?.();
+        // Kick one immediate pass so a blackout in progress at startup self-heals
+        // without waiting a full interval.
+        void this.pollOnce();
+    }
+    /** Stop the loop. Idempotent. */
+    stop() {
+        this.stopped = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/chat-poll/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/chat-poll/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,sBAAsB,CAAC;AAC5D,2DAA2D;AAC3D,MAAM,CAAC,MAAM,yBAAyB,GAAG,yBAAyB,CAAC;AACnE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAC;AACpD,6FAA6F;AAC7F,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAC/C,MAAM,CAAC,MAAM,yBAAyB,GAAG,OAAO,CAAC;AAEjD,wFAAwF;AACxF,MAAM,CAAC,MAAM,uBAAuB,GAAG,QAAiB,CAAC;AAEzD,+EAA+E;AAC/E,SAAS,WAAW,CAAC,GAA8B;IACjD,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC;AACjE,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAA8B;IACtE,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,6BAA6B,CAAC;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,yBAAyB,EAAE,IAAI,CAAC,GAAG,CAAC,yBAAyB,EAAE,CAAC,CAAC,CAAC,CAAC;AACrF,CAAC;AAmBD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,MAAsB,EACtB,WAAmB,EACnB,OAAoC,EAAE;IAEtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,uBAAuB,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM;aAC1B,IAAI,CAAC,YAAY,CAAC;aAClB,MAAM,CAAC,iBAAiB,CAAC;aACzB,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACxB,IAAI,QAAQ,EAAE,KAAK,EAAE,CAAC;YACpB,IAAI,CAAC,KAAK,EAAE,CACV,mDAAmD,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAC5E,CAAC;YACF,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,QAAQ,GAAc,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,MAAM,YAAY,GAAG;YACnB,GAAG,IAAI,GAAG,CACR,QAAQ;iBACL,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACT,MAAM,CAAC,GAAI,CAA0C,EAAE,eAAe,CAAC;gBACvE,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,CAAC,CAAC;iBACD,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CACjC;SACF,CAAC;QACF,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAEzC,MAAM,QAAQ,GAAG,MAAM,MAAM;aAC1B,IAAI,CAAC,oBAAoB,CAAC;aAC1B,MAAM,CAAC,IAAI,CAAC;aACZ,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC;aAC1B,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAC1B,IAAI,QAAQ,EAAE,KAAK,EAAE,CAAC;YACpB,IAAI,CAAC,KAAK,EAAE,CACV,mDAAmD,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAC5E,CAAC;YACF,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,SAAS,GAAc,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,OAAO;YACL,GAAG,IAAI,GAAG,CACR,SAAS;iBACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACT,MAAM,CAAC,GAAI,CAA6B,EAAE,EAAE,CAAC;gBAC7C,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,CAAC,CAAC;iBACD,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CACjC;SACF,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,KAAK,EAAE,CAAC,wCAAyC,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/E,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AA8BD;;;;;;;GAOG;AACH,MAAM,OAAO,cAAc;IAMI;IALrB,KAAK,GAA0C,IAAI,CAAC;IACpD,OAAO,GAAG,KAAK,CAAC;IAChB,OAAO,GAAG,KAAK,CAAC;IACP,UAAU,CAAS;IAEpC,YAA6B,IAAwB;QAAxB,SAAI,GAAJ,IAAI,CAAoB;QACnD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CACxB,yBAAyB,EACzB,IAAI,CAAC,UAAU,IAAI,6BAA6B,CACjD,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,QAAQ;QACZ,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACrE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC;YACH,IAAI,GAAG,GAAa,EAAE,CAAC;YACvB,IAAI,CAAC;gBACH,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CACf,uCAAwC,GAAa,CAAC,OAAO,EAAE,CAChE,CAAC;gBACF,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YACrC,CAAC;YACD,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YACjD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACzC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAChC,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBAC3B,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CACf,4CAA4C,GAAG,CAAC,MAAM,0BAA0B;oBAC9E,wBAAwB,CAC3B,CAAC;gBACF,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAChC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CACf,6CAA8C,GAAa,CAAC,OAAO,EAAE,CACtE,CAAC;gBACF,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YACjC,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,KAAK;QACH,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACvC,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;QACvB,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACpB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QACrB,0EAA0E;QAC1E,mCAAmC;QACnC,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;IACvB,CAAC;IAED,iCAAiC;IACjC,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;CACF"}

package/dist/doctor.d.ts

@@ -125,8 +125,9 @@ export interface DoctorOptions {
     /**
      * Treat advisory WARN outcomes as hard failures. Used by
      * `scripts/provision-runner.sh` and CI so a runner only reports healthy when
-     * the environment is fully green — no missing ANTHROPIC_API_KEY, no stale
-     * binary, no claude/version drift, no unconfirmable foreign watch process.
+     * the environment is fully green — subscription/BYOK serving auth resolved
+     * (REVIEW-SUBS), no stale binary, no claude/version drift, no unconfirmable
+     * foreign watch process.
      * Off by default so interactive `doctor` stays lenient about advisories.
      */
     strict?: boolean;

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAEL,KAAK,oBAAoB,EAUzB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAiBrB,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AAKpC,eAAO,MAAM,aAAa,gCAAgC,CAAC;AAC3D,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,YAAY,EAAE,MAAM,CAYxD,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,YAAY,EAAE,MAAM,CAY5D,CAAC;AAoEF,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAkFD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,KAAK,GAAE,MAAM,OAAO,CAAC,qBAAqB,CAAgD,GACzF,OAAO,CAAC,YAAY,CAAC,CAsBvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,CAAC,CA+B9D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1C;AAED,wBAAsB,oBAAoB,CAAC,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWzF;AA0FD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,YAAY,CAAC,CA8D3D;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAMhF;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,oBAAoB,GAAG,IAAI,GACrC,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAmOD,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC/C;AAED,wBAAsB,cAAc,CAClC,GAAG,EAAE,YAAY,GAAG,IAAI,EACxB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,YAAY,CAAC,CA+CvB;AAQD,wBAAsB,oBAAoB,CACxC,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,YAAY,CAAC,CA4BvB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,YAAY,GAAG,IAAI,GACvB,OAAO,CAAC,YAAY,CAAC,CAevB;AAED,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC/C;AAED,wBAAsB,gBAAgB,CACpC,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,YAAY,CAAC,CA6BvB;AAiGD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAuFtF;AAgBD,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAmF1F;AAkED,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IAC5C;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAiBD,wBAAsB,aAAa,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0FhF"}

package/dist/doctor.js

@@ -9,7 +9,7 @@ import path from "node:path";
 import { execa } from "execa";
 import chalk from "chalk";
 import { buildEnv } from "./bin-resolve.js";
-import { resolveAuthMode, describeAuthMode, authPrecedenceHint } from "./provider-auth.js";
+import { authPrecedenceHint, servingAuthKind, describeServingAuthKind, anthropicApiKey, forwardsAmbientKey, } from "./provider-auth.js";
 import { openaiApiKey, openaiApiKeyFromKeychain, describeCodexAuthMode, } from "./provider-auth.js";
 import { codexEngineEnabled, resolveCodexSpawnMode } from "./engines/codex.js";
 import { claudeCodeEngine } from "./engines/claude-code.js";
@@ -148,29 +148,50 @@ async function checkClaude() {
     };
 }
 /**
- * v0.74-B (T-1780800000740201): advisory check that ANTHROPIC_API_KEY is set.
- * When present, spawned claude sessions authenticate via the API account,
- * which has no per-session cap. When absent claude falls back to the
- * operator's interactive OAuth session, which is subject to 429 session caps
- * during long autonomous runs — worth flagging but not a hard environment
- * failure, so this is a WARN (advisory, never fails the doctor exit code).
+ * Report how spawned claude sessions will authenticate, under the
+ * subscription-only serving policy. NO ambient API-key billing: a host
+ * ANTHROPIC_API_KEY is forwarded to a spawn ONLY when the serving identity is
+ * BYOK `api_key`; otherwise it is stripped and the session serves on the
+ * operator's subscription OAuth login. So a MISSING key is now the healthy
+ * default, not a warning — the advice is `claude login`, never "export a key".
  */
 async function checkAnthropicKey() {
-    const mode = resolveAuthMode();
-    if (mode === "api-key") {
-        const hint = authPrecedenceHint();
+    const kind = servingAuthKind();
+    const keyPresent = !!anthropicApiKey();
+    const name = "Anthropic serving auth";
+    if (forwardsAmbientKey()) {
+        // BYOK api_key identity: the host key IS forwarded. Missing key = misconfig.
+        if (keyPresent) {
+            const hint = authPrecedenceHint();
+            return {
+                name,
+                ok: true,
+                detail: hint
+                    ? `${describeServingAuthKind(kind)} — ${hint}`
+                    : describeServingAuthKind(kind),
+            };
+        }
         return {
-            name: "ANTHROPIC_API_KEY set",
-            ok: true,
-            detail: hint ? `${describeAuthMode(mode)} — ${hint}` : describeAuthMode(mode),
+            name,
+            ok: false,
+            warn: true,
+            detail: `${describeServingAuthKind(kind)} but no ANTHROPIC_API_KEY present`,
+            fix: "this runner serves a BYOK api_key identity — ensure the v9 broker delivers ANTHROPIC_API_KEY, or switch the identity to subscription serving.",
         };
     }
+    // Subscription-first (the desired default). A missing key is correct; a
+    // present-but-stripped key is noted so the operator knows it is NOT billed.
     return {
-        name: "ANTHROPIC_API_KEY set",
-        ok: false,
-        warn: true,
-        detail: describeAuthMode(mode),
-        fix: "export ANTHROPIC_API_KEY=sk-ant-… so spawned claude sessions bill against the API account and avoid 429 session caps.",
+        name,
+        ok: true,
+        detail: keyPresent
+            ? `${describeServingAuthKind(kind)}; a host ANTHROPIC_API_KEY is present but will be STRIPPED from spawns (not billed)`
+            : describeServingAuthKind(kind),
+        ...(keyPresent
+            ? {
+                fix: "a stray ANTHROPIC_API_KEY is set but ignored under subscription-only serving; unset it to avoid confusion. Run `claude login` if the subscription session ever lapses.",
+            }
+            : {}),
     };
 }
 /**
@@ -195,7 +216,7 @@ export async function checkChatAuth(probe = () => claudeCodeChatEngine.credentia
             ok: false,
             warn: true,
             detail: `chat lane unavailable — ${result.detail}`,
-            fix: "export ANTHROPIC_API_KEY=sk-ant-… or run an interactive `claude` login so the chat lane can serve turns.",
+            fix: "run an interactive `claude` login so the chat lane can serve turns on the operator's subscription (REVIEW-SUBS: ambient ANTHROPIC_API_KEY is no longer used).",
         };
     }
     const draftOnly = result.tier === "draft-only";