github-issue-tower-defence-management 1.132.0 → 1.133.0

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

@@ -4,6 +4,7 @@ import {
   LiveSessionOauthTokenSelectUseCase,
 } from '../../../domain/usecases/LiveSessionOauthTokenSelectUseCase';
 import {
+  DEFAULT_SELECTION_WEIGHT,
   FIVE_HOUR_MIN_FREE_RATIO,
   OauthTokenCandidate,
   SEVEN_DAY_MIN_FREE_RATIO,
@@ -61,30 +62,33 @@ export class LiveSessionOauthTokenSelectHandler {
 
     const cacheDirectory = resolveCacheDirectory(input.cacheDirectory);
 
-    const candidates: OauthTokenCandidate[] = entries.map(({ name, token }) => {
-      const snapshot = readRateLimit(token, cacheDirectory);
-      const fableLimit = snapshot?.modelWeeklyLimits[FABLE_LIMIT_TYPE];
-      const fableRejected =
-        fableLimit !== undefined &&
-        fableLimit.rejected &&
-        input.nowEpochSeconds <= fableLimit.resetsAt;
-      return {
-        name,
-        token,
-        snapshot:
-          snapshot === null
-            ? null
-            : {
-                fiveHourUtilization: snapshot.fiveHourUtilization,
-                fiveHourReset: snapshot.fiveHourReset,
-                sevenDayUtilization: snapshot.sevenDayUtilization,
-                sevenDayReset: snapshot.sevenDayReset,
-              },
-        subscriptionDisabled: snapshot?.subscriptionDisabled ?? false,
-        unifiedRejected: snapshot?.unifiedRejected ?? false,
-        fableRejected,
-      };
-    });
+    const candidates: OauthTokenCandidate[] = entries.map(
+      ({ name, token, selectionWeight }) => {
+        const snapshot = readRateLimit(token, cacheDirectory);
+        const fableLimit = snapshot?.modelWeeklyLimits[FABLE_LIMIT_TYPE];
+        const fableRejected =
+          fableLimit !== undefined &&
+          fableLimit.rejected &&
+          input.nowEpochSeconds <= fableLimit.resetsAt;
+        return {
+          name,
+          token,
+          snapshot:
+            snapshot === null
+              ? null
+              : {
+                  fiveHourUtilization: snapshot.fiveHourUtilization,
+                  fiveHourReset: snapshot.fiveHourReset,
+                  sevenDayUtilization: snapshot.sevenDayUtilization,
+                  sevenDayReset: snapshot.sevenDayReset,
+                },
+          subscriptionDisabled: snapshot?.subscriptionDisabled ?? false,
+          unifiedRejected: snapshot?.unifiedRejected ?? false,
+          fableRejected,
+          selectionWeight: selectionWeight ?? DEFAULT_SELECTION_WEIGHT,
+        };
+      },
+    );
 
     const liveSessions = this.liveSessionRepository.listLiveSessions();
 

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

@@ -1,4 +1,5 @@
 import {
+  DEFAULT_SELECTION_WEIGHT,
   OauthTokenCandidate,
   OauthTokenSelectResult,
   OauthTokenSelectUseCase,
@@ -83,30 +84,33 @@ export class OauthTokenSelectHandler {
 
     const cacheDirectory = resolveCacheDirectory(input.cacheDirectory);
 
-    const candidates: OauthTokenCandidate[] = entries.map(({ name, token }) => {
-      const snapshot = readRateLimit(token, cacheDirectory);
-      const fableLimit = snapshot?.modelWeeklyLimits[FABLE_LIMIT_TYPE];
-      const fableRejected =
-        fableLimit !== undefined &&
-        fableLimit.rejected &&
-        input.nowEpochSeconds <= fableLimit.resetsAt;
-      return {
-        name,
-        token,
-        snapshot:
-          snapshot === null
-            ? null
-            : {
-                fiveHourUtilization: snapshot.fiveHourUtilization,
-                fiveHourReset: snapshot.fiveHourReset,
-                sevenDayUtilization: snapshot.sevenDayUtilization,
-                sevenDayReset: snapshot.sevenDayReset,
-              },
-        subscriptionDisabled: snapshot?.subscriptionDisabled ?? false,
-        unifiedRejected: snapshot?.unifiedRejected ?? false,
-        fableRejected,
-      };
-    });
+    const candidates: OauthTokenCandidate[] = entries.map(
+      ({ name, token, selectionWeight }) => {
+        const snapshot = readRateLimit(token, cacheDirectory);
+        const fableLimit = snapshot?.modelWeeklyLimits[FABLE_LIMIT_TYPE];
+        const fableRejected =
+          fableLimit !== undefined &&
+          fableLimit.rejected &&
+          input.nowEpochSeconds <= fableLimit.resetsAt;
+        return {
+          name,
+          token,
+          snapshot:
+            snapshot === null
+              ? null
+              : {
+                  fiveHourUtilization: snapshot.fiveHourUtilization,
+                  fiveHourReset: snapshot.fiveHourReset,
+                  sevenDayUtilization: snapshot.sevenDayUtilization,
+                  sevenDayReset: snapshot.sevenDayReset,
+                },
+          subscriptionDisabled: snapshot?.subscriptionDisabled ?? false,
+          unifiedRejected: snapshot?.unifiedRejected ?? false,
+          fableRejected,
+          selectionWeight: selectionWeight ?? DEFAULT_SELECTION_WEIGHT,
+        };
+      },
+    );
 
     const result = this.useCase.run(candidates, input.nowEpochSeconds);
 

package/src/adapter/proxy/TokenListLoader.test.ts

@@ -50,6 +50,58 @@ describe('loadTokenEntries', () => {
     fs.writeFileSync(filePath, JSON.stringify([{ name: 'no-token' }]));
     expect(loadTokenEntries(filePath)).toBeNull();
   });
+
+  it('should include selectionWeight when the entry has a finite number', () => {
+    const filePath = path.join(tempDir, 'tokens.json');
+    fs.writeFileSync(
+      filePath,
+      JSON.stringify([
+        { name: 'alice', token: 'token-a', selectionWeight: 0.8 },
+        { name: 'bob', token: 'token-b', selectionWeight: 2 },
+      ]),
+    );
+    expect(loadTokenEntries(filePath)).toEqual([
+      { name: 'alice', token: 'token-a', selectionWeight: 0.8 },
+      { name: 'bob', token: 'token-b', selectionWeight: 2 },
+    ]);
+  });
+
+  it('should omit selectionWeight when it is absent', () => {
+    const filePath = path.join(tempDir, 'tokens.json');
+    fs.writeFileSync(
+      filePath,
+      JSON.stringify([{ name: 'alice', token: 'token-a' }]),
+    );
+    expect(loadTokenEntries(filePath)).toEqual([
+      { name: 'alice', token: 'token-a' },
+    ]);
+  });
+
+  it('should ignore a non-numeric selectionWeight', () => {
+    const filePath = path.join(tempDir, 'tokens.json');
+    fs.writeFileSync(
+      filePath,
+      JSON.stringify([
+        { name: 'alice', token: 'token-a', selectionWeight: 'high' },
+        { name: 'bob', token: 'token-b', selectionWeight: null },
+      ]),
+    );
+    expect(loadTokenEntries(filePath)).toEqual([
+      { name: 'alice', token: 'token-a' },
+      { name: 'bob', token: 'token-b' },
+    ]);
+  });
+
+  it('should carry selectionWeight on a positionally named entry', () => {
+    const filePath = path.join(tempDir, 'tokens.json');
+    fs.writeFileSync(
+      filePath,
+      JSON.stringify([{ token: 'token-a', selectionWeight: 0.5 }]),
+    );
+    expect(loadTokenEntries(filePath)).toEqual([
+      { name: 'token-1', token: 'token-a', selectionWeight: 0.5 },
+    ]);
+  });
 });
 
 describe('TokenListLoader', () => {

package/src/adapter/proxy/TokenListLoader.ts

@@ -18,8 +18,19 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
 export type TokenEntry = {
   name: string;
   token: string;
+  selectionWeight?: number;
 };
 
+const parseSelectionWeight = (value: unknown): number | null =>
+  typeof value === 'number' && Number.isFinite(value) ? value : null;
+
+const buildTokenEntry = (
+  name: string,
+  token: string,
+  selectionWeight: number | null,
+): TokenEntry =>
+  selectionWeight === null ? { name, token } : { name, token, selectionWeight };
+
 export const loadTokenEntries = (jsonPath: string): TokenEntry[] | null => {
   const resolved = expandHome(jsonPath);
   if (!fs.existsSync(resolved)) return null;
@@ -34,12 +45,21 @@ export const loadTokenEntries = (jsonPath: string): TokenEntry[] | null => {
         typeof entry.token === 'string' &&
         typeof entry.name === 'string'
       ) {
-        entries.push({ name: entry.name, token: entry.token });
+        entries.push(
+          buildTokenEntry(
+            entry.name,
+            entry.token,
+            parseSelectionWeight(entry.selectionWeight),
+          ),
+        );
       } else if (isRecord(entry) && typeof entry.token === 'string') {
-        entries.push({
-          name: `token-${entries.length + 1}`,
-          token: entry.token,
-        });
+        entries.push(
+          buildTokenEntry(
+            `token-${entries.length + 1}`,
+            entry.token,
+            parseSelectionWeight(entry.selectionWeight),
+          ),
+        );
       }
     }
     return entries.length > 0 ? entries : null;

package/src/adapter/repositories/NodeTmuxSessionRepository.test.ts

@@ -123,6 +123,61 @@ describe('NodeTmuxSessionRepository', () => {
         'Failed to kill tmux session "missing_session": exit code 1',
       );
     });
+
+    it('stops the systemd user scope for the session after killing it, wrapping the stop with reset-failed', async () => {
+      const runner = createMockRunner();
+      runner.runCommand.mockResolvedValue({
+        stdout: '',
+        stderr: '',
+        exitCode: 0,
+      });
+      const repository = new NodeTmuxSessionRepository(runner);
+
+      await repository.killSession('https_//github_com/owner/repo/issues/9');
+
+      const expectedScopeUnitName =
+        'cl-https---github-com-owner-repo-issues-9.scope';
+      const calls = runner.runCommand.mock.calls;
+      expect(calls[0]).toEqual([
+        'tmux',
+        ['kill-session', '-t', 'https_//github_com/owner/repo/issues/9'],
+      ]);
+      const systemctlCalls = calls.filter((call) => call[0] === 'systemctl');
+      expect(systemctlCalls).toEqual([
+        ['systemctl', ['--user', 'reset-failed', expectedScopeUnitName]],
+        ['systemctl', ['--user', 'stop', expectedScopeUnitName]],
+        ['systemctl', ['--user', 'reset-failed', expectedScopeUnitName]],
+      ]);
+    });
+
+    it('logs an error but does not throw when stopping the systemd user scope fails', async () => {
+      const runner = createMockRunner();
+      runner.runCommand.mockImplementation(async (program: string) => {
+        if (program === 'systemctl') {
+          return {
+            stdout: '',
+            stderr: 'Failed to stop cl-leader-session.scope: Unit not loaded.',
+            exitCode: 5,
+          };
+        }
+        return { stdout: '', stderr: '', exitCode: 0 };
+      });
+      const errorSpy = jest
+        .spyOn(console, 'error')
+        .mockImplementation(() => undefined);
+      const repository = new NodeTmuxSessionRepository(runner);
+
+      await expect(
+        repository.killSession('leader_session'),
+      ).resolves.toBeUndefined();
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'Failed to stop systemd user scope "cl-leader-session.scope"',
+        ),
+      );
+      errorSpy.mockRestore();
+    });
   });
 
   describe('listInteractiveProcessCommandLines', () => {

package/src/adapter/repositories/NodeTmuxSessionRepository.ts

@@ -1,6 +1,7 @@
 import { LocalCommandRunner } from '../../domain/usecases/adapter-interfaces/LocalCommandRunner';
 import { TmuxSessionRepository } from '../../domain/usecases/adapter-interfaces/TmuxSessionRepository';
 import { LiveTmuxSession } from '../../domain/entities/LiveTmuxSession';
+import { clSessionScopeUnitName } from './clSessionScopeUnitName';
 
 export class NodeTmuxSessionRepository implements TmuxSessionRepository {
   constructor(private readonly localCommandRunner: LocalCommandRunner) {}
@@ -85,5 +86,31 @@ export class NodeTmuxSessionRepository implements TmuxSessionRepository {
         }`,
       );
     }
+    await this.stopClSessionScope(sessionName);
+  };
+
+  private stopClSessionScope = async (sessionName: string): Promise<void> => {
+    const scopeUnitName = clSessionScopeUnitName(sessionName);
+    await this.localCommandRunner.runCommand('systemctl', [
+      '--user',
+      'reset-failed',
+      scopeUnitName,
+    ]);
+    const { stderr, exitCode } = await this.localCommandRunner.runCommand(
+      'systemctl',
+      ['--user', 'stop', scopeUnitName],
+    );
+    await this.localCommandRunner.runCommand('systemctl', [
+      '--user',
+      'reset-failed',
+      scopeUnitName,
+    ]);
+    if (exitCode !== 0) {
+      console.error(
+        `Failed to stop systemd user scope "${scopeUnitName}" for tmux session "${sessionName}": exit code ${exitCode}${
+          stderr ? `: ${stderr}` : ''
+        }`,
+      );
+    }
   };
 }

package/src/adapter/repositories/clSessionScopeUnitName.test.ts

@@ -0,0 +1,76 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { toTmuxSessionName } from '../../domain/usecases/intmux/InTmuxByHumanSessionReconcileUseCase';
+import { clSessionScopeUnitName } from './clSessionScopeUnitName';
+
+const issueUrls = [
+  'https://github.com/HiromiShikata/secretary/issues/1261',
+  'https://github.com/owner/repo/issues/9',
+  'https://github.com/owner/repo/pull/42',
+];
+
+const sessionNames = [
+  ...issueUrls,
+  ...issueUrls.map((url) => toTmuxSessionName(url)),
+  'idle_no_task_session',
+  'plain-session',
+  'ALLCAPS123',
+];
+
+const canonicalScopeLibPath = (): string | null => {
+  const explicitPath = process.env.CL_SCOPE_LIB_PATH;
+  if (explicitPath !== undefined && existsSync(explicitPath)) {
+    return explicitPath;
+  }
+  const defaultPath = join(
+    homedir(),
+    'git',
+    'secretary',
+    'machine',
+    'sk',
+    'sh',
+    'cl-scope-lib.sh',
+  );
+  return existsSync(defaultPath) ? defaultPath : null;
+};
+
+describe('clSessionScopeUnitName cross-component contract', () => {
+  it('derives a systemd-safe scope unit name of the form cl-<safe>.scope for every session form', () => {
+    for (const sessionName of sessionNames) {
+      const unitName = clSessionScopeUnitName(sessionName);
+      expect(unitName.startsWith('cl-')).toBe(true);
+      expect(unitName.endsWith('.scope')).toBe(true);
+      const core = unitName.slice(0, -'.scope'.length);
+      expect(/^[A-Za-z0-9._-]+$/.test(core)).toBe(true);
+    }
+  });
+
+  it('collapses a raw issue URL and its tmux-normalized session name to the same scope unit name', () => {
+    for (const url of issueUrls) {
+      expect(clSessionScopeUnitName(toTmuxSessionName(url))).toBe(
+        clSessionScopeUnitName(url),
+      );
+    }
+  });
+
+  const libPath = canonicalScopeLibPath();
+  const canonicalContractTest = libPath === null ? it.skip : it;
+  canonicalContractTest(
+    'matches the canonical cl_scope_unit_name derivation shared with cl',
+    () => {
+      if (libPath === null) {
+        return;
+      }
+      for (const sessionName of sessionNames) {
+        const canonicalUnitName = execFileSync(
+          'bash',
+          [libPath, 'unit-name', sessionName],
+          { encoding: 'utf8' },
+        );
+        expect(clSessionScopeUnitName(sessionName)).toBe(canonicalUnitName);
+      }
+    },
+  );
+});

package/src/adapter/repositories/clSessionScopeUnitName.ts

@@ -0,0 +1,5 @@
+export const clSessionScopeUnitName = (sessionName: string): string => {
+  const safe = sessionName.replace(/[^a-zA-Z0-9]/g, '-');
+  const raw = `cl-${safe}`;
+  return `${raw.replace(/[^a-zA-Z0-9._-]/g, '-')}.scope`;
+};

package/src/domain/usecases/LiveSessionOauthTokenSelectUseCase.test.ts

@@ -209,3 +209,77 @@ describe('LiveSessionOauthTokenSelectUseCase', () => {
     expect(rejected?.exclusionReason).toContain('rejected');
   });
 });
+
+const sweepingRandom = (count: number): (() => number) => {
+  let index = 0;
+  return () => {
+    const value = (index + 0.5) / count;
+    index += 1;
+    return value;
+  };
+};
+
+const throwingRandom = (): number => {
+  throw new Error('random source must not be consulted');
+};
+
+const withSelectionWeight = (
+  base: OauthTokenCandidate,
+  selectionWeight: number,
+): OauthTokenCandidate => ({ ...base, selectionWeight });
+
+describe('LiveSessionOauthTokenSelectUseCase selectionWeight', () => {
+  const useCase = new LiveSessionOauthTokenSelectUseCase();
+
+  it('keeps the deterministic fewest-live-sessions selection and never consults random when weights are uniform', () => {
+    const result = useCase.run(
+      [candidate('busy', snapshot({})), candidate('idle', snapshot({}))],
+      [session('busy', 'session-a')],
+      NOW,
+      throwingRandom,
+    );
+
+    expect(result.selected?.name).toBe('idle');
+  });
+
+  it('selects a sole eligible low-weight token without consulting random (no starvation)', () => {
+    const result = useCase.run(
+      [
+        withSelectionWeight(candidate('lowWeightOnly', snapshot({})), 0.01),
+        candidate('blocked', snapshot({ fiveHourUtilization: 0.9 })),
+      ],
+      [],
+      NOW,
+      throwingRandom,
+    );
+
+    expect(result.selected?.name).toBe('lowWeightOnly');
+  });
+
+  it('chooses a lower-weight token proportionally less often among equally-idle eligible candidates', () => {
+    const count = 1000;
+    const random = sweepingRandom(count);
+    const selectionCounts = new Map<string, number>();
+
+    for (let i = 0; i < count; i += 1) {
+      const result = useCase.run(
+        [
+          withSelectionWeight(candidate('heavy', snapshot({})), 1),
+          withSelectionWeight(candidate('light', snapshot({})), 0.5),
+        ],
+        [],
+        NOW,
+        random,
+      );
+      const name = result.selected?.name ?? 'none';
+      selectionCounts.set(name, (selectionCounts.get(name) ?? 0) + 1);
+    }
+
+    const heavy = selectionCounts.get('heavy') ?? 0;
+    const light = selectionCounts.get('light') ?? 0;
+    expect(heavy + light).toBe(count);
+    expect(light).toBeGreaterThan(0);
+    expect(light).toBeLessThan(heavy);
+    expect(Math.abs(light / count - 1 / 3)).toBeLessThan(0.02);
+  });
+});

package/src/domain/usecases/LiveSessionOauthTokenSelectUseCase.ts

@@ -2,6 +2,8 @@ import { ClaudeLiveSession } from './adapter-interfaces/ClaudeLiveSessionReposit
 import {
   OauthTokenCandidate,
   OauthTokenSelectUseCase,
+  SelectionRandom,
+  selectWeightedCandidate,
 } from './OauthTokenSelectUseCase';
 
 export type LiveSessionOauthTokenCandidateMetrics = {
@@ -28,10 +30,12 @@ export class LiveSessionOauthTokenSelectUseCase {
     candidates: OauthTokenCandidate[],
     liveSessions: ClaudeLiveSession[],
     nowEpochSeconds: number,
+    random: SelectionRandom = Math.random,
   ): LiveSessionOauthTokenSelectResult => {
     const rateLimitResult = this.rateLimitSelectUseCase.run(
       candidates,
       nowEpochSeconds,
+      () => 0,
     );
     const liveSessionCountByToken = this.liveSessionCountByToken(liveSessions);
 
@@ -60,13 +64,20 @@ export class LiveSessionOauthTokenSelectUseCase {
       return { selected: null, metrics };
     }
 
-    const best = eligible.reduce((bestEntry, currentEntry) =>
+    const deterministicBest = eligible.reduce((bestEntry, currentEntry) =>
       this.preferred(currentEntry.metric, bestEntry.metric)
         ? currentEntry
         : bestEntry,
     );
 
-    return { selected: best.candidate, metrics };
+    const selected = selectWeightedCandidate(
+      eligible,
+      (entry) => entry.candidate,
+      deterministicBest,
+      random,
+    );
+
+    return { selected: selected.candidate, metrics };
   };
 
   private preferred = (