github-issue-tower-defence-management 2.10.2 → 2.12.0

package/src/adapter/entry-points/console/ui-dist/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>TDPM Console</title>
-    <script type="module" crossorigin src="/assets/index-BSa2JTna.js"></script>
+    <script type="module" crossorigin src="/assets/index-CvJgSVoN.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CLHvrafO.css">
   </head>
   <body>

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

@@ -68,6 +68,7 @@ import { UpdateIssueStatusByLabelUseCase } from '../../../domain/usecases/Update
 import { IssueNoStatusUpdateUseCase } from '../../../domain/usecases/IssueNoStatusUpdateUseCase';
 import { StartPreparationUseCase } from '../../../domain/usecases/StartPreparationUseCase';
 import { NodeLocalCommandRunner } from '../../repositories/NodeLocalCommandRunner';
+import { CliGitHubGraphqlRateLimitRepository } from '../../repositories/CliGitHubGraphqlRateLimitRepository';
 import { ProcTakeOwnershipSpawnRepository } from '../../repositories/ProcTakeOwnershipSpawnRepository';
 import { ProxyClaudeTokenUsageRepository } from '../../repositories/ProxyClaudeTokenUsageRepository';
 import { ProxyRateLimitCacheRepository } from '../../repositories/ProxyRateLimitCacheRepository';
@@ -499,6 +500,7 @@ export class HandleScheduledEventUseCaseHandler {
       nodeLocalCommandRunner,
       claudeTokenUsageRepository,
       new ProcTakeOwnershipSpawnRepository(),
+      new CliGitHubGraphqlRateLimitRepository(nodeLocalCommandRunner),
     );
     const proxyRateLimitCacheRepository = new ProxyRateLimitCacheRepository(
       mergedInput.claudeCodeOauthTokenListJsonPath ?? null,

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

@@ -0,0 +1,71 @@
+import { LocalCommandRunner } from '../../domain/usecases/adapter-interfaces/LocalCommandRunner';
+import { CliGitHubGraphqlRateLimitRepository } from './CliGitHubGraphqlRateLimitRepository';
+
+type Mocked<T> = jest.Mocked<T> & jest.MockedObject<T>;
+
+describe('CliGitHubGraphqlRateLimitRepository', () => {
+  let mockLocalCommandRunner: Mocked<LocalCommandRunner>;
+  let repository: CliGitHubGraphqlRateLimitRepository;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    mockLocalCommandRunner = {
+      runCommand: jest.fn(),
+      spawnInteractive: jest.fn(),
+    };
+    repository = new CliGitHubGraphqlRateLimitRepository(
+      mockLocalCommandRunner,
+    );
+  });
+
+  it('returns the remaining GraphQL request count when gh succeeds', async () => {
+    mockLocalCommandRunner.runCommand.mockResolvedValue({
+      stdout: '4873\n',
+      stderr: '',
+      exitCode: 0,
+    });
+
+    const result = await repository.getRemainingRequestCount();
+
+    expect(result).toBe(4873);
+    expect(mockLocalCommandRunner.runCommand.mock.calls).toEqual([
+      ['gh', ['api', 'rate_limit', '--jq', '.resources.graphql.remaining']],
+    ]);
+  });
+
+  it('returns null when gh exits with a non-zero code', async () => {
+    mockLocalCommandRunner.runCommand.mockResolvedValue({
+      stdout: '',
+      stderr: 'error: authentication required',
+      exitCode: 1,
+    });
+
+    const result = await repository.getRemainingRequestCount();
+
+    expect(result).toBeNull();
+  });
+
+  it('returns null when the output is not a valid integer', async () => {
+    mockLocalCommandRunner.runCommand.mockResolvedValue({
+      stdout: 'not-a-number\n',
+      stderr: '',
+      exitCode: 0,
+    });
+
+    const result = await repository.getRemainingRequestCount();
+
+    expect(result).toBeNull();
+  });
+
+  it('returns zero when the remaining count is zero', async () => {
+    mockLocalCommandRunner.runCommand.mockResolvedValue({
+      stdout: '0\n',
+      stderr: '',
+      exitCode: 0,
+    });
+
+    const result = await repository.getRemainingRequestCount();
+
+    expect(result).toBe(0);
+  });
+});

package/src/adapter/repositories/CliGitHubGraphqlRateLimitRepository.ts

@@ -0,0 +1,21 @@
+import { GitHubGraphqlRateLimitRepository } from '../../domain/usecases/adapter-interfaces/GitHubGraphqlRateLimitRepository';
+import { LocalCommandRunner } from '../../domain/usecases/adapter-interfaces/LocalCommandRunner';
+
+export class CliGitHubGraphqlRateLimitRepository implements GitHubGraphqlRateLimitRepository {
+  constructor(private readonly localCommandRunner: LocalCommandRunner) {}
+
+  getRemainingRequestCount = async (): Promise<number | null> => {
+    const result = await this.localCommandRunner.runCommand('gh', [
+      'api',
+      'rate_limit',
+      '--jq',
+      '.resources.graphql.remaining',
+    ]);
+    if (result.exitCode !== 0) {
+      return null;
+    }
+    const trimmed = result.stdout.trim();
+    const parsed = Number(trimmed);
+    return trimmed !== '' && Number.isInteger(parsed) ? parsed : null;
+  };
+}

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

@@ -1,8 +1,56 @@
 import dotenv from 'dotenv';
-import { KySlackRepository } from './KySlackRepository';
 import fs from 'fs';
 import https from 'https';
 import path from 'path';
+import { KySlackRepository } from './KySlackRepository';
+
+describe('KySlackRepository', () => {
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  describe('postMessageToDirectMessage', () => {
+    it('does not hang on 429 Retry-After responses from Slack', async () => {
+      jest.useFakeTimers();
+
+      jest.spyOn(globalThis, 'fetch').mockResolvedValue(
+        new Response('{"ok":false}', {
+          status: 429,
+          headers: { 'Retry-After': '30' },
+        }),
+      );
+
+      const slackRepository = new KySlackRepository('xoxp-test-token-unit');
+
+      // Attach .catch() immediately to prevent unhandled rejection when the
+      // promise rejects during jest.advanceTimersByTimeAsync below.
+      const settledValue: { value: unknown } = { value: 'not-yet-settled' };
+      slackRepository
+        .postMessageToDirectMessage('test message', 'non-existent-user')
+        .then(() => {
+          settledValue.value = 'resolved';
+        })
+        .catch((e: unknown) => {
+          settledValue.value = e;
+        });
+
+      // Advance 60 seconds of fake time.
+      // With maxRetryAfter bounded (e.g. 10s), all 3 retry delays (3×10s=30s) fire
+      // within this window, exhausting retries and settling the promise.
+      // With the default maxRetryAfter=INFINITY, only 2 of 3 delays fire (2×30s=60s),
+      // leaving the promise pending — causing CI to hang for the full Jest timeout.
+      await jest.advanceTimersByTimeAsync(60000);
+      jest.clearAllTimers();
+      jest.useRealTimers();
+
+      // Drain microtasks so the .then()/.catch() callbacks above have run.
+      await Promise.resolve();
+
+      expect(settledValue.value).not.toBe('not-yet-settled');
+    }, 5000);
+  });
+});
 
 dotenv.config();
 

package/src/adapter/repositories/KySlackRepository.ts

@@ -1,6 +1,6 @@
-import ky from 'ky';
 import fs from 'fs';
-import { SlackRepository } from '../../domain/usecases/adapter-interfaces/SlackRepository';
+import ky from 'ky';
+import type { SlackRepository } from '../../domain/usecases/adapter-interfaces/SlackRepository';
 
 type ConversationsListResponse = {
   ok: boolean;
@@ -87,6 +87,7 @@ export class KySlackRepository implements SlackRepository {
         limit: 3,
         methods: ['get', 'post'],
         statusCodes: [429, 500, 502, 503, 504],
+        maxRetryAfter: 10000,
       },
     });
   }

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

@@ -194,6 +194,9 @@ describe('ConflictedIssueRevertUseCase', () => {
 
       await useCase.run({ projectUrl });
 
+      expect(mockIssueRepository.updateBranch).toHaveBeenCalledWith(
+        conflictedPr.url,
+      );
       expect(mockIssueRepository.updateStatus).toHaveBeenCalledWith(
         mockProject,
         issue,
@@ -205,6 +208,36 @@ describe('ConflictedIssueRevertUseCase', () => {
       );
     });
 
+    it('should not update status or post comment when Awaiting Workspace PR update-branch succeeds', async () => {
+      const issue = createMockIssue({ status: 'Awaiting Workspace' });
+      const prItem = createMockPrItem({
+        url: 'https://github.com/user/repo/pull/1',
+        closingIssueReferenceUrls: [issue.url],
+      });
+      mockIssueRepository.getAllIssues.mockResolvedValue({
+        project: mockProject,
+        issues: [issue, prItem],
+        cacheUsed: false,
+      });
+      const conflictedPr = createMockRelatedPullRequest({
+        url: prItem.url,
+        isConflicted: true,
+        mergeable: 'CONFLICTING',
+      });
+      mockIssueRepository.getOpenPullRequests.mockResolvedValue(
+        new Map([[conflictedPr.url, conflictedPr]]),
+      );
+      mockIssueRepository.updateBranch.mockResolvedValue(true);
+
+      await useCase.run({ projectUrl });
+
+      expect(mockIssueRepository.updateBranch).toHaveBeenCalledWith(
+        conflictedPr.url,
+      );
+      expect(mockIssueRepository.updateStatus).not.toHaveBeenCalled();
+      expect(mockIssueCommentRepository.createComment).not.toHaveBeenCalled();
+    });
+
     it('should skip PR items when scanning for target task issues', async () => {
       const prIssue = createMockIssue({
         url: 'https://github.com/user/repo/issues/1',
@@ -317,6 +350,9 @@ describe('ConflictedIssueRevertUseCase', () => {
 
       await useCase.run({ projectUrl });
 
+      expect(mockIssueRepository.updateBranch).toHaveBeenCalledWith(
+        conflictedPr.url,
+      );
       expect(mockIssueRepository.updateStatus).toHaveBeenCalledWith(
         mockProject,
         issue,
@@ -328,6 +364,44 @@ describe('ConflictedIssueRevertUseCase', () => {
       );
     });
 
+    it('should propagate errors thrown by updateBranch', async () => {
+      const issue = createMockIssue({
+        url: 'https://github.com/user/repo/issues/1',
+        status: 'Preparation',
+      });
+      const prItem = createMockPrItem({
+        url: 'https://github.com/user/repo/pull/1',
+        closingIssueReferenceUrls: [issue.url],
+      });
+      mockIssueRepository.getAllIssues.mockResolvedValue({
+        project: mockProject,
+        issues: [issue, prItem],
+        cacheUsed: false,
+      });
+      const conflictedPr = createMockRelatedPullRequest({
+        url: prItem.url,
+        isConflicted: true,
+        mergeable: 'CONFLICTING',
+      });
+      mockIssueRepository.getOpenPullRequests.mockResolvedValue(
+        new Map([[conflictedPr.url, conflictedPr]]),
+      );
+      mockIssueRepository.updateBranch.mockRejectedValue(
+        new Error(
+          'Failed to update branch for PR https://github.com/user/repo/pull/1: 500 Internal Server Error',
+        ),
+      );
+
+      await expect(useCase.run({ projectUrl })).rejects.toThrow(
+        'Failed to update branch for PR',
+      );
+      expect(mockIssueRepository.updateBranch).toHaveBeenCalledWith(
+        conflictedPr.url,
+      );
+      expect(mockIssueRepository.updateStatus).not.toHaveBeenCalled();
+      expect(mockIssueCommentRepository.createComment).not.toHaveBeenCalled();
+    });
+
     it('should not update status or post comment when update-branch succeeds for the conflicted PR', async () => {
       const issue = createMockIssue({
         url: 'https://github.com/user/repo/issues/1',

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

@@ -10,6 +10,7 @@ import { ProjectRepository } from './adapter-interfaces/ProjectRepository';
 import { LocalCommandRunner } from './adapter-interfaces/LocalCommandRunner';
 import { ClaudeTokenUsageRepository } from './adapter-interfaces/ClaudeTokenUsageRepository';
 import { TakeOwnershipSpawnRepository } from './adapter-interfaces/TakeOwnershipSpawnRepository';
+import { GitHubGraphqlRateLimitRepository } from './adapter-interfaces/GitHubGraphqlRateLimitRepository';
 import { ClaudeTokenUsage } from '../entities/ClaudeTokenUsage';
 import { Issue } from '../entities/Issue';
 import { FieldOption, Project } from '../entities/Project';
@@ -109,6 +110,7 @@ describe('StartPreparationUseCase', () => {
   let mockLocalCommandRunner: Mocked<LocalCommandRunner>;
   let mockClaudeTokenUsageRepository: Mocked<ClaudeTokenUsageRepository>;
   let mockTakeOwnershipSpawnRepository: Mocked<TakeOwnershipSpawnRepository>;
+  let mockGitHubGraphqlRateLimitRepository: Mocked<GitHubGraphqlRateLimitRepository>;
   let mockProject: Project;
   beforeEach(() => {
     jest.resetAllMocks();
@@ -144,12 +146,16 @@ describe('StartPreparationUseCase', () => {
       listSpawns: jest.fn().mockReturnValue([]),
       listRunningIssueUrls: jest.fn().mockReturnValue([]),
     };
+    mockGitHubGraphqlRateLimitRepository = {
+      getRemainingRequestCount: jest.fn().mockResolvedValue(null),
+    };
     useCase = new StartPreparationUseCase(
       mockProjectRepository,
       mockIssueRepository,
       mockLocalCommandRunner,
       mockClaudeTokenUsageRepository,
       mockTakeOwnershipSpawnRepository,
+      mockGitHubGraphqlRateLimitRepository,
     );
   });
   it('should run aw command for awaiting workspace issues', async () => {
@@ -627,6 +633,225 @@ describe('StartPreparationUseCase', () => {
     expect(mockLocalCommandRunner.runCommand.mock.calls).toHaveLength(0);
   });
 
+  it('skips all spawning when active worker count meets the maxConcurrentWorkers cap', async () => {
+    const awaitingIssues: Issue[] = [
+      createMockIssue({
+        url: 'https://github.com/user/repo/issues/10',
+        status: 'Awaiting Workspace',
+        author: 'testuser',
+      }),
+      createMockIssue({
+        number: 2,
+        url: 'https://github.com/user/repo/issues/11',
+        status: 'Awaiting Workspace',
+        author: 'testuser',
+      }),
+    ];
+    mockProjectRepository.getByUrl.mockResolvedValue(mockProject);
+    mockIssueRepository.getStoryObjectMap.mockResolvedValue(
+      createMockStoryObjectMap(awaitingIssues),
+    );
+    mockTakeOwnershipSpawnRepository.listRunningIssueUrls.mockReturnValue([
+      'https://github.com/user/repo/issues/1',
+      'https://github.com/user/repo/issues/2',
+    ]);
+
+    await useCase.run({
+      projectUrl: 'https://github.com/user/repo',
+      defaultAgentName: 'agent1',
+      defaultLlmModelName: 'claude-opus',
+      fallbackLlmModelName: null,
+      defaultLlmAgentName: null,
+      configFilePath: '/path/to/config.yml',
+      maximumPreparingIssuesCount: null,
+      utilizationPercentageThreshold: 90,
+      allowedIssueAuthors: ['testuser'],
+      manager: 'manager-user',
+      codexHomeCandidates: null,
+      labelsAsLlmAgentName: null,
+      maxConcurrentWorkers: 2,
+    });
+
+    expect(mockIssueRepository.updateStatus).not.toHaveBeenCalled();
+    expect(
+      mockLocalCommandRunner.runCommand.mock.calls.map((c) => c[0]),
+    ).not.toContain('aw');
+  });
+
+  it('stops spawning mid-loop when workers started in the run bring the count to the cap', async () => {
+    const awaitingIssues: Issue[] = [
+      createMockIssue({
+        url: 'https://github.com/user/repo/issues/10',
+        status: 'Awaiting Workspace',
+        author: 'testuser',
+      }),
+      createMockIssue({
+        number: 2,
+        url: 'https://github.com/user/repo/issues/11',
+        status: 'Awaiting Workspace',
+        author: 'testuser',
+      }),
+    ];
+    mockProjectRepository.getByUrl.mockResolvedValue(mockProject);
+    mockIssueRepository.getStoryObjectMap.mockResolvedValue(
+      createMockStoryObjectMap(awaitingIssues),
+    );
+    mockIssueRepository.getAllOpened.mockResolvedValue([]);
+    mockTakeOwnershipSpawnRepository.listRunningIssueUrls.mockReturnValue([]);
+    mockLocalCommandRunner.runCommand.mockResolvedValue({
+      stdout: '',
+      stderr: '',
+      exitCode: 0,
+    });
+
+    await useCase.run({
+      projectUrl: 'https://github.com/user/repo',
+      defaultAgentName: 'agent1',
+      defaultLlmModelName: 'claude-opus',
+      fallbackLlmModelName: null,
+      defaultLlmAgentName: null,
+      configFilePath: '/path/to/config.yml',
+      maximumPreparingIssuesCount: null,
+      utilizationPercentageThreshold: 90,
+      allowedIssueAuthors: ['testuser'],
+      manager: 'manager-user',
+      codexHomeCandidates: null,
+      labelsAsLlmAgentName: null,
+      maxConcurrentWorkers: 1,
+    });
+
+    const awCalls = mockLocalCommandRunner.runCommand.mock.calls.filter(
+      (call) => call[0] === 'aw',
+    );
+    expect(awCalls).toHaveLength(1);
+  });
+
+  it('skips the preparation cycle when GraphQL rate limit is below the floor', async () => {
+    const awaitingIssues: Issue[] = [
+      createMockIssue({
+        url: 'https://github.com/user/repo/issues/10',
+        status: 'Awaiting Workspace',
+        author: 'testuser',
+      }),
+    ];
+    mockProjectRepository.getByUrl.mockResolvedValue(mockProject);
+    mockIssueRepository.getStoryObjectMap.mockResolvedValue(
+      createMockStoryObjectMap(awaitingIssues),
+    );
+    mockGitHubGraphqlRateLimitRepository.getRemainingRequestCount.mockResolvedValue(
+      499,
+    );
+
+    await useCase.run({
+      projectUrl: 'https://github.com/user/repo',
+      defaultAgentName: 'agent1',
+      defaultLlmModelName: 'claude-opus',
+      fallbackLlmModelName: null,
+      defaultLlmAgentName: null,
+      configFilePath: '/path/to/config.yml',
+      maximumPreparingIssuesCount: null,
+      utilizationPercentageThreshold: 90,
+      allowedIssueAuthors: ['testuser'],
+      manager: 'manager-user',
+      codexHomeCandidates: null,
+      labelsAsLlmAgentName: null,
+      graphqlRateLimitFloor: 500,
+    });
+
+    expect(mockIssueRepository.updateStatus).not.toHaveBeenCalled();
+    expect(
+      mockLocalCommandRunner.runCommand.mock.calls.map((c) => c[0]),
+    ).not.toContain('aw');
+  });
+
+  it('proceeds with spawning when GraphQL remaining equals the floor exactly', async () => {
+    const awaitingIssues: Issue[] = [
+      createMockIssue({
+        url: 'https://github.com/user/repo/issues/10',
+        status: 'Awaiting Workspace',
+        author: 'testuser',
+      }),
+    ];
+    mockProjectRepository.getByUrl.mockResolvedValue(mockProject);
+    mockIssueRepository.getStoryObjectMap.mockResolvedValue(
+      createMockStoryObjectMap(awaitingIssues),
+    );
+    mockIssueRepository.getAllOpened.mockResolvedValue([]);
+    mockGitHubGraphqlRateLimitRepository.getRemainingRequestCount.mockResolvedValue(
+      500,
+    );
+    mockLocalCommandRunner.runCommand.mockResolvedValue({
+      stdout: '',
+      stderr: '',
+      exitCode: 0,
+    });
+
+    await useCase.run({
+      projectUrl: 'https://github.com/user/repo',
+      defaultAgentName: 'agent1',
+      defaultLlmModelName: 'claude-opus',
+      fallbackLlmModelName: null,
+      defaultLlmAgentName: null,
+      configFilePath: '/path/to/config.yml',
+      maximumPreparingIssuesCount: null,
+      utilizationPercentageThreshold: 90,
+      allowedIssueAuthors: ['testuser'],
+      manager: 'manager-user',
+      codexHomeCandidates: null,
+      labelsAsLlmAgentName: null,
+      graphqlRateLimitFloor: 500,
+    });
+
+    const awCalls = mockLocalCommandRunner.runCommand.mock.calls.filter(
+      (call) => call[0] === 'aw',
+    );
+    expect(awCalls).toHaveLength(1);
+  });
+
+  it('proceeds with spawning when GraphQL rate limit check returns null', async () => {
+    const awaitingIssues: Issue[] = [
+      createMockIssue({
+        url: 'https://github.com/user/repo/issues/10',
+        status: 'Awaiting Workspace',
+        author: 'testuser',
+      }),
+    ];
+    mockProjectRepository.getByUrl.mockResolvedValue(mockProject);
+    mockIssueRepository.getStoryObjectMap.mockResolvedValue(
+      createMockStoryObjectMap(awaitingIssues),
+    );
+    mockIssueRepository.getAllOpened.mockResolvedValue([]);
+    mockGitHubGraphqlRateLimitRepository.getRemainingRequestCount.mockResolvedValue(
+      null,
+    );
+    mockLocalCommandRunner.runCommand.mockResolvedValue({
+      stdout: '',
+      stderr: '',
+      exitCode: 0,
+    });
+
+    await useCase.run({
+      projectUrl: 'https://github.com/user/repo',
+      defaultAgentName: 'agent1',
+      defaultLlmModelName: 'claude-opus',
+      fallbackLlmModelName: null,
+      defaultLlmAgentName: null,
+      configFilePath: '/path/to/config.yml',
+      maximumPreparingIssuesCount: null,
+      utilizationPercentageThreshold: 90,
+      allowedIssueAuthors: ['testuser'],
+      manager: 'manager-user',
+      codexHomeCandidates: null,
+      labelsAsLlmAgentName: null,
+      graphqlRateLimitFloor: 500,
+    });
+
+    const awCalls = mockLocalCommandRunner.runCommand.mock.calls.filter(
+      (call) => call[0] === 'aw',
+    );
+    expect(awCalls).toHaveLength(1);
+  });
+
   it('should pass --branch to aw command when issue has an existing linked PR', async () => {
     const awaitingIssues: Issue[] = [
       createMockIssue({
@@ -7055,6 +7280,7 @@ describe('StartPreparationUseCase.buildRotationOrder', () => {
       listSpawns: jest.fn().mockReturnValue([]),
       listRunningIssueUrls: jest.fn().mockReturnValue([]),
     },
+    { getRemainingRequestCount: jest.fn().mockResolvedValue(null) },
   );
 
   it('lists selected tokens first in ascending 7-day reset deadline order then excluded tokens', () => {
@@ -7354,6 +7580,7 @@ describe('StartPreparationUseCase.getTokenConcurrentLimit', () => {
         listSpawns: jest.fn().mockReturnValue([]),
         listRunningIssueUrls: jest.fn().mockReturnValue([]),
       },
+      { getRemainingRequestCount: jest.fn().mockResolvedValue(null) },
     );
   });
 
@@ -7465,6 +7692,7 @@ describe('StartPreparationUseCase.run normalConcurrentLimit', () => {
       mockLocalCommandRunner,
       mockClaudeTokenUsageRepository,
       mockTakeOwnershipSpawnRepository,
+      { getRemainingRequestCount: jest.fn().mockResolvedValue(null) },
     );
 
     await useCase.run({
@@ -7542,6 +7770,7 @@ describe('StartPreparationUseCase.fetchSpawnCandidateBranchSources', () => {
         listSpawns: jest.fn().mockReturnValue([]),
         listRunningIssueUrls: jest.fn().mockReturnValue([]),
       },
+      { getRemainingRequestCount: jest.fn().mockResolvedValue(null) },
     );
 
   it('looks up related open pull requests for issue urls concurrently up to the configured limit', async () => {

package/src/domain/usecases/StartPreparationUseCase.ts

@@ -7,6 +7,7 @@ import { ProjectRepository } from './adapter-interfaces/ProjectRepository';
 import { LocalCommandRunner } from './adapter-interfaces/LocalCommandRunner';
 import { ClaudeTokenUsageRepository } from './adapter-interfaces/ClaudeTokenUsageRepository';
 import { TakeOwnershipSpawnRepository } from './adapter-interfaces/TakeOwnershipSpawnRepository';
+import { GitHubGraphqlRateLimitRepository } from './adapter-interfaces/GitHubGraphqlRateLimitRepository';
 import { ClaudeTokenUsage } from '../entities/ClaudeTokenUsage';
 import { DEFAULT_SELECTION_WEIGHT } from './OauthTokenSelectUseCase';
 import {
@@ -74,6 +75,7 @@ export class StartPreparationUseCase {
     private readonly localCommandRunner: LocalCommandRunner,
     private readonly claudeTokenUsageRepository: ClaudeTokenUsageRepository,
     private readonly takeOwnershipSpawnRepository: TakeOwnershipSpawnRepository,
+    private readonly gitHubGraphqlRateLimitRepository: GitHubGraphqlRateLimitRepository,
   ) {}
 
   private weeklyLimitTypeForModel = (modelName: string | null): string => {
@@ -421,6 +423,8 @@ export class StartPreparationUseCase {
     labelsAsLlmAgentName: string[] | null;
     agents?: string[] | null;
     normalConcurrentLimit?: number;
+    maxConcurrentWorkers?: number | null;
+    graphqlRateLimitFloor?: number | null;
   }): Promise<{ rotationOrder: RotationOrderEntry[] | null }> => {
     const normalConcurrentLimit =
       params.normalConcurrentLimit ?? NORMAL_CONCURRENT_LIMIT;
@@ -537,6 +541,28 @@ export class StartPreparationUseCase {
 
     const now = new Date();
 
+    const maxConcurrentWorkers = params.maxConcurrentWorkers ?? null;
+    const graphqlRateLimitFloor = params.graphqlRateLimitFloor ?? null;
+
+    if (graphqlRateLimitFloor !== null) {
+      const graphqlRemaining =
+        await this.gitHubGraphqlRateLimitRepository.getRemainingRequestCount();
+      if (
+        graphqlRemaining !== null &&
+        graphqlRemaining < graphqlRateLimitFloor
+      ) {
+        console.warn(
+          `GraphQL rate limit low (${graphqlRemaining} remaining, floor: ${graphqlRateLimitFloor}); skipping preparation cycle.`,
+        );
+        return { rotationOrder };
+      }
+      if (graphqlRemaining === null) {
+        console.warn(
+          'GraphQL rate limit check failed; proceeding with spawning.',
+        );
+      }
+    }
+
     const branchSourceByIssueUrl = await this.fetchSpawnCandidateBranchSources(
       awaitingWorkspaceIssues
         .filter(
@@ -567,6 +593,15 @@ export class StartPreparationUseCase {
         console.warn(`Skipping ${issue.url}: worker already running.`);
         continue;
       }
+      if (maxConcurrentWorkers !== null) {
+        const activeWorkerCount = runningIssueUrls.size + startedInThisRunCount;
+        if (activeWorkerCount >= maxConcurrentWorkers) {
+          console.warn(
+            `Spawn cap reached (${activeWorkerCount}/${maxConcurrentWorkers} active workers); skipping remaining candidates.`,
+          );
+          break;
+        }
+      }
       const exclusionReason = this.spawnCandidateExclusionReasonOf(
         issue,
         params.allowedIssueAuthors,

package/src/domain/usecases/adapter-interfaces/GitHubGraphqlRateLimitRepository.ts

@@ -0,0 +1,3 @@
+export interface GitHubGraphqlRateLimitRepository {
+  getRemainingRequestCount(): Promise<number | null>;
+}