@teamvibe/poller 0.8.2-rc.1 → 0.8.3-rc.2

package/dist/pool-telemetry.js

@@ -0,0 +1,107 @@
+import { emitEvent } from './event-queue.js';
+import { normalizePassiveUsage, reactiveEligibleAt, } from './subscription-selection.js';
+import { safeQuota, safeRateLimitInfo, } from './subscription-usage-store.js';
+function safeText(value) {
+    return value && value.length <= 128 && !/sk-ant-|Bearer\s|[\r\n]/i.test(value)
+        ? value
+        : undefined;
+}
+function safeMetrics(metrics) {
+    if (!metrics)
+        return undefined;
+    const result = {};
+    for (const key of [
+        'total_cost_usd',
+        'input_tokens',
+        'output_tokens',
+        'cache_read_input_tokens',
+        'cache_creation_input_tokens',
+        'duration_ms',
+        'duration_api_ms',
+        'num_turns',
+    ]) {
+        const value = metrics[key];
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+            result[key] = value;
+    }
+    const model = safeText(metrics.model);
+    if (model)
+        result.model = model;
+    return result;
+}
+/** Explicit transport DTO: never serialize a pool account/credential envelope. */
+export function accountUsageTelemetry(account, state) {
+    const passive = state.passive
+        ? normalizePassiveUsage(state.passive.rateLimitInfo, state.passive.observedAt)
+        : undefined;
+    const probe = state.probe?.usage;
+    const usage = passive && (!probe || passive.observedAt >= probe.observedAt)
+        ? passive
+        : probe;
+    return {
+        accountId: account.accountId,
+        accountLabel: account.label ?? account.accountId,
+        reportedAt: Date.now(),
+        ...(usage ? { usage } : {}),
+        ...(state.probe
+            ? {
+                probeStatus: state.probe.status,
+                probeObservedAt: state.probe.observedAt,
+            }
+            : {}),
+        ...(state.passive
+            ? { lastRateLimitInfo: state.passive.rateLimitInfo }
+            : {}),
+        reactive: state.reactive.map((r) => ({
+            observedAt: r.observedAt,
+            window: r.quota.window,
+            scope: r.quota.modelScope ?? 'global',
+            resetAt: r.quota.resetAt ? Date.parse(r.quota.resetAt) : undefined,
+            eligibleAt: reactiveEligibleAt(r),
+        })),
+    };
+}
+export async function emitCandidateUsage(msg, accounts, store) {
+    // Usage storage is already local. Observability failures never change selection.
+    for (const account of accounts) {
+        try {
+            emitEvent('pool.usage_observed', msg.teamvibe.channelId, {
+                workspaceId: msg.teamvibe.workspaceId,
+                ...accountUsageTelemetry(account, await store.read(account)),
+            });
+        }
+        catch { }
+    }
+}
+export function poolRunTelemetry(attempts, quotaDeferEpisodes = 0) {
+    const safeAttempts = attempts.map((a) => ({
+        accountId: a.accountId,
+        accountLabel: safeText(a.accountLabel) ?? a.accountId,
+        sessionId: safeText(a.sessionId),
+        model: safeText(a.model),
+        success: a.success,
+        exitCode: a.exitCode,
+        observedAt: a.observedAt,
+        quota: a.quota ? safeQuota(a.quota) : undefined,
+        metrics: safeMetrics(a.metrics),
+        lastRateLimitInfo: a.rateLimitInfo
+            ? safeRateLimitInfo(a.rateLimitInfo)
+            : undefined,
+    }));
+    const last = safeAttempts.at(-1);
+    return {
+        ...(last
+            ? {
+                accountId: last.accountId,
+                accountLabel: last.accountLabel,
+                model: last.model,
+                observedAt: last.observedAt,
+                lastRateLimitInfo: last.lastRateLimitInfo,
+            }
+            : {}),
+        chainLength: attempts.length,
+        switchedAccounts: new Set(attempts.map((a) => a.accountId)).size > 1,
+        quotaDeferEpisodes,
+        attempts: safeAttempts,
+    };
+}

package/dist/quota-pause.d.ts

@@ -0,0 +1,16 @@
+import type { ClaudeQuotaFailure } from './claude-quota.js';
+export declare const UNKNOWN_QUOTA_RECHECK_MS: number;
+export declare class QuotaPausedError extends Error {
+    constructor();
+}
+export interface QuotaPause {
+    createdAt: number;
+    resumeAt: number;
+    brainPath: string;
+    threadId: string;
+}
+export declare function readQuotaPause(): QuotaPause | undefined;
+export declare function isQuotaPaused(): boolean;
+/** Persist before notification; only the first quota result owns the notice. */
+export declare function pauseForQuota(quota: ClaudeQuotaFailure, brainPath: string, threadId: string): boolean;
+export declare function clearQuotaPauseAfterSuccess(): void;

package/dist/quota-pause.js

@@ -0,0 +1,96 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { config } from './config.js';
+import { logger } from './logger.js';
+export const UNKNOWN_QUOTA_RECHECK_MS = 15 * 60_000;
+export class QuotaPausedError extends Error {
+    constructor() {
+        super('Claude account is paused for quota');
+    }
+}
+// The ambient credential path retains the original poller-wide pause.
+// Configured subscription pools use per-account usage and per-thread pool-defer.
+function markerPath() {
+    return join(config.TEAMVIBE_DATA_DIR, 'quota-pause.json');
+}
+const unreadableMarkers = new Set();
+const cleanupFailures = new Set();
+export function readQuotaPause() {
+    const path = markerPath();
+    try {
+        const pause = JSON.parse(readFileSync(path, 'utf8'));
+        if (pause && Number.isFinite(pause.createdAt) && Number.isFinite(pause.resumeAt)
+            && Number.isFinite(pause.resumeAt - pause.createdAt) && pause.resumeAt > pause.createdAt
+            && typeof pause.brainPath === 'string' && typeof pause.threadId === 'string') {
+            unreadableMarkers.delete(path);
+            return pause;
+        }
+        throw new Error('Invalid quota pause marker');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            unreadableMarkers.delete(path);
+            return undefined;
+        }
+        if (!unreadableMarkers.has(path)) {
+            unreadableMarkers.add(path);
+            logger.warn('[QuotaPause] Unreadable marker treated as expired', error instanceof Error ? error.message : String(error));
+        }
+        try {
+            rmSync(path, { recursive: true, force: true });
+        }
+        catch {
+            // A directory or unreadable file can still be moved out of the way.
+            // Cleanup failure must never stop the watcher from resuming saved work.
+            try {
+                renameSync(path, `${path}.invalid`);
+            }
+            catch { }
+        }
+        return undefined;
+    }
+}
+export function isQuotaPaused() {
+    const pause = readQuotaPause();
+    if (!pause)
+        return false;
+    const now = Date.now();
+    // A backward clock correction must not extend the original pause duration.
+    const bound = pause.resumeAt - pause.createdAt;
+    return now >= pause.createdAt && now < pause.resumeAt && pause.resumeAt - now <= bound;
+}
+/** Persist before notification; only the first quota result owns the notice. */
+export function pauseForQuota(quota, brainPath, threadId) {
+    if (isQuotaPaused())
+        return false;
+    const now = Date.now();
+    const reset = quota.resetAt ? Date.parse(quota.resetAt) : NaN;
+    const pause = {
+        createdAt: now,
+        resumeAt: Number.isFinite(reset) && reset > now ? reset : now + UNKNOWN_QUOTA_RECHECK_MS,
+        brainPath,
+        threadId,
+    };
+    mkdirSync(config.TEAMVIBE_DATA_DIR, { recursive: true });
+    const path = markerPath();
+    writeFileSync(`${path}.tmp`, JSON.stringify(pause), { mode: 0o600 });
+    renameSync(`${path}.tmp`, path);
+    return true;
+}
+export function clearQuotaPauseAfterSuccess() {
+    // An already-running request may succeed after another thread exhausted the
+    // account. Its success must not erase that thread's newly active pause.
+    const path = markerPath();
+    try {
+        if (!isQuotaPaused()) {
+            rmSync(path, { recursive: true, force: true });
+            cleanupFailures.delete(path);
+        }
+    }
+    catch (error) {
+        if (!unreadableMarkers.has(path) && !cleanupFailures.has(path)) {
+            cleanupFailures.add(path);
+            logger.warn('[QuotaPause] Marker cleanup failed after success', error instanceof Error ? error.message : String(error));
+        }
+    }
+}

package/dist/session-store.d.ts

@@ -1,4 +1,4 @@
-import type { SessionRecord, SessionStatus } from './types.js';
+import type { SessionRecord, SessionStatus, SubscriptionPin } from './types.js';
 export declare function getSession(threadId: string): Promise<SessionRecord | null>;
 export declare function createSession(threadId: string, workspacePath: string): Promise<SessionRecord>;
 export interface AcquireLockResult {
@@ -7,6 +7,6 @@ export interface AcquireLockResult {
     lockToken: string | null;
 }
 export declare function acquireSessionLock(threadId: string, workspacePath: string): Promise<AcquireLockResult>;
-export declare function updateSessionId(threadId: string, lockToken: string, newSessionId: string): Promise<void>;
+export declare function updateSessionId(threadId: string, lockToken: string, newSessionId: string, pin?: SubscriptionPin): Promise<boolean>;
 export declare function releaseSessionLock(threadId: string, lockToken: string, newStatus?: SessionStatus, lastMessageTs?: string): Promise<void>;
 export declare function forceReleaseStalelock(threadId: string, maxAgeMs: number): Promise<boolean>;

package/dist/session-store.js

@@ -43,6 +43,7 @@ function generateLockToken() {
 export async function getSession(threadId) {
     const key = buildKey(threadId);
     const result = await createDocClient().send(new GetCommand({
+        ConsistentRead: true,
         TableName: getTableName(),
         Key: key,
     }));
@@ -149,25 +150,27 @@ export async function acquireSessionLock(threadId, workspacePath) {
         throw error;
     }
 }
-export async function updateSessionId(threadId, lockToken, newSessionId) {
+export async function updateSessionId(threadId, lockToken, newSessionId, pin) {
     try {
         await createDocClient().send(new UpdateCommand({
             TableName: getTableName(),
             Key: buildKey(threadId),
-            UpdateExpression: 'SET session_id = :newSessionId',
+            UpdateExpression: pin ? 'SET session_id = :newSessionId, subscription_pin = :pin' : 'SET session_id = :newSessionId',
             ConditionExpression: 'lock_token = :lockToken',
             ExpressionAttributeValues: {
                 ':newSessionId': newSessionId,
+                ...(pin ? { ':pin': Object.fromEntries(Object.entries(pin).filter(([, value]) => value !== undefined)) } : {}),
                 ':lockToken': lockToken,
             },
         }));
         logger.info(`Updated session_id for thread ${threadId} to ${newSessionId}`);
+        return true;
     }
     catch (error) {
         if (error.name === 'ConditionalCheckFailedException') {
             logger.warn(`Lock token mismatch when updating session_id for ${threadId}`);
             emitError('session', `Lock token mismatch when updating session_id for ${threadId}`, { severity: 'warn' });
-            return;
+            return false;
         }
         throw error;
     }

package/dist/slack-client.d.ts

@@ -3,7 +3,10 @@ export declare function getUserInfo(botToken: string, userId: string): Promise<{
     name: string;
     realName: string;
 }>;
-export declare function sendSlackMessage(msg: TeamVibeQueueMessage, text: string): Promise<void>;
+export declare function sendSlackMessage(msg: TeamVibeQueueMessage, text: string, options?: {
+    clientMessageId: string;
+    reconcile?: boolean;
+}): Promise<void>;
 export declare function sendSlackError(msg: TeamVibeQueueMessage, error: string): Promise<void>;
 export declare function addReaction(msg: TeamVibeQueueMessage, emoji: string): Promise<void>;
 export declare function setThreadStatus(msg: TeamVibeQueueMessage, status: string): Promise<void>;

package/dist/slack-client.js

@@ -1,10 +1,13 @@
 import { WebClient } from '@slack/web-api';
 import { logger } from './logger.js';
 import { emitError } from './event-queue.js';
+import { config } from './config.js';
 // Cache user info to avoid repeated API calls
 const userCache = new Map();
 // Per-token Slack client cache
 const slackClients = new Map();
+// Slack: "must be less than 51 characters [json-pointer:/loading_messages/0]"
+const SLACK_LOADING_MESSAGE_MAX = 50;
 function getSlackClient(botToken) {
     let client = slackClients.get(botToken);
     if (!client) {
@@ -42,19 +45,37 @@ export async function getUserInfo(botToken, userId) {
     userCache.set(userId, fallback);
     return fallback;
 }
-export async function sendSlackMessage(msg, text) {
+export async function sendSlackMessage(msg, text, options) {
     if (!msg.response_context.slack) {
         logger.error('No Slack context in message, cannot respond');
         return;
     }
     const { channel, thread_ts } = msg.response_context.slack;
     const slack = getSlackClient(msg.teamvibe.botToken);
+    if (options?.reconcile) {
+        let cursor;
+        // A claim may have reached Slack before the process/connection died.
+        // Reconcile by stable episode ID; absence or read failure never reposts it.
+        for (let page = 0; page < 20; page++) {
+            const response = await slack.conversations.replies({ channel, ts: thread_ts, limit: 100, cursor, include_all_metadata: true });
+            if (response.messages?.some(message => {
+                const payload = message.metadata?.event_payload;
+                return ('client_msg_id' in message && message.client_msg_id === options.clientMessageId) || (payload !== null && typeof payload === 'object' && 'episodeId' in payload && payload.episodeId === options.clientMessageId);
+            }))
+                return;
+            cursor = response.response_metadata?.next_cursor;
+            if (!cursor)
+                break;
+        }
+        throw new Error('Pool notice delivery remains unresolved');
+    }
     await slack.chat.postMessage({
         channel,
         thread_ts,
         text,
         unfurl_links: false,
         unfurl_media: false,
+        ...(options ? { client_msg_id: options.clientMessageId, metadata: { event_type: 'subscription_pool_defer', event_payload: { episodeId: options.clientMessageId } } } : {}),
     });
 }
 export async function sendSlackError(msg, error) {
@@ -95,25 +116,59 @@ export async function setThreadStatus(msg, status) {
     const { channel, thread_ts } = msg.response_context.slack;
     const slack = getSlackClient(msg.teamvibe.botToken);
     const safeStatus = neutralizeSlackMarkup(status);
+    const payload = {
+        channel_id: channel,
+        thread_ts,
+        status: safeStatus,
+    };
     try {
         await slack.apiCall('assistant.threads.setStatus', {
-            channel_id: channel,
-            thread_ts,
-            status: safeStatus,
-            ...(safeStatus ? { loading_messages: [safeStatus] } : {}),
+            ...payload,
+            ...(safeStatus ? { loading_messages: [truncateLoadingMessage(safeStatus)] } : {}),
         });
     }
-    catch {
+    catch (error) {
+        const messages = error?.data?.response_metadata?.messages;
+        const details = [error?.message, ...(Array.isArray(messages) ? messages : [])].join(' ');
+        if (safeStatus && error?.data?.error === 'invalid_arguments' && details.includes('loading_messages')) {
+            // API errors may echo request fields; never log the error or status.
+            logger.warn('Slack rejected loading messages; retrying thread status');
+            try {
+                await slack.apiCall('assistant.threads.setStatus', payload);
+                return;
+            }
+            catch {
+                emitError('slack', 'Failed to set thread status', { severity: 'warn' });
+                return;
+            }
+        }
         // API errors may echo request fields; status can contain private narration.
         logger.warn('Failed to set thread status');
         emitError('slack', `Failed to set thread status`, { severity: 'warn' });
     }
 }
+function truncateLoadingMessage(text) {
+    // Treat escaped markup as whole tokens so truncation never leaves a partial entity.
+    const tokens = text.match(/&(?:lt|gt|amp);|[\s\S]/gu) ?? [];
+    if (text.length <= SLACK_LOADING_MESSAGE_MAX)
+        return text;
+    let result = '';
+    for (const token of tokens) {
+        if (result.length + token.length >= SLACK_LOADING_MESSAGE_MAX)
+            break;
+        result += token;
+    }
+    return result + '…';
+}
 function neutralizeSlackMarkup(text) {
     return text.replace(/[<>&]/g, (character) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;' })[character]);
 }
 export function startTypingIndicator(msg, statusText = 'Thinking...') {
     let currentStatus = statusText;
+    let currentSource = statusText === 'Thinking...' ? 'default' : 'comment';
+    let commentShownAt = currentSource === 'comment' ? Date.now() : 0;
+    let pendingCanned = null;
+    let holdTimer;
     let stopped = false;
     const logStatus = (status, source) => {
         if (!status)
@@ -122,8 +177,25 @@ export function startTypingIndicator(msg, statusText = 'Thinking...') {
             logger.info(`[Typing] status -> ${source} (${status.length} chars)`);
     };
     // Set initial status
-    logStatus(currentStatus, statusText === 'Thinking...' ? 'default' : 'comment');
+    logStatus(currentStatus, currentSource);
     setThreadStatus(msg, currentStatus);
+    const cancelHold = () => {
+        if (holdTimer !== undefined)
+            clearTimeout(holdTimer);
+        holdTimer = undefined;
+        pendingCanned = null;
+    };
+    const showStatus = (text, source) => {
+        const changed = text !== currentStatus;
+        currentStatus = text;
+        currentSource = text ? source : 'default';
+        if (text && source === 'comment')
+            commentShownAt = Date.now();
+        if (changed) {
+            logStatus(text, source);
+            setThreadStatus(msg, text);
+        }
+    };
     // Keepalive every 3 seconds (Slack clears after ~2 min timeout)
     let failures = 0;
     const interval = setInterval(async () => {
@@ -142,16 +214,33 @@ export function startTypingIndicator(msg, statusText = 'Thinking...') {
         updateStatus: (newStatus, source = 'comment') => {
             if (stopped)
                 return;
-            if (newStatus !== currentStatus) {
-                currentStatus = newStatus;
-                logStatus(currentStatus, source);
-                setThreadStatus(msg, currentStatus);
+            if (!newStatus || source === 'comment') {
+                cancelHold();
+                showStatus(newStatus, source);
+                return;
+            }
+            const remainingHold = config.TYPING_COMMENT_MIN_HOLD_MS - (Date.now() - commentShownAt);
+            if (currentSource === 'comment' && remainingHold > 0) {
+                pendingCanned = { text: newStatus, source };
+                if (holdTimer === undefined) {
+                    holdTimer = setTimeout(() => {
+                        holdTimer = undefined;
+                        const pending = pendingCanned;
+                        pendingCanned = null;
+                        if (!stopped && pending)
+                            showStatus(pending.text, pending.source);
+                    }, remainingHold);
+                }
+                return;
             }
+            cancelHold();
+            showStatus(newStatus, source);
         },
         stop: () => {
             if (stopped)
                 return;
             stopped = true;
+            cancelHold();
             clearInterval(interval);
             if (currentStatus)
                 logStatus('', 'default');

package/dist/subscription-pool-client.d.ts

@@ -0,0 +1,32 @@
+import type { AccountIdentity, PoolFetchResult } from './subscription-selection.js';
+/** Unwrap only at the optional Claude probe or future child-spawn boundary. */
+export declare class SubscriptionCredential {
+    #private;
+    constructor(token: string);
+    unwrap(): string;
+    toJSON(): string;
+    toString(): string;
+}
+export interface SubscriptionAccount extends AccountIdentity {
+    harness: 'CLAUDE';
+    label?: string;
+    credential: SubscriptionCredential;
+}
+export interface PoolFetchInput {
+    workspaceId: string;
+    channelId: string;
+    pollerId: string;
+}
+export interface PoolClientOptions {
+    apiUrl: string;
+    pollerToken: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/** Deadline covers response headers AND body, even for an uncooperative adapter. */
+export declare function boundedRequest<T>(work: (signal: AbortSignal) => Promise<T>, signal?: AbortSignal, timeoutMs?: number): Promise<T>;
+/** Bounded, ephemeral raw body. Neither it nor caught errors leave this module. */
+export declare function readSubscriptionJson(response: Response): Promise<unknown>;
+/** No global config, logging, workspace fallback or credential cache. */
+export declare function fetchSubscriptionPool(input: PoolFetchInput, options: PoolClientOptions): Promise<PoolFetchResult<SubscriptionAccount>>;

package/dist/subscription-pool-client.js

@@ -0,0 +1,139 @@
+import { record } from './subscription-selection.js';
+/** Unwrap only at the optional Claude probe or future child-spawn boundary. */
+export class SubscriptionCredential {
+    #token;
+    constructor(token) { this.#token = token; }
+    unwrap() { return this.#token; }
+    toJSON() { return '[REDACTED]'; }
+    toString() { return '[SubscriptionCredential REDACTED]'; }
+    [Symbol.for('nodejs.util.inspect.custom')]() { return this.toString(); }
+}
+/** Deadline covers response headers AND body, even for an uncooperative adapter. */
+export async function boundedRequest(work, signal, timeoutMs = 15_000) {
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    signal?.addEventListener('abort', cancel, { once: true });
+    const timer = setTimeout(cancel, timeoutMs);
+    if (signal?.aborted)
+        cancel();
+    let onAbort = () => { };
+    try {
+        return await Promise.race([
+            new Promise((_, reject) => {
+                onAbort = () => reject(new Error('Subscription request interrupted'));
+                controller.signal.addEventListener('abort', onAbort, { once: true });
+                if (controller.signal.aborted)
+                    onAbort();
+            }),
+            Promise.resolve().then(() => {
+                if (controller.signal.aborted)
+                    throw new Error('Subscription request interrupted');
+                return work(controller.signal);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', cancel);
+        controller.signal.removeEventListener('abort', onAbort);
+    }
+}
+/** Bounded, ephemeral raw body. Neither it nor caught errors leave this module. */
+export async function readSubscriptionJson(response) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Invalid subscription response');
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > 1024 * 1024)
+                throw new Error('Subscription response too large');
+            chunks.push(chunk.value);
+        }
+        const bytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+}
+/** No global config, logging, workspace fallback or credential cache. */
+export async function fetchSubscriptionPool(input, options) {
+    let url;
+    try {
+        if (!input.pollerId || !input.workspaceId || !input.channelId || !options.pollerToken)
+            throw new Error('Missing configuration');
+        url = new URL('/subscription-accounts/spawn', options.apiUrl);
+        if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+            throw new Error('Invalid URL');
+        url.searchParams.set('pollerId', input.pollerId);
+        url.searchParams.set('workspaceId', input.workspaceId);
+        url.searchParams.set('channelId', input.channelId);
+    }
+    catch {
+        return { kind: 'fetch_unavailable', reason: 'configuration' };
+    }
+    try {
+        return await boundedRequest(async (signal) => {
+            const response = await (options.fetch ?? fetch)(url, {
+                method: 'GET', signal,
+                headers: { Authorization: `Bearer ${options.pollerToken}`, 'Cache-Control': 'no-store' },
+                redirect: 'error',
+            });
+            if (response.status === 401 || response.status === 403)
+                return { kind: 'fetch_unauthorized', status: response.status };
+            if (!response.ok)
+                return { kind: 'fetch_unavailable', reason: 'http', status: response.status };
+            let body;
+            try {
+                body = await readSubscriptionJson(response);
+            }
+            catch {
+                return { kind: 'fetch_unavailable', reason: 'invalid_response' };
+            }
+            const envelope = record(body);
+            const raw = envelope['accounts'];
+            if (!Array.isArray(raw) || raw.length > 1000)
+                return { kind: 'fetch_unavailable', reason: 'invalid_response' };
+            const poolConfigured = envelope['poolConfigured'];
+            if (('poolConfigured' in envelope && typeof poolConfigured !== 'boolean') ||
+                (poolConfigured === false && raw.length > 0))
+                return { kind: 'fetch_unavailable', reason: 'invalid_response' };
+            const accounts = [];
+            const ids = new Set();
+            for (const value of raw) {
+                const item = record(value);
+                const credential = record(item['credential']);
+                if (typeof item['accountId'] !== 'string' || !item['accountId'] || ids.has(item['accountId']) ||
+                    item['workspaceId'] !== input.workspaceId || item['enabled'] !== true || item['harness'] !== 'CLAUDE' ||
+                    typeof item['credentialVersion'] !== 'string' || !item['credentialVersion'] ||
+                    credential['type'] !== 'claude-setup-token' || typeof credential['token'] !== 'string' || !credential['token']) {
+                    return { kind: 'fetch_unavailable', reason: 'invalid_response' };
+                }
+                ids.add(item['accountId']);
+                accounts.push({ accountId: item['accountId'], workspaceId: input.workspaceId, credentialVersion: item['credentialVersion'], enabled: true, harness: 'CLAUDE', ...(typeof item['label'] === 'string' && item['label'].length <= 128 && !/sk-ant-|Bearer\s|[\r\n]/i.test(item['label']) ? { label: item['label'] } : {}), credential: new SubscriptionCredential(credential['token']) });
+            }
+            if (accounts.length)
+                return { kind: 'ready', accounts };
+            if (poolConfigured === false)
+                return { kind: 'no_accounts_configured' };
+            if (poolConfigured === true)
+                return { kind: 'fetch_unavailable', reason: 'no_usable_accounts' };
+            // Older platforms cannot distinguish an absent pool from disabled members.
+            return { kind: 'unknown_pool_state' };
+        }, options.signal, options.timeoutMs);
+    }
+    catch {
+        return { kind: 'fetch_unavailable', reason: options.signal?.aborted ? 'cancelled' : 'network' };
+    }
+}

package/dist/subscription-pool.d.ts

@@ -0,0 +1,18 @@
+import type { resolveModel } from './claude-spawner.js';
+import { type AccountIdentity, type PoolFetchResult, type SelectionOutcome } from './subscription-selection.js';
+import { type SubscriptionUsageStore } from './subscription-usage-store.js';
+export type ResolvedPoolModel = ReturnType<typeof resolveModel>;
+export type ResolvedPoolSelection<A extends AccountIdentity> = (SelectionOutcome<A> | {
+    kind: 'usage_unavailable';
+}) & ResolvedPoolModel;
+/**
+ * #405 integration seam: resolveModel ONCE before calling, then reuse the
+ * returned model/modelSource for --model. No fetch, probe, spawn or env fallback
+ * occurs here. Only no_accounts_configured permits the legacy env credential.
+ */
+export declare function selectPoolForResolvedModel<A extends AccountIdentity>(resolvedModel: ResolvedPoolModel, input: {
+    workspaceId: string;
+    pool: PoolFetchResult<A>;
+    store: SubscriptionUsageStore;
+    now: number;
+}): Promise<ResolvedPoolSelection<A>>;