@teamvibe/poller 0.8.6-rc.2 → 0.8.6-rc.3

package/dist/claude-spawner.js

@@ -1,5 +1,5 @@
 import { logPoolFetch, logPoolUsageWrite, poolInfo, poolLabel } from './pool-logging.js';
-import { accountUsageTelemetry, emitCandidateUsage, poolRunTelemetry } from './pool-telemetry.js';
+import { emitPoolSelection, accountUsageTelemetry, emitCandidateUsage, poolRunTelemetry } from './pool-telemetry.js';
 import { spawn } from 'child_process';
 import { join } from 'path';
 import { readFileSync, existsSync } from 'fs';
@@ -1046,6 +1046,8 @@ async function runClaudeCode(msg, sessionLog, cwd, directory, sessionId, isFirst
         activeProcessesByThread.set(msg.thread_id, proc);
         if (runtime?.account)
             activeSubscriptionAccounts.set(proc, runtime.account);
+        if (proc.pid !== undefined)
+            runtime?.onSpawn?.();
         for (const chunk of spawnStdinPlan.stdinChunks) {
             proc.stdin?.write(chunk);
         }
@@ -1579,7 +1581,18 @@ export async function spawnPoolClaudeCode(msg, sessionLog, selectedDirectory, se
         const prepared = poolRuntime ? await preparePool(msg, resolved, poolRuntime.pin, fetchedPool, sessionLog, { cliPath: config.CLAUDE_CLI_PATH, isAtCapacity, emit: emitEvent, log: line => sessionLog.info(line) }) : undefined;
         const modelNormalizedFrom = scoped?.model === resolved.model && scoped?.modelSource === resolved.modelSource
             ? scoped?.modelNormalizedFrom : undefined;
-        const runtime = poolRuntime ? { resolved, modelNormalizedFrom, claudeConfigDir, account: prepared?.account, shouldStop: poolRuntime.shouldStop, resumePending: fetchedPool?.kind !== 'no_accounts_configured' && poolRuntime.pin?.resumePending === true } : undefined;
+        const runtime = poolRuntime ? {
+            resolved, modelNormalizedFrom, claudeConfigDir, account: prepared?.account,
+            shouldStop: poolRuntime.shouldStop,
+            resumePending: fetchedPool?.kind !== 'no_accounts_configured' && poolRuntime.pin?.resumePending === true,
+            onSpawn: () => {
+                if (prepared?.selection) {
+                    emitPoolSelection(msg, prepared.selection);
+                    // Retries report each launch, but release the original pin only once.
+                    delete prepared.selection.switch;
+                }
+            },
+        } : undefined;
         let sawSendMessageCall = poolRuntime?.pin?.resumePending === true && poolRuntime.pin.sawSendMessageCall === true;
         const attempt = async (id, first) => {
             if (prepared?.account && id && poolRuntime) {
@@ -1689,6 +1702,12 @@ export async function spawnPoolClaudeCode(msg, sessionLog, selectedDirectory, se
                 abortLocalProbe(selected.account);
                 poolInfo(sessionLog, `switch from=${poolLabel(fromAccount)} to=${poolLabel(selected.account)} session=${JSON.stringify(effectiveSessionId)}`);
                 prepared.account = selected.account;
+                selected.candidates = [
+                    ...(selected.candidates ?? []).filter(c => !attemptedAccounts.has(c.accountId)),
+                    ...(prepared.pool.kind === 'ready' ? prepared.pool.accounts.filter(a => attemptedAccounts.has(a.accountId)).map(a => ({ accountId: a.accountId, accountLabel: JSON.parse(poolLabel(a)), outcome: 'skipped', reason: 'already exhausted in this session' })) : []),
+                ];
+                if (prepared.pool.kind === 'ready' && prepared.pool.accounts.some(a => a.accountId === fromAccount.accountId))
+                    selected.switch = { fromAccountId: fromAccount.accountId, reason: 'reactive quota' };
                 prepared.selection = selected;
                 runtime.account = selected.account;
                 runtime.resumePending = true;

package/dist/pool-logging.d.ts

@@ -14,6 +14,18 @@ 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 interface PoolSelectionCandidate {
+    accountId: string;
+    accountLabel: string;
+    outcome: 'selected' | 'skipped';
+    reason: string;
+    score?: number;
+    headroom?: number;
+    rateWindow?: Pick<UsageWindow, 'window' | 'scope'>;
+    eligibleAt?: number;
+}
+/** The log and transport share a single explanation of the same selection snapshot. */
+export declare function poolSelectionCandidates<A extends LabeledAccount>(pool: PoolFetchResult<A>, states: Readonly<Record<string, AccountUsageState>>, model: string | undefined, now: number, selected: SelectionOutcome<A>): PoolSelectionCandidate[];
 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;
 export declare function formatPoolUsageWindows(windows: readonly UsageWindow[], includeScope?: boolean): string;
 /** Log the real store promise without changing its rejection or retry behavior. */

package/dist/pool-logging.js

@@ -42,23 +42,36 @@ export function logPoolFetch(log, pool) {
     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}` : ''}${pool.cause ? ` cause=${pool.cause}` : ''} attempts=${pool.attempts ?? 1}`);
 }
-export function logPoolSelection(log, pool, states, model, now, selected, logAllExhausted = true) {
+/** The log and transport share a single explanation of the same selection snapshot. */
+export function poolSelectionCandidates(pool, states, model, now, selected) {
     if (pool.kind !== 'ready')
-        return;
-    for (const account of pool.accounts) {
-        if (!account.enabled) {
-            poolInfo(log, `skipped account=${poolLabel(account)} reason=disabled`);
-            continue;
-        }
+        return [];
+    return pool.accounts.map(account => {
+        const base = { accountId: account.accountId, accountLabel: JSON.parse(poolLabel(account)), outcome: 'skipped' };
+        if (!account.enabled)
+            return { ...base, reason: 'disabled' };
         const candidate = selectSubscriptionAccount({ pool: { ...pool, accounts: [account] }, states, model, now });
         if (candidate.kind === 'deferred') {
             const usageOnly = selectSubscriptionAccount({ pool: { ...pool, accounts: [account] }, states: { [account.accountId]: { usage: states[account.accountId]?.usage } }, model, now });
-            poolInfo(log, `skipped account=${poolLabel(account)} reason=${usageOnly.kind === 'deferred' ? `usage >=${account.useFullQuota ? 100 : 90}%` : 'reactive quota'} eligibleAt=${new Date(candidate.eligibleAt).toISOString()}`);
-        }
-        else if (candidate.kind === 'selected' && selected.kind === 'selected' && account.accountId !== selected.account.accountId) {
-            const reason = candidate.provenance === 'unknown' && selected.provenance === 'known' ? 'known observation preferred' : candidate.provenance === 'known' && selected.provenance === 'known' && candidate.score < selected.score ? 'lower headroom per hour' : 'deterministic account order';
-            poolInfo(log, `skipped account=${poolLabel(account)} reason=${reason}`);
+            return { ...base, reason: usageOnly.kind === 'deferred' ? `usage >=${account.useFullQuota ? 100 : 90}%` : 'reactive quota', eligibleAt: candidate.eligibleAt };
         }
+        const metrics = candidate.kind === 'selected' && candidate.provenance === 'known'
+            ? { score: candidate.score, headroom: (account.useFullQuota ? 100 : 90) - candidate.rateWindow.percent, rateWindow: { window: candidate.rateWindow.window, scope: candidate.rateWindow.scope } } : {};
+        if (selected.kind === 'selected' && account.accountId === selected.account.accountId)
+            return { ...base, ...metrics, outcome: 'selected', reason: 'selected' };
+        const reason = candidate.kind === 'selected' && selected.kind === 'selected'
+            ? candidate.provenance === 'unknown' && selected.provenance === 'known' ? 'known observation preferred' : candidate.provenance === 'known' && selected.provenance === 'known' && candidate.score < selected.score ? 'lower headroom per hour' : 'deterministic account order'
+            : 'unavailable';
+        return { ...base, ...metrics, reason };
+    });
+}
+export function logPoolSelection(log, pool, states, model, now, selected, logAllExhausted = true) {
+    if (pool.kind !== 'ready')
+        return;
+    for (const candidate of poolSelectionCandidates(pool, states, model, now, selected)) {
+        if (candidate.outcome !== 'skipped' || candidate.reason === 'unavailable')
+            continue;
+        poolInfo(log, `skipped account=${JSON.stringify(candidate.accountLabel)} reason=${candidate.reason}${candidate.eligibleAt === undefined ? '' : ` eligibleAt=${new Date(candidate.eligibleAt).toISOString()}`}`);
     }
     if (selected.kind === 'deferred' && logAllExhausted) {
         // Ask the same policy about each observation so model scope, freshness and

package/dist/pool-telemetry.d.ts

@@ -60,3 +60,5 @@ export declare function poolRunTelemetry(attempts: readonly PoolAttempt[], quota
     model?: string | undefined;
     observedAt?: number | undefined;
 };
+/** Labels and explicit decision metrics only; never spread account or credential objects. */
+export declare function emitPoolSelection(msg: TeamVibeQueueMessage, selection: import('./subscription-pool.js').ResolvedPoolSelection<SubscriptionAccount>): void;

package/dist/pool-telemetry.js

@@ -1,5 +1,5 @@
 import { emitEvent } from './event-queue.js';
-import { reactiveEligibleAt } from './subscription-selection.js';
+import { family, reactiveEligibleAt } from './subscription-selection.js';
 import { usageStateForSelection, safeQuota, safeRateLimitInfo, } from './subscription-usage-store.js';
 function safeText(value) {
     return value && value.length <= 128 && !/sk-ant-|Bearer\s|[\r\n]/i.test(value)
@@ -123,3 +123,22 @@ export function poolRunTelemetry(attempts, quotaDeferEpisodes = 0) {
         attempts: safeAttempts,
     };
 }
+// Keep ordering across retries and intervening threads even within one clock tick.
+let lastSelectionAt = 0;
+/** Labels and explicit decision metrics only; never spread account or credential objects. */
+export function emitPoolSelection(msg, selection) {
+    if (selection.kind !== 'selected')
+        return;
+    lastSelectionAt = Math.max(Date.now(), lastSelectionAt + 1);
+    emitEvent('pool.selection', msg.teamvibe.channelId, {
+        workspaceId: msg.teamvibe.workspaceId,
+        threadId: msg.thread_id,
+        model: safeText(selection.model) ?? 'CLI default',
+        modelFamily: family(selection.model) ?? 'default',
+        selectedAccountId: selection.account.accountId,
+        selectedAccountLabel: safeText(selection.account.label) ?? 'unlabeled',
+        decidedAt: lastSelectionAt,
+        candidates: selection.candidates ?? [],
+        ...(selection.switch ? { switch: selection.switch } : {}),
+    });
+}

package/dist/subscription-pool.d.ts

@@ -1,4 +1,4 @@
-import { type PoolInfoLogger } from './pool-logging.js';
+import { type PoolSelectionCandidate, type PoolInfoLogger } from './pool-logging.js';
 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';
@@ -6,7 +6,13 @@ export type ResolvedPoolModel = ReturnType<typeof resolveModel>;
 export type ResolvedPoolSelection<A extends AccountIdentity> = (SelectionOutcome<A> | {
     kind: 'usage_unavailable';
     error: unknown;
-}) & ResolvedPoolModel;
+}) & ResolvedPoolModel & {
+    candidates?: PoolSelectionCandidate[];
+    switch?: {
+        fromAccountId: string;
+        reason: string;
+    };
+};
 /**
  * #405 integration seam: resolveModel ONCE before calling, then reuse the
  * returned model/modelSource for --model. No fetch, probe, spawn or env fallback

package/dist/subscription-pool.js

@@ -1,5 +1,5 @@
 import { logger } from './logger.js';
-import { logPoolSelection, poolInfo, poolLabel, poolErrorClass } from './pool-logging.js';
+import { logPoolSelection, poolSelectionCandidates, poolInfo, poolLabel, poolErrorClass } from './pool-logging.js';
 import { selectSubscriptionAccount } from './subscription-selection.js';
 import { usageStateForSelection } from './subscription-usage-store.js';
 /**
@@ -33,5 +33,5 @@ export async function selectPoolForResolvedModel(resolvedModel, input) {
     const selected = selectSubscriptionAccount({ pool: input.pool, states, model: resolvedModel.model, now: input.now, currentAccountId: input.currentAccountId, currentAccountTolerance: input.currentAccountTolerance });
     if (input.log)
         logPoolSelection(input.log, input.pool, states, resolvedModel.model, input.now, selected, input.logAllExhausted);
-    return { ...selected, ...resolvedModel };
+    return { ...selected, ...resolvedModel, candidates: poolSelectionCandidates(input.pool, states, resolvedModel.model, input.now, selected) };
 }

package/dist/subscription-runtime.d.ts

@@ -89,6 +89,12 @@ export declare function preparePool(msg: TeamVibeQueueMessage, resolved: Resolve
     } & HeadroomScore & {
         model: string | undefined;
         modelSource: import("./claude-spawner.js").ModelSource;
+    } & {
+        candidates?: import("./pool-logging.js").PoolSelectionCandidate[];
+        switch?: {
+            fromAccountId: string;
+            reason: string;
+        };
     }) | ({
         kind: "selected";
         account: SubscriptionAccount;
@@ -97,6 +103,12 @@ export declare function preparePool(msg: TeamVibeQueueMessage, resolved: Resolve
     } & {
         model: string | undefined;
         modelSource: import("./claude-spawner.js").ModelSource;
+    } & {
+        candidates?: import("./pool-logging.js").PoolSelectionCandidate[];
+        switch?: {
+            fromAccountId: string;
+            reason: string;
+        };
     });
 } | {
     account: undefined;

package/dist/subscription-runtime.js

@@ -123,10 +123,13 @@ export async function preparePool(msg, resolved, pin, fetched, log, probeOptions
     const selected = await selectPoolForResolvedModel(resolved, { workspaceId: msg.teamvibe.workspaceId, pool, store, now: Date.now(), log, currentAccountId, currentAccountTolerance: PIN_HEADROOM_SWITCH_RELATIVE });
     if (selected.kind === 'selected') {
         abortLocalProbe(selected.account);
-        if (log && pool.kind === 'ready' && currentAccountId && currentAccountId !== selected.account.accountId) {
+        if (pool.kind === 'ready' && currentAccountId && currentAccountId !== selected.account.accountId) {
             const previous = pool.accounts.find(a => a.accountId === currentAccountId);
             const previousSelection = previous ? await selectPoolForResolvedModel(resolved, { workspaceId: msg.teamvibe.workspaceId, pool: { kind: 'ready', accounts: [previous] }, store, now: Date.now() }) : undefined;
-            poolInfo(log, `switch from=${poolLabel(previous ?? {})} to=${poolLabel(selected.account)} reason=${previousSelection?.kind === 'selected' ? 'better headroom' : 'pinned account unavailable'}`);
+            if (previous)
+                selected.switch = { fromAccountId: currentAccountId, reason: previousSelection?.kind === 'selected' ? 'better headroom' : 'pinned account unavailable' };
+            if (log)
+                poolInfo(log, `switch from=${poolLabel(previous ?? {})} to=${poolLabel(selected.account)} reason=${previousSelection?.kind === 'selected' ? 'better headroom' : 'pinned account unavailable'}`);
         }
         if (pool.kind === 'ready')
             probeUnknownAccounts(pool.accounts, selected.account.accountId, resolved, store, {

package/dist/subscription-selection.d.ts

@@ -88,6 +88,7 @@ export type SelectionOutcome<A extends AccountIdentity = AccountIdentity> = ({
 export declare function record(value: unknown): Record<string, unknown>;
 export declare function normalizePassiveUsage(value: unknown, observedAt: number): UsageObservation;
 export declare function normalizeProbeUsage(value: unknown, observedAt: number): UsageObservation;
+export declare function family(model: string | undefined): 'sonnet' | 'opus' | 'haiku' | 'fable' | undefined;
 export declare function reactiveEligibleAt(reactive: ReactiveExhaustion): number;
 /** Pure policy. Unknown is eligible after every known/reactive blocker is ruled out. */
 export declare function selectSubscriptionAccount<A extends AccountIdentity>(input: {

package/dist/subscription-selection.js

@@ -143,7 +143,7 @@ export function normalizeProbeUsage(value, observedAt) {
     }
     return { source: 'probe', observedAt, windows };
 }
-function family(model) {
+export function family(model) {
     return model?.toLowerCase().match(/^(?:claude-)?(sonnet|opus|haiku|fable)(?:-\d[\w.-]*)?(?:\[1m\])?$/)?.[1];
 }
 function applicable(scope, model) {
@@ -209,7 +209,7 @@ export function selectSubscriptionAccount(input) {
             }
         }
         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)));
+        const uncertain = windows.some(w => w.scope === 'uncertain' || (w.scope !== 'global' && input.model !== undefined && !family(input.model)));
         for (const w of windows) {
             if (w.percent !== undefined && w.percent >= (account.useFullQuota ? 100 : USAGE_THRESHOLD_PERCENT))
                 blockers.push(usageWindowExpiresAt(usage, w));

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@teamvibe/poller",
-  "version": "0.8.6-rc.2",
+  "version": "0.8.6-rc.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@teamvibe/poller",
-      "version": "0.8.6-rc.2",
+      "version": "0.8.6-rc.3",
       "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.6-rc.2",
+  "version": "0.8.6-rc.3",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {