@teamvibe/poller 0.8.4 → 0.8.5

package/README.md

@@ -95,3 +95,7 @@ In the environment the poller injects, the alias and account ID follow the selec
 ## How It Works
 
 The poller authenticates with the TeamVibe API using your token, then continuously polls an SQS queue for incoming messages from Slack. When a message arrives, it spawns a Claude Code session with the appropriate brain (knowledge base) and streams the response back to Slack.
+
+## Subscription usage freshness
+
+Passive usage percentages remain usable lower bounds until each window's `resetAt`. Without a reset time, passive windows expire five minutes after observation. Probe windows retain their 60-second TTL. Reset windows are ignored; known accounts still rank before unknown accounts. A window at the account's threshold defers selection until its expiry (reset for passive windows, TTL fallback without a reset).

package/dist/claude-spawner.js

@@ -902,7 +902,7 @@ async function runClaudeCode(msg, sessionLog, cwd, directory, sessionId, isFirst
         if (!runtime?.account && isQuotaPaused())
             throw new QuotaPausedError();
         if (runtime?.shouldStop())
-            throw new PoolDeferredError();
+            throw new PoolDeferredError('infrastructure', { suppressNotice: true });
         const prompt = runtime?.resumePending ? 'Continue the pending work in this session from the last completed action. Do not repeat completed actions or messages.' : buildPrompt(msg, contextHint);
         // teamvibe.ai#293 bug 2: decides plain-text vs. stream-json stdin. Empty
         // `extraArgs`/single-chunk `stdinChunks` (the overwhelming majority of
@@ -1530,7 +1530,6 @@ export async function spawnPoolClaudeCode(msg, sessionLog, selectedDirectory, se
     }
     const resumePending = poolRuntime?.pin?.resumePending === true;
     let effectiveCwd = cwd;
-    let loggingPool = false;
     let retainWorktree = resumePending;
     const poolAttempts = poolRuntime?.attempts?.slice(-1000) ?? [];
     let worktreeOwner;
@@ -1547,7 +1546,7 @@ export async function spawnPoolClaudeCode(msg, sessionLog, selectedDirectory, se
         catch (err) {
             if (resumePending) {
                 sessionLog.warn('[Worktree] Pending worktree recreation failed; retaining work for the next recheck');
-                throw new PoolDeferredError();
+                throw new PoolDeferredError('infrastructure', { error: err });
             }
             sessionLog.warn(`[Worktree] Failed to create worktree, falling back to main brain dir: ${err instanceof Error ? err.message : err}`);
         }
@@ -1562,7 +1561,6 @@ export async function spawnPoolClaudeCode(msg, sessionLog, selectedDirectory, se
             effectiveSessionId = randomUUID();
         }
         const fetchedPool = poolRuntime ? poolRuntime.pool ?? await fetchRuntimePool(msg) : undefined;
-        loggingPool = fetchedPool !== undefined && fetchedPool.kind !== 'no_accounts_configured';
         if (fetchedPool)
             logPoolFetch(sessionLog, fetchedPool);
         const scoped = poolRuntime ? await fetchConfigForSpawn({ pollerId: getPollerId() || '', workspaceId: msg.teamvibe.workspaceId, channelId: msg.teamvibe.channelId }) : undefined;
@@ -1580,8 +1578,8 @@ export async function spawnPoolClaudeCode(msg, sessionLog, selectedDirectory, se
                 try {
                     await poolRuntime.persist(id, { ...accountPin(prepared.account, resolved), effectiveCwd, claudeConfigDir, resumePending: runtime?.resumePending, sawSendMessageCall }, poolAttempts);
                 }
-                catch {
-                    throw new PoolDeferredError();
+                catch (error) {
+                    throw new PoolDeferredError('infrastructure', { error });
                 }
             }
             // Only a quota continuation shares delivery history. A fresh-session
@@ -1638,8 +1636,9 @@ export async function spawnPoolClaudeCode(msg, sessionLog, selectedDirectory, se
                 if (id && poolRuntime)
                     writes.push(poolRuntime.persist(id, { ...accountPin(prepared.account, resolved), effectiveCwd, claudeConfigDir, resumePending: runtime?.resumePending, sawSendMessageCall }, poolAttempts));
                 const outcomes = await Promise.allSettled(writes);
-                if (outcomes.some(outcome => outcome.status === 'rejected'))
-                    throw new PoolDeferredError();
+                const failed = outcomes.find((outcome) => outcome.status === 'rejected');
+                if (failed)
+                    throw new PoolDeferredError('infrastructure', { error: failed.reason });
             }
             return result;
         };
@@ -1649,8 +1648,10 @@ export async function spawnPoolClaudeCode(msg, sessionLog, selectedDirectory, se
             let result = initial;
             while (prepared?.account && (result.quota || result.rateLimitInfo?.status === 'rejected') && !result.killedByPoller && poolRuntime && runtime) {
                 attemptedAccounts.add(prepared.account.accountId);
-                if (poolRuntime.shouldStop() || attemptedAccounts.size >= 1000)
-                    throw new PoolDeferredError();
+                if (poolRuntime.shouldStop())
+                    throw new PoolDeferredError('infrastructure', { suppressNotice: true });
+                if (attemptedAccounts.size >= 1000)
+                    throw new PoolDeferredError('usage');
                 prepared.pool = await fetchRuntimePool(msg);
                 logPoolFetch(sessionLog, prepared.pool);
                 if (prepared.pool.kind === 'ready')
@@ -1664,11 +1665,18 @@ export async function spawnPoolClaudeCode(msg, sessionLog, selectedDirectory, se
                     }
                 const remaining = prepared.pool.kind === 'ready' ? prepared.pool.accounts.filter(a => !attemptedAccounts.has(a.accountId)) : [];
                 const selected = await selectPoolForResolvedModel(resolved, { workspaceId: msg.teamvibe.workspaceId, pool: remaining.length && prepared.pool.kind === 'ready' ? { ...prepared.pool, accounts: remaining } : prepared.pool, store: prepared.store, now: Date.now(), log: sessionLog, logAllExhausted: remaining.length === 0 });
-                if (selected.kind !== 'selected' || attemptedAccounts.has(selected.account.accountId))
-                    throw await poolDeferredError(prepared.pool, resolved, prepared.store, undefined, remaining.length ? sessionLog : undefined);
+                if (selected.kind !== 'selected' || attemptedAccounts.has(selected.account.accountId)) {
+                    const cause = selected.kind === 'deferred' || selected.kind === 'selected' ? 'usage'
+                        : selected.kind === 'usage_unavailable' ? 'infrastructure' : 'platform';
+                    // Usage eligibility must include previously attempted accounts too.
+                    throw await poolDeferredError(cause, prepared.pool, resolved, prepared.store, {
+                        log: remaining.length ? sessionLog : undefined,
+                        error: selected.kind === 'usage_unavailable' ? selected.error : undefined,
+                    });
+                }
                 effectiveSessionId = result.attemptedSessionId ?? effectiveSessionId;
                 if (!effectiveSessionId)
-                    throw new PoolDeferredError();
+                    throw new PoolDeferredError('infrastructure');
                 const fromAccount = prepared.account;
                 poolInfo(sessionLog, `switch from=${poolLabel(fromAccount)} to=${poolLabel(selected.account)} session=${JSON.stringify(effectiveSessionId)}`);
                 prepared.account = selected.account;
@@ -1710,8 +1718,6 @@ export async function spawnPoolClaudeCode(msg, sessionLog, selectedDirectory, se
     }
     catch (error) {
         if (error instanceof PoolDeferredError) {
-            if (loggingPool)
-                poolInfo(sessionLog, `work deferred eligibleAt=${new Date(error.eligibleAt).toISOString()} providerResetAt=${error.resetAt ?? 'unknown'}`);
             retainWorktree = true;
             error.attempts = poolAttempts;
         }

package/dist/poller.js

@@ -1,7 +1,7 @@
 import { isUsageProbe, handleUsageProbe } from './usage-probe-job.js';
 import { fetchSubscriptionPool } from './subscription-pool-client.js';
 import { formatPoolUsageLimitMessage } from './usage-limit-messages.js';
-import { logPoolUsageWrite } from './pool-logging.js';
+import { logPoolUsageWrite, poolInfo } from './pool-logging.js';
 import { emitCandidateUsage, poolRunTelemetry } from './pool-telemetry.js';
 import { executionDirectory, selectBrainDirectory } from './brain-directory.js';
 import { config, POLLER_VERSION } from './config.js';
@@ -440,8 +440,8 @@ export async function runInboxLoop(threadId, selectedDirectory, queueMessage, se
                     try {
                         saveInboxContext(kbPath, inboxMsg);
                     }
-                    catch {
-                        throw new PoolDeferredError();
+                    catch (error) {
+                        throw new PoolDeferredError('infrastructure', { error });
                     }
                     const savedRuntime = readInboxRuntime(kbPath, threadId);
                     if (savedRuntime?.filename === message.filename && savedRuntime.pin.workspaceId === queueMessage.teamvibe.workspaceId && (!currentPin || currentPin.accountId === savedRuntime.pin.accountId)) {
@@ -478,7 +478,7 @@ export async function runInboxLoop(threadId, selectedDirectory, queueMessage, se
                         persist: async (id, pin, attempts) => {
                             pin = { ...pin, inboxFilename: message.filename };
                             if (!lockToken || await persistSessionId(id, pin) === false)
-                                throw new PoolDeferredError();
+                                throw new PoolDeferredError('infrastructure');
                             currentSessionId = id;
                             currentPin = pin;
                             saveInboxRuntime(kbPath, threadId, { sessionId: id, pin, filename: message.filename, attempts, quotaDeferEpisodes });
@@ -594,7 +594,7 @@ export async function runInboxLoop(threadId, selectedDirectory, queueMessage, se
                             context: { threadId, filename: message.filename, iteration, reason: describeFailureReason(lastKilledByPoller, lastExitCode) },
                         });
                     }
-                    if (hasSlackContext && (decision.kind !== 'quota' || notifyQuota)) {
+                    if (hasSlackContext && !(poolIteration && lastKilledByPoller === 'shutdown') && (decision.kind !== 'quota' || notifyQuota)) {
                         if (decision.kind === 'neutral' || decision.kind === 'quota') {
                             await sendSlackMessage(deliveryMsg, decision.text);
                         }
@@ -608,6 +608,13 @@ export async function runInboxLoop(threadId, selectedDirectory, queueMessage, se
             catch (error) {
                 typing?.stop();
                 if (poolIteration && error instanceof PoolDeferredError) {
+                    poolInfo(sessionLog, `work deferred cause=${error.cause} error=${error.error} eligibleAt=${new Date(error.eligibleAt).toISOString()} providerResetAt=${error.resetAt ?? 'unknown'}`);
+                    if (error.suppressNotice || shuttingDown) {
+                        // Any prior marker has expired; retain its notice claim for restart.
+                        requeueMessage(kbPath, threadId, message.filename);
+                        deferred = true;
+                        break;
+                    }
                     quotaPaused = true;
                     deferred = true;
                     const pause = deferPool(threadId, error.eligibleAt, error.resetAt);
@@ -620,10 +627,11 @@ export async function runInboxLoop(threadId, selectedDirectory, queueMessage, se
                     if (hasSlackContext && pause.notice !== 'delivered') {
                         const reconcile = pause.notice === 'claimed' || pause.notice === 'ambiguous';
                         if (!reconcile && !setPoolNotice(threadId, pause.episodeId, 'claimed'))
-                            throw new PoolDeferredError(error.eligibleAt);
+                            throw new PoolDeferredError('infrastructure');
                         try {
                             const notice = formatPoolUsageLimitMessage({
                                 ...error.notice,
+                                cause: error.cause,
                                 thresholdDeferred: error.notice?.thresholdDeferred && !error.attempts?.some(a => a.quota),
                                 resetAt: pause.resetAt ? Date.parse(pause.resetAt) : error.notice?.resetAt,
                                 timeZone: config.POLLER_TZ,

package/dist/pool-logging.d.ts

@@ -1,3 +1,4 @@
+import type { PoolFetchDiagnostics } from './subscription-pool-client.js';
 import type { SessionLogger } from './logger.js';
 import type { ClaudeRateLimitInfo } from './claude-rate-limit.js';
 import { type AccountIdentity, type AccountUsageState, type PoolFetchResult, type SelectionOutcome } from './subscription-selection.js';
@@ -9,7 +10,10 @@ export declare function poolInfo(log: PoolInfoLogger, message: string): void;
 export declare function poolLabel(account: {
     label?: string;
 }): string;
-export declare function logPoolFetch(log: PoolInfoLogger, pool: PoolFetchResult): void;
+export declare function poolErrorClass(error: unknown): string;
+/** Allowlisted class/code only: caught messages and arbitrary names may contain secrets. */
+export declare function poolErrorDiagnostic(error: unknown): string;
+export declare function logPoolFetch(log: PoolInfoLogger, pool: PoolFetchResult & PoolFetchDiagnostics): void;
 export declare function logPoolSelection<A extends LabeledAccount>(log: PoolInfoLogger, pool: PoolFetchResult<A>, states: Readonly<Record<string, AccountUsageState>>, model: string | undefined, now: number, selected: SelectionOutcome<A>, logAllExhausted?: boolean): void;
 /** Log the real store promise without changing its rejection or retry behavior. */
 export declare function logPoolUsageWrite(log: PoolInfoLogger, account: {

package/dist/pool-logging.js

@@ -11,13 +11,36 @@ export function poolLabel(account) {
     const label = account.label;
     return JSON.stringify(label && label.length <= 128 && !/sk-ant-|Bearer\s|[\r\n]/i.test(label) ? label : 'unlabeled');
 }
+const POOL_ERROR_CLASSES = new Set([
+    'Error', 'TypeError', 'RangeError', 'AbortError', 'TimeoutError', 'SubscriptionUsageStoreError',
+    'ConditionalCheckFailedException', 'AccessDeniedException', 'ExpiredTokenException', 'CredentialsProviderError',
+    'ThrottlingException', 'ProvisionedThroughputExceededException', 'ValidationException', 'ResourceNotFoundException',
+]);
+export function poolErrorClass(error) {
+    return error instanceof Error && POOL_ERROR_CLASSES.has(error.name) ? error.name : 'UnknownError';
+}
+/** Allowlisted class/code only: caught messages and arbitrary names may contain secrets. */
+export function poolErrorDiagnostic(error) {
+    if (error === undefined)
+        return 'none';
+    const record = (value) => value && typeof value === 'object' ? value : {};
+    const outer = record(error);
+    const code = record(outer['cause'])['code'] ?? outer['code'];
+    if (typeof code === 'string' && (POOL_ERROR_CLASSES.has(code) || [
+        'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT', 'UND_ERR_ABORTED',
+        'ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EPIPE', 'ENETUNREACH', 'EHOSTUNREACH',
+        'ENOENT', 'EACCES', 'EPERM', 'ENOSPC', 'ENOTDIR', 'EIO',
+    ].includes(code)))
+        return code;
+    return poolErrorClass(error);
+}
 export function logPoolFetch(log, pool) {
     if (pool.kind === 'no_accounts_configured')
         return;
     // The API exposes usable members only; hidden disabled labels are unavailable.
     const enabled = pool.kind === 'ready' ? pool.accounts.filter(a => a.enabled).length : pool.kind === 'fetch_unavailable' && pool.reason === 'no_usable_accounts' ? 0 : 'unknown';
     const configured = pool.kind === 'ready' || pool.kind === 'fetch_unavailable' && pool.reason === 'no_usable_accounts' ? 'true' : 'unknown';
-    poolInfo(log, `fetch poolConfigured=${configured} enabled=${enabled} usable=${enabled} result=${pool.kind}${pool.kind === 'fetch_unavailable' ? ` reason=${pool.reason}` : ''}`);
+    poolInfo(log, `fetch poolConfigured=${configured} enabled=${enabled} usable=${enabled} result=${pool.kind}${pool.kind === 'fetch_unavailable' ? ` reason=${pool.reason}` : ''}${pool.cause ? ` cause=${pool.cause}` : ''} attempts=${pool.attempts ?? 1}`);
 }
 export function logPoolSelection(log, pool, states, model, now, selected, logAllExhausted = true) {
     if (pool.kind !== 'ready')

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

@@ -29,7 +29,11 @@ export interface PoolClientOptions {
 }
 /** 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>;
+export interface PoolFetchDiagnostics {
+    attempts?: number;
+    cause?: string;
+}
 /** 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>>;
+export declare function fetchSubscriptionPool(input: PoolFetchInput, options: PoolClientOptions): Promise<PoolFetchResult<SubscriptionAccount> & PoolFetchDiagnostics>;

package/dist/subscription-pool-client.js

@@ -1,3 +1,4 @@
+import { setTimeout as delay } from 'node:timers/promises';
 import { ACCOUNT_PROBE_FAILURE_REASONS } from './usage-probe-contract.js';
 import { record } from './subscription-selection.js';
 /** Unwrap only at the optional Claude probe or future child-spawn boundary. */
@@ -39,6 +40,17 @@ export async function boundedRequest(work, signal, timeoutMs = 15_000) {
         controller.signal.removeEventListener('abort', onAbort);
     }
 }
+/** Only allow known transport codes/classes out; never expose error messages. */
+function networkCause(error) {
+    const outer = record(error);
+    const code = record(outer['cause'])['code'] ?? outer['code'];
+    if (typeof code === 'string' && [
+        'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT', 'UND_ERR_ABORTED',
+        'ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EPIPE', 'ENETUNREACH', 'EHOSTUNREACH',
+    ].includes(code))
+        return code;
+    return error instanceof Error && ['Error', 'TypeError', 'AbortError', 'TimeoutError'].includes(error.name) ? error.name : 'UnknownError';
+}
 /** Bounded, ephemeral raw body. Neither it nor caught errors leave this module. */
 export async function readSubscriptionJson(response) {
     const reader = response.body?.getReader();
@@ -88,6 +100,21 @@ export async function fetchSubscriptionPool(input, options) {
     catch {
         return { kind: 'fetch_unavailable', reason: 'configuration' };
     }
+    for (let attempts = 1;; attempts++) {
+        const result = await fetchPoolAttempt(url, input, options);
+        const retryable = result.kind === 'fetch_unavailable' && (result.reason === 'network' ||
+            result.reason === 'http' && (result.status === 429 || (result.status !== undefined && result.status >= 500 && result.status <= 599)));
+        if (!retryable || attempts >= 3)
+            return attempts > 1 ? { ...result, attempts } : result;
+        try {
+            await delay(attempts === 1 ? 500 : 2_000, undefined, { signal: options.signal });
+        }
+        catch {
+            return { kind: 'fetch_unavailable', reason: 'cancelled', attempts };
+        }
+    }
+}
+async function fetchPoolAttempt(url, input, options) {
     try {
         return await boundedRequest(async (signal) => {
             const response = await (options.fetch ?? fetch)(url, {
@@ -144,7 +171,7 @@ export async function fetchSubscriptionPool(input, options) {
             return { kind: 'unknown_pool_state' };
         }, options.signal, options.timeoutMs);
     }
-    catch {
-        return { kind: 'fetch_unavailable', reason: options.signal?.aborted ? 'cancelled' : 'network' };
+    catch (error) {
+        return { kind: 'fetch_unavailable', reason: options.signal?.aborted ? 'cancelled' : 'network', cause: networkCause(error) };
     }
 }

package/dist/subscription-pool.d.ts

@@ -5,13 +5,16 @@ 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';
+    error: unknown;
 }) & 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: {
+export declare function selectPoolForResolvedModel<A extends AccountIdentity & {
+    label?: string;
+}>(resolvedModel: ResolvedPoolModel, input: {
     workspaceId: string;
     pool: PoolFetchResult<A>;
     store: SubscriptionUsageStore;

package/dist/subscription-pool.js

@@ -1,4 +1,5 @@
-import { logPoolSelection } from './pool-logging.js';
+import { logger } from './logger.js';
+import { logPoolSelection, poolInfo, poolLabel, poolErrorClass } from './pool-logging.js';
 import { selectSubscriptionAccount } from './subscription-selection.js';
 import { usageStateForSelection } from './subscription-usage-store.js';
 /**
@@ -17,11 +18,17 @@ export async function selectPoolForResolvedModel(resolvedModel, input) {
     const states = Object.create(null);
     try {
         await Promise.all(input.pool.accounts.map(async (account) => {
-            states[account.accountId] = usageStateForSelection(await input.store.read(account), input.now);
+            try {
+                states[account.accountId] = usageStateForSelection(await input.store.read(account), input.now);
+            }
+            catch (error) {
+                poolInfo(input.log ?? logger, `usage read account=${poolLabel(account)} result=failed errorClass=${poolErrorClass(error)}`);
+                throw error;
+            }
         }));
     }
-    catch {
-        return { kind: 'usage_unavailable', ...resolvedModel };
+    catch (error) {
+        return { kind: 'usage_unavailable', error, ...resolvedModel };
     }
     const selected = selectSubscriptionAccount({ pool: input.pool, states, model: resolvedModel.model, now: input.now, currentAccountId: input.currentAccountId });
     if (input.log)

package/dist/subscription-runtime.d.ts

@@ -1,10 +1,10 @@
 import { type PoolInfoLogger } from './pool-logging.js';
-import { type SubscriptionAccount } from './subscription-pool-client.js';
+import { type PoolFetchDiagnostics, type SubscriptionAccount } from './subscription-pool-client.js';
 import { type ResolvedPoolModel } from './subscription-pool.js';
 import { FileSubscriptionUsageStore, type SubscriptionUsageStore } from './subscription-usage-store.js';
 import { type PoolFetchResult, type HeadroomScore } from './subscription-selection.js';
 import type { SubscriptionPin, TeamVibeQueueMessage, SessionMetrics } from './types.js';
-import type { PoolUsageLimitNotice } from './usage-limit-messages.js';
+import type { PoolUsageLimitNotice, PoolDeferCause } from './usage-limit-messages.js';
 import type { ClaudeRateLimitInfo } from './claude-rate-limit.js';
 import type { ClaudeQuotaFailure } from './claude-quota.js';
 import type { KilledByPoller } from './classify-failed-iteration.js';
@@ -23,12 +23,21 @@ export interface PoolAttempt extends Partial<HeadroomScore> {
     quota?: ClaudeQuotaFailure;
     metrics?: SessionMetrics;
 }
+export declare const POOL_UNAVAILABLE_RECHECK_MS = 60000;
 export declare class PoolDeferredError extends Error {
-    readonly eligibleAt: number;
-    readonly resetAt?: string | undefined;
+    readonly cause: PoolDeferCause;
     attempts?: readonly PoolAttempt[];
-    notice?: PoolUsageLimitNotice;
-    constructor(eligibleAt?: number, resetAt?: string | undefined);
+    notice?: Omit<PoolUsageLimitNotice, 'cause'>;
+    readonly eligibleAt: number;
+    readonly resetAt?: string;
+    readonly suppressNotice: boolean;
+    readonly error: string;
+    constructor(cause: PoolDeferCause, options?: {
+        eligibleAt?: number;
+        resetAt?: string;
+        error?: unknown;
+        suppressNotice?: boolean;
+    });
 }
 export interface PoolRuntimeOptions {
     pin?: SubscriptionPin;
@@ -41,11 +50,28 @@ export interface PoolRuntimeOptions {
     shouldStop: () => boolean;
 }
 export declare function subscriptionUsageStore(): FileSubscriptionUsageStore;
-export declare function fetchRuntimePool(msg: TeamVibeQueueMessage): Promise<PoolFetchResult<SubscriptionAccount>>;
+export declare function fetchRuntimePool(msg: TeamVibeQueueMessage): Promise<PoolFetchResult<SubscriptionAccount> & PoolFetchDiagnostics>;
 export declare function preparePool(msg: TeamVibeQueueMessage, resolved: ResolvedPoolModel, pin?: SubscriptionPin, fetched?: PoolFetchResult<SubscriptionAccount>, log?: PoolInfoLogger): Promise<{
     account: SubscriptionAccount;
     store: FileSubscriptionUsageStore;
-    pool: PoolFetchResult<SubscriptionAccount>;
+    pool: {
+        kind: "probe_account_unavailable";
+        reason: import("./usage-probe-contract.js").AccountProbeFailureReason;
+    } | {
+        kind: "no_accounts_configured";
+    } | {
+        kind: "unknown_pool_state";
+    } | {
+        kind: "fetch_unauthorized";
+        status: 401 | 403;
+    } | {
+        kind: "fetch_unavailable";
+        reason: "configuration" | "http" | "network" | "invalid_response" | "cancelled" | "no_usable_accounts";
+        status?: number;
+    } | {
+        kind: "ready";
+        accounts: readonly SubscriptionAccount[];
+    };
     selection: ({
         kind: "selected";
         account: SubscriptionAccount;
@@ -66,10 +92,31 @@ export declare function preparePool(msg: TeamVibeQueueMessage, resolved: Resolve
 } | {
     account: undefined;
     store: FileSubscriptionUsageStore;
-    pool: PoolFetchResult<SubscriptionAccount>;
+    pool: {
+        kind: "probe_account_unavailable";
+        reason: import("./usage-probe-contract.js").AccountProbeFailureReason;
+    } | {
+        kind: "no_accounts_configured";
+    } | {
+        kind: "unknown_pool_state";
+    } | {
+        kind: "fetch_unauthorized";
+        status: 401 | 403;
+    } | {
+        kind: "fetch_unavailable";
+        reason: "configuration" | "http" | "network" | "invalid_response" | "cancelled" | "no_usable_accounts";
+        status?: number;
+    } | {
+        kind: "ready";
+        accounts: readonly SubscriptionAccount[];
+    };
     selection: undefined;
 }>;
 export declare function accountPin(account: SubscriptionAccount, resolved: ResolvedPoolModel): SubscriptionPin;
 export declare function validateAccount(account: SubscriptionAccount, resolved: ResolvedPoolModel): Promise<void>;
 /** A snapshot TTL/recheck is not a provider reset. Explicit rejections also establish resets. */
-export declare function poolDeferredError(pool: PoolFetchResult<SubscriptionAccount>, resolved: ResolvedPoolModel, store: SubscriptionUsageStore, eligibleAt?: number, log?: PoolInfoLogger): Promise<PoolDeferredError>;
+export declare function poolDeferredError(cause: PoolDeferCause, pool: PoolFetchResult<SubscriptionAccount> & PoolFetchDiagnostics, resolved: ResolvedPoolModel, store: SubscriptionUsageStore, options?: {
+    eligibleAt?: number;
+    log?: PoolInfoLogger;
+    error?: unknown;
+}): Promise<PoolDeferredError>;

package/dist/subscription-runtime.js

@@ -1,4 +1,4 @@
-import { poolInfo, poolLabel } from './pool-logging.js';
+import { poolInfo, poolLabel, poolErrorDiagnostic } from './pool-logging.js';
 import { emitCandidateUsage } from './pool-telemetry.js';
 import { join } from 'node:path';
 import { config } from './config.js';
@@ -6,16 +6,23 @@ import { getPollerId } from './auth-provider.js';
 import { fetchSubscriptionPool } from './subscription-pool-client.js';
 import { selectPoolForResolvedModel } from './subscription-pool.js';
 import { FileSubscriptionUsageStore, usageStateForSelection } from './subscription-usage-store.js';
-import { normalizePassiveUsage, selectSubscriptionAccount, PASSIVE_USAGE_TTL_MS, PROBE_USAGE_TTL_MS, reactiveEligibleAt, USAGE_THRESHOLD_PERCENT, POOL_RECHECK_MS } from './subscription-selection.js';
+import { normalizePassiveUsage, selectSubscriptionAccount, usageWindowExpiresAt, reactiveEligibleAt, USAGE_THRESHOLD_PERCENT, POOL_RECHECK_MS } from './subscription-selection.js';
+export const POOL_UNAVAILABLE_RECHECK_MS = 60_000;
 export class PoolDeferredError extends Error {
-    eligibleAt;
-    resetAt;
+    cause;
     attempts;
     notice;
-    constructor(eligibleAt = Date.now() + POOL_RECHECK_MS, resetAt) {
+    eligibleAt;
+    resetAt;
+    suppressNotice;
+    error;
+    constructor(cause, options = {}) {
         super('Subscription pool unavailable; work retained');
-        this.eligibleAt = eligibleAt;
-        this.resetAt = resetAt;
+        this.cause = cause;
+        this.eligibleAt = cause === 'usage' ? options.eligibleAt ?? Date.now() + POOL_RECHECK_MS : Date.now() + POOL_UNAVAILABLE_RECHECK_MS;
+        this.resetAt = cause === 'usage' ? options.resetAt : undefined;
+        this.suppressNotice = options.suppressNotice === true;
+        this.error = options.error instanceof PoolDeferredError ? options.error.error : poolErrorDiagnostic(options.error);
     }
 }
 export function subscriptionUsageStore() {
@@ -53,15 +60,25 @@ export async function preparePool(msg, resolved, pin, fetched, log) {
     }
     if (selected.kind === 'no_accounts_configured')
         return { account: undefined, store, pool, selection: undefined };
-    throw await poolDeferredError(pool, resolved, store, selected.kind === 'deferred' ? selected.eligibleAt : undefined);
+    const cause = selected.kind === 'deferred' ? 'usage' : selected.kind === 'usage_unavailable' ? 'infrastructure' : 'platform';
+    throw await poolDeferredError(cause, pool, resolved, store, {
+        eligibleAt: selected.kind === 'deferred' ? selected.eligibleAt : undefined,
+        log, error: selected.kind === 'usage_unavailable' ? selected.error : undefined,
+    });
 }
 export function accountPin(account, resolved) {
     return { workspaceId: account.workspaceId, accountId: account.accountId, credentialVersion: account.credentialVersion, ...resolved };
 }
 export async function validateAccount(account, resolved) {
-    const selected = await selectPoolForResolvedModel(resolved, { workspaceId: account.workspaceId, pool: { kind: 'ready', accounts: [account] }, store: subscriptionUsageStore(), now: Date.now() });
-    if (selected.kind !== 'selected')
-        throw new PoolDeferredError(selected.kind === 'deferred' ? selected.eligibleAt : undefined);
+    const store = subscriptionUsageStore();
+    const pool = { kind: 'ready', accounts: [account] };
+    const selected = await selectPoolForResolvedModel(resolved, { workspaceId: account.workspaceId, pool, store, now: Date.now() });
+    if (selected.kind !== 'selected') {
+        throw await poolDeferredError(selected.kind === 'deferred' ? 'usage' : 'infrastructure', pool, resolved, store, {
+            eligibleAt: selected.kind === 'deferred' ? selected.eligibleAt : undefined,
+            error: selected.kind === 'usage_unavailable' ? selected.error : undefined,
+        });
+    }
 }
 /** Message-only evidence; never changes selection, eligibility or durable pause state. */
 async function poolUsageNotice(pool, resolved, store) {
@@ -72,9 +89,8 @@ async function poolUsageNotice(pool, resolved, store) {
         const accounts = await Promise.all(pool.accounts.map(async (account) => {
             const state = usageStateForSelection(await store.read(account), now);
             const usage = state.usage;
-            const ttl = usage?.source === 'passive' ? PASSIVE_USAGE_TTL_MS : PROBE_USAGE_TTL_MS;
-            const windows = usage && usage.observedAt <= now && now < usage.observedAt + ttl
-                ? usage.windows.filter(w => w.resetAt === undefined || w.resetAt > now) : [];
+            const windows = usage && usage.observedAt <= now
+                ? usage.windows.filter(w => now < usageWindowExpiresAt(usage, w)) : [];
             const rejection = selectSubscriptionAccount({
                 pool: { kind: 'ready', accounts: [account] },
                 states: { [account.accountId]: { usage: usage ? { ...usage, windows: usage.windows.filter(w => w.status === 'rejected') } : undefined } },
@@ -100,17 +116,19 @@ async function poolUsageNotice(pool, resolved, store) {
     }
 }
 /** A snapshot TTL/recheck is not a provider reset. Explicit rejections also establish resets. */
-export async function poolDeferredError(pool, resolved, store, eligibleAt, log) {
+export async function poolDeferredError(cause, pool, resolved, store, options = {}) {
+    const { log } = options;
+    let { eligibleAt } = options;
+    if (cause !== 'usage')
+        return new PoolDeferredError(cause, { error: options.error ?? (pool.kind === 'fetch_unavailable' && pool.cause ? { code: pool.cause } : undefined) });
     const notice = await poolUsageNotice(pool, resolved, store);
-    let usageDeferred = eligibleAt !== undefined;
     const deferredError = (resetAt) => {
-        const error = new PoolDeferredError(eligibleAt, resetAt);
-        error.notice = { ...notice, thresholdDeferred: usageDeferred && notice.thresholdDeferred, resetAt: resetAt ? Date.parse(resetAt) : notice.resetAt };
+        const error = new PoolDeferredError('usage', { eligibleAt, resetAt });
+        error.notice = { ...notice, resetAt: resetAt ? Date.parse(resetAt) : notice.resetAt };
         return error;
     };
     if (eligibleAt === undefined) {
         const selected = await selectPoolForResolvedModel(resolved, { workspaceId: pool.kind === 'ready' ? pool.accounts[0]?.workspaceId ?? '' : '', pool, store, now: Date.now(), log });
-        usageDeferred = selected.kind === 'deferred';
         eligibleAt = selected.kind === 'deferred' ? selected.eligibleAt : Date.now() + POOL_RECHECK_MS;
     }
     if (pool.kind === 'ready') {

package/dist/subscription-selection.d.ts

@@ -1,7 +1,7 @@
 import type { AccountProbeFailureReason } from './usage-probe-contract.js';
 import type { ClaudeQuotaFailure } from './claude-quota.js';
 export declare const USAGE_THRESHOLD_PERCENT = 90;
-/** Passive snapshots are useful for five minutes, then become unknown. */
+/** Fallback freshness for passive windows without a reset time. */
 export declare const PASSIVE_USAGE_TTL_MS: number;
 export declare const PROBE_USAGE_TTL_MS = 60000;
 export declare const POOL_RECHECK_MS: number;
@@ -49,6 +49,8 @@ export interface UsageObservation {
     observedAt: number;
     windows: readonly UsageWindow[];
 }
+/** Passive percentages remain lower bounds until reset; probes retain their short TTL. */
+export declare function usageWindowExpiresAt(usage: UsageObservation, window: UsageWindow): number;
 /** Latest measurements plus durable rejections; omission or success never clears a hold. */
 export declare function mergeUsageObservations(observations: readonly (UsageObservation | undefined)[], now: number): UsageObservation | undefined;
 export interface ReactiveExhaustion {

package/dist/subscription-selection.js

@@ -1,10 +1,15 @@
 export const USAGE_THRESHOLD_PERCENT = 90;
-/** Passive snapshots are useful for five minutes, then become unknown. */
+/** Fallback freshness for passive windows without a reset time. */
 export const PASSIVE_USAGE_TTL_MS = 5 * 60_000;
 export const PROBE_USAGE_TTL_MS = 60_000;
 export const POOL_RECHECK_MS = 15 * 60_000;
 /** Safety hold from the rejection observation when the provider gives no reset. */
 export const REJECTED_BLOCK_MS = 15 * 60_000;
+/** Passive percentages remain lower bounds until reset; probes retain their short TTL. */
+export function usageWindowExpiresAt(usage, window) {
+    const ttlExpiry = usage.observedAt + (usage.source === 'passive' ? PASSIVE_USAGE_TTL_MS : PROBE_USAGE_TTL_MS);
+    return usage.source === 'passive' ? window.resetAt ?? ttlExpiry : Math.min(window.resetAt ?? ttlExpiry, ttlExpiry);
+}
 /** Latest measurements plus durable rejections; omission or success never clears a hold. */
 export function mergeUsageObservations(observations, now) {
     let latest;
@@ -200,13 +205,11 @@ export function selectSubscriptionAccount(input) {
                     blockers.push(until);
             }
         }
-        const expiry = usage ? usage.observedAt + (usage.source === 'passive' ? PASSIVE_USAGE_TTL_MS : PROBE_USAGE_TTL_MS) : 0;
-        const fresh = usage && usage.observedAt <= input.now && input.now < expiry;
-        const windows = fresh ? usage.windows.filter(w => w.status !== 'rejected' && (w.observedAt ?? usage.observedAt) === usage.observedAt && (w.source ?? usage.source) === usage.source && applicable(w.scope, input.model) && (w.resetAt === undefined || w.resetAt > input.now)) : [];
+        const windows = usage && usage.observedAt <= input.now ? usage.windows.filter(w => w.status !== 'rejected' && (w.observedAt ?? usage.observedAt) === usage.observedAt && (w.source ?? usage.source) === usage.source && applicable(w.scope, input.model) && input.now < usageWindowExpiresAt(usage, w)) : [];
         const uncertain = windows.some(w => w.scope === 'uncertain' || (w.scope !== 'global' && !family(input.model)));
         for (const w of windows) {
             if (w.percent !== undefined && w.percent >= (account.useFullQuota ? 100 : USAGE_THRESHOLD_PERCENT))
-                blockers.push(Math.min(w.resetAt ?? expiry, expiry));
+                blockers.push(usageWindowExpiresAt(usage, w));
         }
         if (blockers.length) {
             deadlines.push(Math.max(...blockers));

package/dist/usage-limit-messages.d.ts

@@ -13,7 +13,9 @@ export interface UsageLimitAccount {
     }[];
     rejected?: boolean;
 }
+export type PoolDeferCause = 'usage' | 'platform' | 'infrastructure';
 export interface PoolUsageLimitNotice extends UsageResetTiming {
+    cause: PoolDeferCause;
     thresholdDeferred?: boolean;
     accounts?: readonly UsageLimitAccount[];
 }

package/dist/usage-limit-messages.js

@@ -1,3 +1,4 @@
+import { USAGE_THRESHOLD_PERCENT } from './subscription-selection.js';
 /** Owner-facing account policy location. */
 export const FULL_QUOTA_SETTINGS_PATH = 'Connections (account menu → Use until exhausted)';
 export function formatUsageReset(input) {
@@ -24,6 +25,12 @@ export function formatUsageReset(input) {
     return `${time} (in ${relative})`;
 }
 export function formatPoolUsageLimitMessage(input) {
+    if (input.cause === 'infrastructure') {
+        return "⏳ Something went wrong while starting your session. Your message is saved and I'll retry in about a minute.";
+    }
+    if (input.cause === 'platform') {
+        return "⏳ I couldn't reach the TeamVibe platform to pick a Claude account. Your message is saved and I'll retry in about a minute.";
+    }
     const accounts = input.accounts ?? [];
     const headroom = accounts.filter(account => !account.useFullQuota && !account.rejected).map(account => {
         const percentages = account.windows.map(w => w.percent).filter((p) => p !== undefined && Number.isFinite(p) && p >= 0 && p <= 100);
@@ -34,7 +41,7 @@ export function formatPoolUsageLimitMessage(input) {
     const reset = formatUsageReset(input);
     if (threshold) {
         const labels = headroom.filter(a => a.label && a.remaining > 0).map(a => `${a.label} ${Number(a.remaining.toFixed(2))} %`).join(', ');
-        return `⏳ All Claude accounts in this workspace are above 90 % of their usage limit, so I'm waiting for the next reset${reset ? ` at ${reset}` : ''}. Your message is saved and will run automatically.\n💡 There is still some capacity left${labels ? ` (${labels})` : ''}. A workspace owner can allow the full quota per account in ${FULL_QUOTA_SETTINGS_PATH}.`;
+        return `⏳ All Claude accounts in this workspace are above ${USAGE_THRESHOLD_PERCENT} % of their usage limit, so I'm waiting for the next reset${reset ? ` at ${reset}` : ''}. Your message is saved and will run automatically.\n💡 There is still some capacity left${labels ? ` (${labels})` : ''}. A workspace owner can allow the full quota per account in ${FULL_QUOTA_SETTINGS_PATH}.`;
     }
     return `⏳ All Claude accounts in this workspace have hit their usage limit. Your message is saved and will run automatically after ${reset ? `the earliest reset at ${reset}` : 'the next reset'}.`;
 }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@teamvibe/poller",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@teamvibe/poller",
-      "version": "0.8.4",
+      "version": "0.8.5",
       "dependencies": {
         "@aws-sdk/client-dynamodb": "3.1108.0",
         "@aws-sdk/client-sqs": "3.1108.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamvibe/poller",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {