github-issue-tower-defence-management 1.146.7 → 1.146.8

package/src/adapter/entry-points/cli/fleetConfig.test.ts

@@ -0,0 +1,177 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS } from '../../../domain/usecases/LiveSessionOauthTokenSelectUseCase';
+import {
+  FLEET_CONFIG_FILE_PATH_ENVIRONMENT_VARIABLE,
+  loadLiveSessionOauthTokenSelectionSettings,
+  resolveFleetConfigFilePath,
+} from './fleetConfig';
+
+describe('resolveFleetConfigFilePath', () => {
+  const originalEnvironmentValue =
+    process.env[FLEET_CONFIG_FILE_PATH_ENVIRONMENT_VARIABLE];
+
+  afterEach(() => {
+    if (originalEnvironmentValue === undefined) {
+      delete process.env[FLEET_CONFIG_FILE_PATH_ENVIRONMENT_VARIABLE];
+      return;
+    }
+    process.env[FLEET_CONFIG_FILE_PATH_ENVIRONMENT_VARIABLE] =
+      originalEnvironmentValue;
+  });
+
+  it('prefers the explicit value over the environment variable', () => {
+    process.env[FLEET_CONFIG_FILE_PATH_ENVIRONMENT_VARIABLE] =
+      '/from/environment.yaml';
+
+    expect(resolveFleetConfigFilePath('/from/option.yaml')).toBe(
+      '/from/option.yaml',
+    );
+  });
+
+  it('falls back to the environment variable when no explicit value is given', () => {
+    process.env[FLEET_CONFIG_FILE_PATH_ENVIRONMENT_VARIABLE] =
+      '/from/environment.yaml';
+
+    expect(resolveFleetConfigFilePath(null)).toBe('/from/environment.yaml');
+  });
+
+  it('returns null when neither an explicit value nor the environment variable is set', () => {
+    delete process.env[FLEET_CONFIG_FILE_PATH_ENVIRONMENT_VARIABLE];
+
+    expect(resolveFleetConfigFilePath(null)).toBeNull();
+  });
+});
+
+describe('loadLiveSessionOauthTokenSelectionSettings', () => {
+  let tempDir: string;
+
+  const writeFleetConfig = (content: string): string => {
+    const fleetConfigFilePath = path.join(tempDir, 'fleet.config.yaml');
+    fs.writeFileSync(fleetConfigFilePath, content);
+    return fleetConfigFilePath;
+  };
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fleet-config-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('returns the built-in settings when no fleet config path is given', () => {
+    expect(loadLiveSessionOauthTokenSelectionSettings(null)).toEqual(
+      DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
+    );
+  });
+
+  it('reads both tuning numbers from the fleet config file', () => {
+    const fleetConfigFilePath = writeFleetConfig(
+      [
+        'inTmuxLauncherCommand: cl',
+        'liveSessionOauthTokenSelection:',
+        '  maxConcurrentSessionCount: 16',
+        '  fullSpeedFiveHourFreeRatio: 0.4',
+      ].join('\n'),
+    );
+
+    expect(
+      loadLiveSessionOauthTokenSelectionSettings(fleetConfigFilePath),
+    ).toEqual({
+      maxConcurrentSessionCount: 16,
+      fullSpeedFiveHourFreeRatio: 0.4,
+    });
+  });
+
+  it('keeps the built-in value for a tuning number the fleet config omits', () => {
+    const fleetConfigFilePath = writeFleetConfig(
+      [
+        'liveSessionOauthTokenSelection:',
+        '  maxConcurrentSessionCount: 16',
+      ].join('\n'),
+    );
+
+    expect(
+      loadLiveSessionOauthTokenSelectionSettings(fleetConfigFilePath),
+    ).toEqual({
+      maxConcurrentSessionCount: 16,
+      fullSpeedFiveHourFreeRatio:
+        DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS.fullSpeedFiveHourFreeRatio,
+    });
+  });
+
+  it('returns the built-in settings when the fleet config carries no live session section', () => {
+    const fleetConfigFilePath = writeFleetConfig('inTmuxLauncherCommand: cl\n');
+
+    expect(
+      loadLiveSessionOauthTokenSelectionSettings(fleetConfigFilePath),
+    ).toEqual(DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS);
+  });
+
+  it('returns the built-in settings for an empty fleet config file', () => {
+    const fleetConfigFilePath = writeFleetConfig('');
+
+    expect(
+      loadLiveSessionOauthTokenSelectionSettings(fleetConfigFilePath),
+    ).toEqual(DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS);
+  });
+
+  it('throws when the fleet config file does not exist', () => {
+    expect(() =>
+      loadLiveSessionOauthTokenSelectionSettings(
+        path.join(tempDir, 'missing.yaml'),
+      ),
+    ).toThrow();
+  });
+
+  it('throws when the maximum concurrent session count is not a positive integer', () => {
+    const fleetConfigFilePath = writeFleetConfig(
+      [
+        'liveSessionOauthTokenSelection:',
+        '  maxConcurrentSessionCount: 0',
+      ].join('\n'),
+    );
+
+    expect(() =>
+      loadLiveSessionOauthTokenSelectionSettings(fleetConfigFilePath),
+    ).toThrow('maxConcurrentSessionCount');
+  });
+
+  it('throws when the five hour free ratio is above one', () => {
+    const fleetConfigFilePath = writeFleetConfig(
+      [
+        'liveSessionOauthTokenSelection:',
+        '  fullSpeedFiveHourFreeRatio: 1.5',
+      ].join('\n'),
+    );
+
+    expect(() =>
+      loadLiveSessionOauthTokenSelectionSettings(fleetConfigFilePath),
+    ).toThrow('fullSpeedFiveHourFreeRatio');
+  });
+
+  it('throws when a tuning number is written as a string', () => {
+    const fleetConfigFilePath = writeFleetConfig(
+      [
+        'liveSessionOauthTokenSelection:',
+        "  maxConcurrentSessionCount: '16'",
+      ].join('\n'),
+    );
+
+    expect(() =>
+      loadLiveSessionOauthTokenSelectionSettings(fleetConfigFilePath),
+    ).toThrow('must be a number');
+  });
+
+  it('throws when the live session section is not a mapping', () => {
+    const fleetConfigFilePath = writeFleetConfig(
+      'liveSessionOauthTokenSelection: 10\n',
+    );
+
+    expect(() =>
+      loadLiveSessionOauthTokenSelectionSettings(fleetConfigFilePath),
+    ).toThrow('must be a mapping');
+  });
+});

package/src/adapter/entry-points/cli/fleetConfig.ts

@@ -0,0 +1,109 @@
+import YAML from 'yaml';
+import * as fs from 'fs';
+import {
+  DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
+  LiveSessionOauthTokenSelectionSettings,
+} from '../../../domain/usecases/LiveSessionOauthTokenSelectUseCase';
+
+export const FLEET_CONFIG_FILE_PATH_ENVIRONMENT_VARIABLE = 'TDPM_FLEET_CONFIG';
+
+export const LIVE_SESSION_OAUTH_TOKEN_SELECTION_SECTION_KEY =
+  'liveSessionOauthTokenSelection';
+
+export const resolveFleetConfigFilePath = (
+  cliValue: string | null,
+): string | null => {
+  if (cliValue !== null && cliValue !== '') {
+    return cliValue;
+  }
+  const fromEnvironment =
+    process.env[FLEET_CONFIG_FILE_PATH_ENVIRONMENT_VARIABLE];
+  if (fromEnvironment !== undefined && fromEnvironment !== '') {
+    return fromEnvironment;
+  }
+  return null;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const readSection = (
+  fleetConfigFilePath: string,
+): Record<string, unknown> | null => {
+  const parsed: unknown = YAML.parse(
+    fs.readFileSync(fleetConfigFilePath, 'utf8'),
+  );
+  if (parsed === null || parsed === undefined) {
+    return null;
+  }
+  if (!isRecord(parsed)) {
+    throw new Error(
+      `${fleetConfigFilePath} does not hold a mapping at its top level.`,
+    );
+  }
+  const section = parsed[LIVE_SESSION_OAUTH_TOKEN_SELECTION_SECTION_KEY];
+  if (section === undefined || section === null) {
+    return null;
+  }
+  if (!isRecord(section)) {
+    throw new Error(
+      `${LIVE_SESSION_OAUTH_TOKEN_SELECTION_SECTION_KEY} in ${fleetConfigFilePath} must be a mapping.`,
+    );
+  }
+  return section;
+};
+
+const readBoundedNumber = (
+  section: Record<string, unknown>,
+  key: string,
+  fleetConfigFilePath: string,
+  fallback: number,
+  isAccepted: (value: number) => boolean,
+  requirement: string,
+): number => {
+  const value = section[key];
+  if (value === undefined || value === null) {
+    return fallback;
+  }
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(
+      `${LIVE_SESSION_OAUTH_TOKEN_SELECTION_SECTION_KEY}.${key} in ${fleetConfigFilePath} must be a number ${requirement}.`,
+    );
+  }
+  if (!isAccepted(value)) {
+    throw new Error(
+      `${LIVE_SESSION_OAUTH_TOKEN_SELECTION_SECTION_KEY}.${key} in ${fleetConfigFilePath} must be a number ${requirement}, but it is ${value}.`,
+    );
+  }
+  return value;
+};
+
+export const loadLiveSessionOauthTokenSelectionSettings = (
+  fleetConfigFilePath: string | null,
+): LiveSessionOauthTokenSelectionSettings => {
+  if (fleetConfigFilePath === null) {
+    return DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS;
+  }
+  const section = readSection(fleetConfigFilePath);
+  if (section === null) {
+    return DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS;
+  }
+  return {
+    maxConcurrentSessionCount: readBoundedNumber(
+      section,
+      'maxConcurrentSessionCount',
+      fleetConfigFilePath,
+      DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS.maxConcurrentSessionCount,
+      (value) => Number.isInteger(value) && value >= 1,
+      'integer of at least 1',
+    ),
+    fullSpeedFiveHourFreeRatio: readBoundedNumber(
+      section,
+      'fullSpeedFiveHourFreeRatio',
+      fleetConfigFilePath,
+      DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS.fullSpeedFiveHourFreeRatio,
+      (value) => value > 0 && value <= 1,
+      'above 0 and at most 1',
+    ),
+  };
+};

package/src/adapter/entry-points/cli/index.ts

@@ -59,6 +59,10 @@ import { IssueRepository } from '../../../domain/usecases/adapter-interfaces/Iss
 import { OauthTokenSelectHandler } from '../handlers/OauthTokenSelectHandler';
 import { LiveSessionOauthTokenSelectHandler } from '../handlers/LiveSessionOauthTokenSelectHandler';
 import { InTmuxByHumanSessionTokenCountHandler } from '../handlers/InTmuxByHumanSessionTokenCountHandler';
+import {
+  loadLiveSessionOauthTokenSelectionSettings,
+  resolveFleetConfigFilePath,
+} from './fleetConfig';
 
 type StartDaemonOptions = {
   projectUrl?: string;
@@ -127,6 +131,7 @@ type SelectOauthTokenOptions = {
 type SelectLiveSessionOauthTokenOptions = {
   tokenListJsonPath?: string;
   cacheDir?: string;
+  fleetConfigFilePath?: string;
 };
 
 type CountInTmuxByHumanSessionsPerTokenOptions = {
@@ -951,22 +956,29 @@ program
 program
   .command('selectLiveSessionOauthToken')
   .description(
-    'Print exactly one Claude Code OAuth token chosen for a new live interactive session. Among rate-limit-eligible tokens the choice is weighted-random, with each token weighted by its per-token selectionWeight (default 1), multiplied by how urgent its 7d window is (the free share of that window times 168 divided by the hours left before it resets, with those hours floored at 1), and divided by one plus its current live session count (by distinct CLAUDE_CODE_SESSION_ID found in running Claude Code processes). A token whose 7d window still holds unused allowance and resets soon is therefore chosen more often, while occupancy keeps sessions spread across tokens. When every eligible weight is identical, the choice stays deterministic and no random draw is made. The token string is written to stdout (pipeable); the per-candidate decision trace is written to stderr. Exits non-zero when no token passes the filter.',
+    'Print exactly one Claude Code OAuth token chosen for a new live interactive session. The choice is deterministic. Each rate-limit-eligible token gets a concurrent session limit of maxConcurrentSessionCount (default 10), scaled by its per-token selectionWeight (default 1). That limit is held at full value while the free share of the 5h window is at or above fullSpeedFiveHourFreeRatio (default 0.5) and is tapered in proportion below it, never dropping under 1; the 7d window never lowers the limit, so a weekly allowance that is about to expire is drained at full speed instead of being discarded unused. Among eligible tokens still under that limit the token whose 7d window resets soonest wins; ties go to the token carrying fewer live sessions (by distinct CLAUDE_CODE_SESSION_ID found in running Claude Code processes). When every eligible token is at its limit the soonest-resetting one is still returned. The token string is written to stdout (pipeable); the per-candidate decision trace is written to stderr. Exits non-zero when no token passes the filter.',
   )
   .option(
     '--tokenListJsonPath <path>',
-    'Path to the JSON array of { name, token, selectionWeight? } records. selectionWeight is an optional positive number (default 1) that biases how often this token is chosen among rate-limit-eligible candidates; a smaller weight is chosen proportionally less often and never bypasses eligibility filtering or starves a sole eligible token. Falls back to the CLAUDE_CODE_OAUTH_TOKEN_LIST_JSON_PATH environment variable.',
+    'Path to the JSON array of { name, token, selectionWeight? } records. selectionWeight is an optional positive number (default 1) that scales this token concurrent live session limit; a smaller weight allows fewer simultaneous sessions and never bypasses eligibility filtering or starves a sole eligible token. Falls back to the CLAUDE_CODE_OAUTH_TOKEN_LIST_JSON_PATH environment variable.',
   )
   .option(
     '--cacheDir <path>',
     'Directory holding per-token rate-limit cache files. Falls back to the TDPM_RATELIMIT_CACHE_DIR environment variable, then to ${XDG_CACHE_HOME:-~/.cache}/tdpm/ratelimit.',
   )
+  .option(
+    '--fleetConfigFilePath <path>',
+    'Path to the fleet-wide YAML config file holding the liveSessionOauthTokenSelection mapping (maxConcurrentSessionCount, fullSpeedFiveHourFreeRatio). Falls back to the TDPM_FLEET_CONFIG environment variable; when neither is set the built-in values are used. A key the file omits keeps its built-in value, and an unreadable file or an out-of-range value is reported as an error instead of being ignored.',
+  )
   .action((options: SelectLiveSessionOauthTokenOptions) => {
     const handler = new LiveSessionOauthTokenSelectHandler();
     const output = handler.handle({
       tokenListJsonPath: options.tokenListJsonPath ?? null,
       cacheDirectory: options.cacheDir ?? null,
       nowEpochSeconds: Date.now() / 1000,
+      selectionSettings: loadLiveSessionOauthTokenSelectionSettings(
+        resolveFleetConfigFilePath(options.fleetConfigFilePath ?? null),
+      ),
     });
 
     for (const line of output.diagnostics) {

package/src/adapter/entry-points/handlers/LiveSessionOauthTokenSelectHandler.test.ts

@@ -5,7 +5,10 @@ import {
   ClaudeLiveSession,
   ClaudeLiveSessionRepository,
 } from '../../../domain/usecases/adapter-interfaces/ClaudeLiveSessionRepository';
-import { LiveSessionOauthTokenSelectUseCase } from '../../../domain/usecases/LiveSessionOauthTokenSelectUseCase';
+import {
+  DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
+  LiveSessionOauthTokenSelectUseCase,
+} from '../../../domain/usecases/LiveSessionOauthTokenSelectUseCase';
 import { FABLE_LIMIT_TYPE, hashToken } from '../../proxy/RateLimitCache';
 import { LiveSessionOauthTokenSelectHandler } from './LiveSessionOauthTokenSelectHandler';
 
@@ -109,12 +112,10 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
 
   const buildHandler = (
     sessions: ClaudeLiveSession[],
-    random: () => number = () => 0.5,
   ): LiveSessionOauthTokenSelectHandler =>
     new LiveSessionOauthTokenSelectHandler(
       new LiveSessionOauthTokenSelectUseCase(),
       new FakeClaudeLiveSessionRepository(sessions),
-      random,
     );
 
   const writeFableRejectionCache = (token: string, resetsAt: number): void => {
@@ -157,6 +158,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedName).toBe('active');
@@ -165,7 +167,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
     );
   });
 
-  it('selects the eligible token with fewer live sessions for a draw inside its weight slice', () => {
+  it('selects the soonest resetting eligible token even when it already carries a live session', () => {
     writeTokenList([
       { name: 'busy', token: 'fake-busy' },
       { name: 'idle', token: 'fake-idle' },
@@ -183,18 +185,21 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       sevenDayReset: NOW + 6 * DAY,
     });
 
-    const handler = buildHandler(
-      [{ token: 'fake-busy', sessionKey: 'session-a' }],
-      () => 0.9,
-    );
+    const handler = buildHandler([
+      { token: 'fake-busy', sessionKey: 'session-a' },
+    ]);
     const output = handler.handle({
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
-    expect(output.selectedName).toBe('idle');
-    expect(output.selectedToken).toBe('fake-idle');
+    expect(output.selectedName).toBe('busy');
+    expect(output.selectedToken).toBe('fake-busy');
+    expect(output.diagnostics.join('\n')).toContain(
+      'busy: 1/10 live session(s)',
+    );
   });
 
   it('breaks an occupancy tie by the soonest 7d reset', () => {
@@ -223,6 +228,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedName).toBe('soon');
@@ -256,6 +262,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedName).toBe('oneSession');
@@ -286,6 +293,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedName).toBe('free');
@@ -305,6 +313,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedToken).toBeNull();
@@ -330,6 +339,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedToken).toBe('fake-free');
@@ -343,6 +353,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: null,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedToken).toBeNull();
@@ -357,6 +368,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedToken).toBeNull();
@@ -383,6 +395,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedName).toBe('active');
@@ -419,6 +432,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedName).toBe('active');
@@ -446,6 +460,7 @@ describe('LiveSessionOauthTokenSelectHandler', () => {
       tokenListJsonPath: tokenListPath,
       cacheDirectory,
       nowEpochSeconds: NOW,
+      selectionSettings: DEFAULT_LIVE_SESSION_OAUTH_TOKEN_SELECTION_SETTINGS,
     });
 
     expect(output.selectedToken).toBeNull();

package/src/adapter/entry-points/handlers/LiveSessionOauthTokenSelectHandler.ts

@@ -2,13 +2,13 @@ import { ClaudeLiveSessionRepository } from '../../../domain/usecases/adapter-in
 import {
   LiveSessionOauthTokenSelectResult,
   LiveSessionOauthTokenSelectUseCase,
+  LiveSessionOauthTokenSelectionSettings,
 } from '../../../domain/usecases/LiveSessionOauthTokenSelectUseCase';
 import {
   DEFAULT_SELECTION_WEIGHT,
   FIVE_HOUR_MIN_FREE_RATIO,
   OauthTokenCandidate,
   SEVEN_DAY_MIN_FREE_RATIO,
-  SelectionRandom,
 } from '../../../domain/usecases/OauthTokenSelectUseCase';
 import { ProcClaudeLiveSessionRepository } from '../../repositories/ProcClaudeLiveSessionRepository';
 import { FABLE_LIMIT_TYPE, readRateLimit } from '../../proxy/RateLimitCache';
@@ -22,6 +22,7 @@ export type LiveSessionOauthTokenSelectHandlerInput = {
   tokenListJsonPath: string | null;
   cacheDirectory: string | null;
   nowEpochSeconds: number;
+  selectionSettings: LiveSessionOauthTokenSelectionSettings;
 };
 
 export type LiveSessionOauthTokenSelectHandlerOutput = {
@@ -34,7 +35,6 @@ export class LiveSessionOauthTokenSelectHandler {
   constructor(
     private readonly useCase: LiveSessionOauthTokenSelectUseCase = new LiveSessionOauthTokenSelectUseCase(),
     private readonly liveSessionRepository: ClaudeLiveSessionRepository = new ProcClaudeLiveSessionRepository(),
-    private readonly random: SelectionRandom = Math.random,
   ) {}
 
   handle = (
@@ -98,7 +98,7 @@ export class LiveSessionOauthTokenSelectHandler {
       candidates,
       liveSessions,
       input.nowEpochSeconds,
-      this.random,
+      input.selectionSettings,
     );
 
     return {
@@ -119,7 +119,7 @@ export class LiveSessionOauthTokenSelectHandler {
       const status = metric.eligible
         ? 'eligible'
         : `excluded (${metric.exclusionReason})`;
-      return `${metric.name}: ${metric.liveSessionCount} live session(s), 5h ${Math.round(metric.fiveHourFreeRatio * 100)}% free, 7d ${Math.round(metric.sevenDayFreeRatio * 100)}% free, 7d-end in ${secondsUntilSevenDayEnd}s -> ${status}`;
+      return `${metric.name}: ${metric.liveSessionCount}/${metric.concurrentSessionLimit} live session(s), 5h ${Math.round(metric.fiveHourFreeRatio * 100)}% free, 7d ${Math.round(metric.sevenDayFreeRatio * 100)}% free, 7d-end in ${secondsUntilSevenDayEnd}s -> ${status}`;
     });
 
     if (result.selected === null) {
@@ -128,7 +128,7 @@ export class LiveSessionOauthTokenSelectHandler {
       );
     } else {
       lines.push(
-        `Selected ${result.selected.name} (weighted by how soon the 7d window resets, how much of it is free, and how few live sessions the token carries).`,
+        `Selected ${result.selected.name} (the soonest-resetting 7d window among tokens still under their concurrent session limit, which is set by the free share of the 5h window alone).`,
       );
     }