github-issue-tower-defence-management 2.19.1 → 2.19.3

package/src/domain/usecases/StartPreparationUseCase.ts

@@ -1,876 +0,0 @@
-import {
-  IssueRepository,
-  RelatedPullRequest,
-} from './adapter-interfaces/IssueRepository';
-import { Issue } from '../entities/Issue';
-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 {
-  AWAITING_WORKSPACE_STATUS_NAME,
-  PREPARATION_STATUS_NAME,
-} from '../entities/WorkflowStatus';
-import { NO_STORY_STORY_NAME } from '../entities/RequiredProjectField';
-import { adoptIssueAgentDesignationLabel } from './AgentDesignationLabelAdoptUseCase';
-import { issueReactivationTriggerIsPending } from './issueReactivationTriggerIsPending';
-import { ensureAgentOptionAndGetId } from './ensureAgentOptionAndGetId';
-import { isAuthorAuthorizedForAutoStatusCheck } from './isAuthorAuthorizedForAutoStatusCheck';
-
-export const NORMAL_CONCURRENT_LIMIT = 6;
-const SEVEN_DAY_THROTTLE_START_THRESHOLD = 0.8;
-const FIVE_HOUR_THROTTLE_START_THRESHOLD = 0.8;
-export const DEFAULT_FALLBACK_LLM_MODEL_NAME = 'claude-opus-4-8';
-const LLM_AGENT_LABEL_PREFIX = 'llm-agent:';
-export const SPAWN_CANDIDATE_BRANCH_SOURCE_CONCURRENCY = 8;
-
-export type SpawnCandidateExclusionReason =
-  | 'dependedIssueUrls'
-  | 'futureNextActionDate'
-  | 'nextActionHourNotReached'
-  | 'authorNotAllowed'
-  | 'notAssignedToManager';
-
-export type SpawnCandidateBranchSource = {
-  openPullRequest: RelatedPullRequest | null;
-  relatedOpenPullRequests: RelatedPullRequest[];
-};
-
-export const agentNameFromDesignation = (designation: string): string =>
-  designation.startsWith(LLM_AGENT_LABEL_PREFIX)
-    ? designation.slice(LLM_AGENT_LABEL_PREFIX.length).trim()
-    : designation.trim();
-
-export type RotationOrderEntry = {
-  name: string;
-  fiveHourUtilization: number;
-  blocked: boolean;
-  rejected: boolean;
-  thresholdExcluded: boolean;
-  cooldownExcluded: boolean;
-};
-
-export class StartPreparationUseCase {
-  constructor(
-    private readonly projectRepository: Pick<
-      ProjectRepository,
-      'getByUrl' | 'createField' | 'updateAgentList'
-    >,
-    private readonly issueRepository: Pick<
-      IssueRepository,
-      | 'getStoryObjectMap'
-      | 'getAllOpened'
-      | 'updateStatus'
-      | 'findRelatedOpenPRs'
-      | 'getOpenPullRequest'
-      | 'closePullRequest'
-      | 'deletePullRequestBranch'
-      | 'createCommentByUrl'
-      | 'setIssueAgentField'
-      | 'removeLabel'
-    >,
-    private readonly localCommandRunner: LocalCommandRunner,
-    private readonly claudeTokenUsageRepository: ClaudeTokenUsageRepository,
-    private readonly takeOwnershipSpawnRepository: TakeOwnershipSpawnRepository,
-    private readonly gitHubGraphqlRateLimitRepository: GitHubGraphqlRateLimitRepository,
-  ) {}
-
-  private weeklyLimitTypeForModel = (modelName: string | null): string => {
-    const normalized = (modelName ?? '').toLowerCase();
-    if (normalized.includes('sonnet')) return 'seven_day_sonnet';
-    if (normalized.includes('opus')) return 'seven_day_opus';
-    return 'seven_day';
-  };
-
-  private isWithinCooldown = (
-    usage: ClaudeTokenUsage,
-    nowEpochSeconds: number,
-  ): boolean => usage.blockedUntilEpoch > nowEpochSeconds;
-
-  private isModelWeeklyLimitRejected = (
-    usage: ClaudeTokenUsage,
-    weeklyLimitType: string,
-  ): boolean => {
-    const specific = usage.modelWeeklyLimits[weeklyLimitType];
-    if (specific !== undefined && specific.rejected) return true;
-    const general = usage.modelWeeklyLimits['seven_day'];
-    return general !== undefined && general.rejected;
-  };
-
-  private selectModelForToken = (
-    usage: ClaudeTokenUsage,
-    defaultModelName: string | null,
-    fallbackModelName: string | null,
-  ): string | null => {
-    const generalWeeklyLimit = usage.modelWeeklyLimits['seven_day'];
-    if (generalWeeklyLimit !== undefined && generalWeeklyLimit.rejected) {
-      return null;
-    }
-    const candidateModelNames = [defaultModelName, fallbackModelName].filter(
-      (modelName): modelName is string =>
-        modelName !== null && modelName !== '',
-    );
-    for (const candidateModelName of candidateModelNames) {
-      const weeklyLimitType = this.weeklyLimitTypeForModel(candidateModelName);
-      const specificWeeklyLimit = usage.modelWeeklyLimits[weeklyLimitType];
-      if (specificWeeklyLimit === undefined || !specificWeeklyLimit.rejected) {
-        return candidateModelName;
-      }
-    }
-    return null;
-  };
-
-  private secondsUntilSevenDayReset = (
-    usage: ClaudeTokenUsage,
-    weeklyLimitType: string,
-    nowEpochSeconds: number,
-  ): number => {
-    const specific = usage.modelWeeklyLimits[weeklyLimitType];
-    if (specific !== undefined) {
-      return specific.resetsAt - nowEpochSeconds;
-    }
-    const general = usage.modelWeeklyLimits['seven_day'];
-    if (general !== undefined) {
-      return general.resetsAt - nowEpochSeconds;
-    }
-    return Number.POSITIVE_INFINITY;
-  };
-
-  private compareBySevenDayDeadlineThenUtilization = (
-    a: ClaudeTokenUsage,
-    aWeeklyLimitType: string,
-    b: ClaudeTokenUsage,
-    bWeeklyLimitType: string,
-    nowEpochSeconds: number,
-  ): number => {
-    const aSecondsUntilReset = this.secondsUntilSevenDayReset(
-      a,
-      aWeeklyLimitType,
-      nowEpochSeconds,
-    );
-    const bSecondsUntilReset = this.secondsUntilSevenDayReset(
-      b,
-      bWeeklyLimitType,
-      nowEpochSeconds,
-    );
-    if (aSecondsUntilReset !== bSecondsUntilReset) {
-      return aSecondsUntilReset - bSecondsUntilReset;
-    }
-    return a.fiveHourUtilization - b.fiveHourUtilization;
-  };
-
-  private taperedConcurrentLimit = (
-    utilization: number,
-    throttleStartThreshold: number,
-    normalConcurrentLimit: number,
-  ): number => {
-    if (utilization < throttleStartThreshold) {
-      return normalConcurrentLimit;
-    }
-    const remaining = (1 - utilization) / (1 - throttleStartThreshold);
-    return Math.max(1, Math.ceil(normalConcurrentLimit * remaining));
-  };
-
-  getTokenConcurrentLimit = (
-    fiveHourUtilization: number,
-    sevenDayUtilization: number,
-    selectionWeight?: number,
-    normalConcurrentLimit: number = NORMAL_CONCURRENT_LIMIT,
-  ): number => {
-    const sevenDayLimit = this.taperedConcurrentLimit(
-      sevenDayUtilization,
-      SEVEN_DAY_THROTTLE_START_THRESHOLD,
-      normalConcurrentLimit,
-    );
-    const fiveHourLimit = this.taperedConcurrentLimit(
-      fiveHourUtilization,
-      FIVE_HOUR_THROTTLE_START_THRESHOLD,
-      normalConcurrentLimit,
-    );
-    const weight = selectionWeight ?? DEFAULT_SELECTION_WEIGHT;
-    return Math.max(
-      1,
-      Math.floor(Math.min(sevenDayLimit, fiveHourLimit) * weight),
-    );
-  };
-
-  spawnCandidateExclusionReasonOf = (
-    issue: Issue,
-    allowedIssueAuthors: string[] | null,
-    manager: string,
-    now: Date,
-  ): SpawnCandidateExclusionReason | null => {
-    if (issue.dependedIssueUrls.length > 0) {
-      return 'dependedIssueUrls';
-    }
-    if (issueReactivationTriggerIsPending(issue, now)) {
-      const startOfTomorrow = new Date(
-        Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1),
-      );
-      return issue.nextActionDate !== null &&
-        issue.nextActionDate >= startOfTomorrow
-        ? 'futureNextActionDate'
-        : 'nextActionHourNotReached';
-    }
-    if (
-      !isAuthorAuthorizedForAutoStatusCheck(issue.author, allowedIssueAuthors)
-    ) {
-      return 'authorNotAllowed';
-    }
-    if (!issue.assignees.includes(manager)) {
-      return 'notAssignedToManager';
-    }
-    return null;
-  };
-
-  fetchSpawnCandidateBranchSources = async (
-    issueUrls: string[],
-  ): Promise<Map<string, SpawnCandidateBranchSource>> => {
-    const branchSourceByIssueUrl = new Map<
-      string,
-      SpawnCandidateBranchSource
-    >();
-    let nextIndex = 0;
-    const fetchSequentially = async (): Promise<void> => {
-      while (nextIndex < issueUrls.length) {
-        const issueUrl = issueUrls[nextIndex];
-        nextIndex += 1;
-        branchSourceByIssueUrl.set(
-          issueUrl,
-          issueUrl.includes('/pull/')
-            ? {
-                openPullRequest:
-                  await this.issueRepository.getOpenPullRequest(issueUrl),
-                relatedOpenPullRequests: [],
-              }
-            : {
-                openPullRequest: null,
-                relatedOpenPullRequests:
-                  await this.issueRepository.findRelatedOpenPRs(issueUrl),
-              },
-        );
-      }
-    };
-    await Promise.all(
-      Array.from(
-        {
-          length: Math.min(
-            SPAWN_CANDIDATE_BRANCH_SOURCE_CONCURRENCY,
-            issueUrls.length,
-          ),
-        },
-        fetchSequentially,
-      ),
-    );
-    return branchSourceByIssueUrl;
-  };
-
-  private selectRotationTokens = (
-    tokenUsages: ClaudeTokenUsage[],
-    utilizationPercentageThreshold: number,
-    defaultModelName: string | null,
-    fallbackModelName: string | null,
-    maxConcurrent: number,
-    normalConcurrentLimit: number,
-  ): {
-    tokens: string[];
-    effectiveCap: number;
-    tokensWithLimits: Array<{
-      token: string;
-      model: string;
-      limit: number;
-      secondsUntilSevenDayReset: number;
-    }>;
-  } => {
-    const nowEpochSeconds = Date.now() / 1000;
-    const eligibleTokens = tokenUsages
-      .filter((usage) => !usage.blocked)
-      .filter((usage) => !usage.fiveHourRejected)
-      .filter((usage) => !this.isWithinCooldown(usage, nowEpochSeconds))
-      .filter(
-        (usage) =>
-          usage.fiveHourUtilization * 100 < utilizationPercentageThreshold,
-      )
-      .flatMap((usage) => {
-        const model = this.selectModelForToken(
-          usage,
-          defaultModelName,
-          fallbackModelName,
-        );
-        if (model === null) return [];
-        return [{ usage, model }];
-      })
-      .sort((a, b) =>
-        this.compareBySevenDayDeadlineThenUtilization(
-          a.usage,
-          this.weeklyLimitTypeForModel(a.model),
-          b.usage,
-          this.weeklyLimitTypeForModel(b.model),
-          nowEpochSeconds,
-        ),
-      );
-
-    if (eligibleTokens.length === 0) {
-      return { tokens: [], effectiveCap: 0, tokensWithLimits: [] };
-    }
-
-    const tokensWithLimits = eligibleTokens.map(({ usage, model }) => ({
-      token: usage.token,
-      model,
-      limit: this.getTokenConcurrentLimit(
-        usage.fiveHourUtilization,
-        usage.sevenDayUtilization,
-        usage.selectionWeight,
-        normalConcurrentLimit,
-      ),
-      secondsUntilSevenDayReset: this.secondsUntilSevenDayReset(
-        usage,
-        this.weeklyLimitTypeForModel(model),
-        nowEpochSeconds,
-      ),
-    }));
-
-    const totalCapacity = tokensWithLimits.reduce((sum, t) => sum + t.limit, 0);
-    const effectiveCap = Math.min(maxConcurrent, totalCapacity);
-
-    const maxLimit = Math.max(...tokensWithLimits.map((t) => t.limit));
-    const rotationList: string[] = [];
-    for (let round = 0; round < maxLimit; round++) {
-      for (const t of tokensWithLimits) {
-        if (t.limit > round) {
-          rotationList.push(t.token);
-        }
-      }
-    }
-
-    return { tokens: rotationList, effectiveCap, tokensWithLimits };
-  };
-
-  buildRotationOrder = (
-    tokenUsages: ClaudeTokenUsage[],
-    utilizationPercentageThreshold: number,
-    modelName: string | null,
-  ): RotationOrderEntry[] => {
-    const weeklyLimitType = this.weeklyLimitTypeForModel(modelName);
-    const nowEpochSeconds = Date.now() / 1000;
-    const selectedTokens = tokenUsages
-      .filter((usage) => !usage.blocked)
-      .filter((usage) => !usage.fiveHourRejected)
-      .filter((usage) => !this.isWithinCooldown(usage, nowEpochSeconds))
-      .filter(
-        (usage) => !this.isModelWeeklyLimitRejected(usage, weeklyLimitType),
-      )
-      .filter(
-        (usage) =>
-          usage.fiveHourUtilization * 100 < utilizationPercentageThreshold,
-      )
-      .sort((a, b) =>
-        this.compareBySevenDayDeadlineThenUtilization(
-          a,
-          weeklyLimitType,
-          b,
-          weeklyLimitType,
-          nowEpochSeconds,
-        ),
-      );
-    const selectedTokenValues = new Set(selectedTokens.map((u) => u.token));
-    const excluded: RotationOrderEntry[] = tokenUsages
-      .filter((usage) => !selectedTokenValues.has(usage.token))
-      .map((usage) => ({
-        name: usage.name ?? '',
-        fiveHourUtilization: usage.fiveHourUtilization,
-        blocked: usage.blocked,
-        rejected: usage.fiveHourRejected,
-        thresholdExcluded:
-          !usage.blocked &&
-          !usage.fiveHourRejected &&
-          !this.isWithinCooldown(usage, nowEpochSeconds) &&
-          !this.isModelWeeklyLimitRejected(usage, weeklyLimitType) &&
-          usage.fiveHourUtilization * 100 >= utilizationPercentageThreshold,
-        cooldownExcluded:
-          !usage.blocked &&
-          !usage.fiveHourRejected &&
-          this.isWithinCooldown(usage, nowEpochSeconds),
-      }));
-    const selectedEntries: RotationOrderEntry[] = selectedTokens.map(
-      (usage) => ({
-        name: usage.name ?? '',
-        fiveHourUtilization: usage.fiveHourUtilization,
-        blocked: false,
-        rejected: false,
-        thresholdExcluded: false,
-        cooldownExcluded: false,
-      }),
-    );
-    return [...selectedEntries, ...excluded];
-  };
-
-  run = async (params: {
-    projectUrl: string;
-    defaultAgentName: string;
-    defaultLlmModelName: string | null;
-    fallbackLlmModelName: string | null;
-    defaultLlmAgentName: string | null;
-    configFilePath: string;
-    maximumPreparingIssuesCount: number | null;
-    utilizationPercentageThreshold: number;
-    allowedIssueAuthors: string[] | null;
-    manager: string;
-    codexHomeCandidates: string[] | null;
-    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;
-    const tokenUsages =
-      await this.claudeTokenUsageRepository.getAvailableTokenUsages();
-    let rotationTokens: string[] | null = null;
-    let proxyBaseUrl: string | null = null;
-    let selectedTokensWithLimits: Array<{
-      token: string;
-      model: string;
-      limit: number;
-      secondsUntilSevenDayReset: number;
-    }> = [];
-    let tokenInFlightCounts: Record<string, number> = {};
-    const rotationOrder: RotationOrderEntry[] | null =
-      tokenUsages.length > 0
-        ? this.buildRotationOrder(
-            tokenUsages,
-            params.utilizationPercentageThreshold,
-            params.defaultLlmModelName,
-          )
-        : null;
-    const maximumPreparingIssuesCount =
-      params.maximumPreparingIssuesCount ?? NORMAL_CONCURRENT_LIMIT;
-    let effectiveMaxPreparingIssuesCount = maximumPreparingIssuesCount;
-    const fallbackLlmModelName =
-      params.fallbackLlmModelName ?? DEFAULT_FALLBACK_LLM_MODEL_NAME;
-    if (tokenUsages.length > 0) {
-      const {
-        tokens: selectedTokens,
-        effectiveCap: selectedCap,
-        tokensWithLimits: selectedTokensWithLimitsLocal,
-      } = this.selectRotationTokens(
-        tokenUsages,
-        params.utilizationPercentageThreshold,
-        params.defaultLlmModelName,
-        fallbackLlmModelName,
-        maximumPreparingIssuesCount,
-        normalConcurrentLimit,
-      );
-      if (selectedTokens.length === 0) {
-        console.warn(
-          `All ${tokenUsages.length} configured Claude OAuth token(s) are unavailable (blocked, 5h-window rejected, within cooldown, weekly limits for every candidate model exhausted, or 5h utilization >= ${params.utilizationPercentageThreshold}%). Skipping starting preparation.`,
-        );
-        return { rotationOrder };
-      }
-      await this.claudeTokenUsageRepository.ensureObservable();
-      tokenInFlightCounts =
-        await this.claudeTokenUsageRepository.getTokenInFlightCounts();
-      rotationTokens = selectedTokens;
-      selectedTokensWithLimits = selectedTokensWithLimitsLocal;
-      effectiveMaxPreparingIssuesCount = selectedCap;
-      proxyBaseUrl = this.claudeTokenUsageRepository.proxyBaseUrl();
-    }
-
-    const project = await this.projectRepository.getByUrl(params.projectUrl);
-    const storyObjectMap =
-      await this.issueRepository.getStoryObjectMap(project);
-
-    const allOpenedIssues = Array.from(storyObjectMap.values()).flatMap(
-      (storyObject) => storyObject.issues,
-    );
-    const preparationStatusOption = project.status.statuses.find(
-      (s) => s.name === PREPARATION_STATUS_NAME,
-    );
-    if (!preparationStatusOption) {
-      console.error(
-        `Preparation status option '${PREPARATION_STATUS_NAME}' not found in project.`,
-      );
-      return { rotationOrder };
-    }
-    const awaitingWorkspaceStatusOption = project.status.statuses.find(
-      (s) => s.name === AWAITING_WORKSPACE_STATUS_NAME,
-    );
-
-    const runningIssueUrls = new Set(
-      this.takeOwnershipSpawnRepository.listRunningIssueUrls(),
-    );
-    const awaitingWorkspaceIssues = allOpenedIssues
-      .filter(
-        (issue) =>
-          issue.status === AWAITING_WORKSPACE_STATUS_NAME && !issue.isClosed,
-      )
-      .map((issue) => ({ ...issue }));
-    const allProjectOpenIssues =
-      await this.issueRepository.getAllOpened(project);
-    const storyUnsetAwaitingWorkspaceIssueUrls = allProjectOpenIssues
-      .filter(
-        (issue) =>
-          issue.status === AWAITING_WORKSPACE_STATUS_NAME &&
-          !issue.isClosed &&
-          issue.story === null,
-      )
-      .map((issue) => issue.url);
-    if (storyUnsetAwaitingWorkspaceIssueUrls.length > 0) {
-      console.warn(
-        `Awaiting Workspace issue(s) invisible to spawn candidate selection because Story is unset: ${storyUnsetAwaitingWorkspaceIssueUrls.join(', ')}`,
-      );
-    }
-    const currentPreparationIssueCount = allOpenedIssues.filter(
-      (issue) => issue.status === PREPARATION_STATUS_NAME,
-    ).length;
-    let updatedCurrentPreparationIssueCount = currentPreparationIssueCount;
-    let startedInThisRunCount = 0;
-    const spawnedInThisRunByToken: Record<string, number> = {};
-    let tokenInFlightCountsRefreshed = false;
-    const exclusionCounts = {
-      dependedIssueUrls: 0,
-      futureNextActionDate: 0,
-      nextActionHourNotReached: 0,
-      authorNotAllowed: 0,
-      notAssignedToManager: 0,
-    };
-
-    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(
-          (issue) =>
-            !runningIssueUrls.has(issue.url) &&
-            this.spawnCandidateExclusionReasonOf(
-              issue,
-              params.allowedIssueAuthors,
-              params.manager,
-              now,
-            ) === null,
-        )
-        .map((issue) => issue.url),
-    );
-
-    for (
-      let i = 0;
-      i < awaitingWorkspaceIssues.length &&
-      updatedCurrentPreparationIssueCount < effectiveMaxPreparingIssuesCount;
-      i++
-    ) {
-      const issue = awaitingWorkspaceIssues[i];
-      if (issue.dependedIssueUrls.length > 0) {
-        exclusionCounts.dependedIssueUrls++;
-        continue;
-      }
-      if (runningIssueUrls.has(issue.url)) {
-        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,
-        params.manager,
-        now,
-      );
-      if (exclusionReason !== null) {
-        exclusionCounts[exclusionReason]++;
-        continue;
-      }
-      const branchSource = branchSourceByIssueUrl.get(issue.url);
-      if (branchSource === undefined) {
-        console.error(
-          `Skipping ${issue.url}: no branch source was prefetched for this spawn candidate.`,
-        );
-        continue;
-      }
-      await adoptIssueAgentDesignationLabel(
-        issue,
-        project,
-        params.agents ?? [],
-        this.projectRepository,
-        this.issueRepository,
-      );
-      const isNoStory =
-        issue.story === null || issue.story.startsWith(NO_STORY_STORY_NAME);
-      const agent =
-        (isNoStory || issue.agent === null
-          ? null
-          : agentNameFromDesignation(issue.agent)) || params.defaultAgentName;
-      if (issue.agent === null) {
-        const agentOptionId = await ensureAgentOptionAndGetId(
-          this.projectRepository,
-          project,
-          agent,
-        );
-        if (agentOptionId !== null) {
-          try {
-            await this.issueRepository.setIssueAgentField(
-              issue.url,
-              project,
-              agentOptionId,
-            );
-            issue.agent = agent;
-          } catch (err) {
-            console.error(
-              `Failed to write Agent field for ${issue.url}: ${err instanceof Error ? err.message : String(err)}`,
-            );
-            continue;
-          }
-        } else {
-          console.warn(
-            `Agent field option '${agent}' could not be set for ${issue.url}. Proceeding without recording the agent in the Agent field.`,
-          );
-        }
-      }
-      const labelModelName = issue.labels
-        .find((label: string) => label.startsWith('llm-model:'))
-        ?.replace('llm-model:', '')
-        .trim();
-      if (
-        !labelModelName &&
-        !params.defaultLlmModelName &&
-        rotationTokens === null
-      ) {
-        console.error(
-          `No LLM model configured for issue ${issue.url}. Provide --defaultLlmModelName or add an llm-model: label.`,
-        );
-        continue;
-      }
-      const isPrUrl = issue.url.includes('/pull/');
-      let branchName: string;
-      if (isPrUrl) {
-        const pr = branchSource.openPullRequest;
-        if (pr === null) {
-          console.warn(
-            `Skipping non-OPEN PR ${issue.url}: wrapper requires an open PR.`,
-          );
-          continue;
-        }
-        if (pr.branchName === null) {
-          console.warn(`Skipping PR ${issue.url}: head branch is unavailable.`);
-          continue;
-        }
-        branchName = pr.branchName;
-      } else {
-        const relatedPRs = branchSource.relatedOpenPullRequests;
-        const sameRepoRelatedPRs = relatedPRs.filter((pr) => {
-          const match = /^https?:\/\/[^/]+\/([^/]+\/[^/]+)\//.exec(pr.url);
-          return match === null || match[1] === issue.nameWithOwner;
-        });
-        if (sameRepoRelatedPRs.length > 1) {
-          const sortedPRs = [...sameRepoRelatedPRs].sort(
-            (a, b) => a.createdAt.getTime() - b.createdAt.getTime(),
-          );
-          const canonicalPR = sortedPRs[0];
-          const duplicatePRs = sortedPRs.slice(1);
-          for (const duplicatePR of duplicatePRs) {
-            await this.issueRepository.closePullRequest(duplicatePR.url);
-            if (duplicatePR.branchName !== null) {
-              await this.issueRepository.deletePullRequestBranch(
-                duplicatePR.url,
-                duplicatePR.branchName,
-              );
-            }
-            await this.issueRepository.createCommentByUrl(
-              duplicatePR.url,
-              `This PR was automatically closed to resolve multiple-open-PR ambiguity for issue ${issue.url}. The adopted canonical PR is ${canonicalPR.url}.`,
-            );
-          }
-          const removedPrUrls = duplicatePRs.map((pr) => pr.url).join(', ');
-          await this.issueRepository.createCommentByUrl(
-            issue.url,
-            `${duplicatePRs.length} duplicate PR(s) were automatically closed to resolve multiple-open-PR ambiguity.\n\nRemoved PRs: ${removedPrUrls}\nAdopted PR: ${canonicalPR.url}`,
-          );
-          if (canonicalPR.branchName === null) {
-            console.warn(
-              `Skipping issue ${issue.url}: adopted canonical PR has unavailable head branch.`,
-            );
-            continue;
-          }
-          branchName = canonicalPR.branchName;
-        } else if (sameRepoRelatedPRs.length === 1) {
-          if (sameRepoRelatedPRs[0].branchName === null) {
-            console.warn(
-              `Skipping issue ${issue.url}: related open PR has unavailable head branch.`,
-            );
-            continue;
-          }
-          branchName = sameRepoRelatedPRs[0].branchName;
-        } else {
-          branchName = `i${issue.number}`;
-        }
-      }
-
-      if (!/^[\w./-]+$/.test(branchName)) {
-        console.error(
-          `Skipping issue ${issue.url}: branch name contains unexpected characters: ${branchName}`,
-        );
-        continue;
-      }
-
-      await this.issueRepository.updateStatus(
-        project,
-        issue,
-        preparationStatusOption.id,
-      );
-      issue.status = PREPARATION_STATUS_NAME;
-
-      const revertToAwaitingWorkspace = async (
-        reason: string,
-      ): Promise<void> => {
-        console.error(
-          `Reverting ${issue.url} to ${AWAITING_WORKSPACE_STATUS_NAME} because no worker was spawned: ${reason}`,
-        );
-        if (!awaitingWorkspaceStatusOption) {
-          console.error(
-            `Awaiting Workspace status option '${AWAITING_WORKSPACE_STATUS_NAME}' not found in project. ${issue.url} stays in ${PREPARATION_STATUS_NAME} without a worker.`,
-          );
-          return;
-        }
-        await this.issueRepository.updateStatus(
-          project,
-          issue,
-          awaitingWorkspaceStatusOption.id,
-        );
-        issue.status = AWAITING_WORKSPACE_STATUS_NAME;
-      };
-
-      let spawnEnv: Record<string, string> | undefined;
-      let routedModelName: string | null = null;
-      let selectedTokenName: string | null = null;
-      if (rotationTokens !== null && proxyBaseUrl !== null) {
-        const tokenWithSoonestResetAmongAvailableOf = ():
-          { token: string; model: string } | undefined =>
-          selectedTokensWithLimits
-            .map((t) => ({
-              token: t.token,
-              model: t.model,
-              remaining:
-                t.limit -
-                (tokenInFlightCounts[t.token] ?? 0) -
-                (spawnedInThisRunByToken[t.token] ?? 0),
-              secondsUntilSevenDayReset: t.secondsUntilSevenDayReset,
-            }))
-            .filter((t) => t.remaining > 0)
-            .sort((a, b) => {
-              if (a.secondsUntilSevenDayReset !== b.secondsUntilSevenDayReset) {
-                return (
-                  a.secondsUntilSevenDayReset - b.secondsUntilSevenDayReset
-                );
-              }
-              return b.remaining - a.remaining;
-            })[0];
-        let tokenWithSoonestResetAmongAvailable =
-          tokenWithSoonestResetAmongAvailableOf();
-        if (
-          tokenWithSoonestResetAmongAvailable === undefined &&
-          !tokenInFlightCountsRefreshed
-        ) {
-          tokenInFlightCountsRefreshed = true;
-          tokenInFlightCounts =
-            await this.claudeTokenUsageRepository.getTokenInFlightCounts();
-          tokenWithSoonestResetAmongAvailable =
-            tokenWithSoonestResetAmongAvailableOf();
-        }
-        if (tokenWithSoonestResetAmongAvailable === undefined) {
-          await revertToAwaitingWorkspace(
-            'every Claude OAuth token reached its concurrent worker limit',
-          );
-          break;
-        }
-        const selected = tokenWithSoonestResetAmongAvailable.token;
-        routedModelName = tokenWithSoonestResetAmongAvailable.model;
-        selectedTokenName = selected;
-        spawnEnv = {
-          CLAUDE_CODE_OAUTH_TOKEN: selected,
-          ANTHROPIC_BASE_URL: proxyBaseUrl,
-        };
-      }
-      const model =
-        labelModelName || routedModelName || params.defaultLlmModelName;
-      if (!model) {
-        console.error(
-          `No LLM model configured for issue ${issue.url}. Provide --defaultLlmModelName or add an llm-model: label.`,
-        );
-        await revertToAwaitingWorkspace('no LLM model is configured');
-        continue;
-      }
-      const awArgs: string[] = [
-        issue.url,
-        agent,
-        model,
-        '--configFilePath',
-        params.configFilePath,
-        '--branch',
-        branchName,
-      ];
-      if (
-        params.codexHomeCandidates !== null &&
-        params.codexHomeCandidates.length > 0
-      ) {
-        const codexHome =
-          params.codexHomeCandidates[
-            startedInThisRunCount % params.codexHomeCandidates.length
-          ];
-        awArgs.push('--codexHome', codexHome);
-      }
-      const spawnResult = await this.localCommandRunner.runCommand(
-        'aw',
-        awArgs,
-        spawnEnv ? { env: spawnEnv } : undefined,
-      );
-      if (spawnResult.exitCode !== 0) {
-        await revertToAwaitingWorkspace(
-          `aw exited with ${spawnResult.exitCode}. stdout: ${spawnResult.stdout} stderr: ${spawnResult.stderr}`,
-        );
-        continue;
-      }
-      if (selectedTokenName !== null) {
-        spawnedInThisRunByToken[selectedTokenName] =
-          (spawnedInThisRunByToken[selectedTokenName] ?? 0) + 1;
-      }
-      startedInThisRunCount++;
-      updatedCurrentPreparationIssueCount++;
-    }
-    console.log(
-      `Spawn candidate exclusion summary for ${params.projectUrl}: dependedIssueUrls=${exclusionCounts.dependedIssueUrls}, futureNextActionDate=${exclusionCounts.futureNextActionDate}, nextActionHourNotReached=${exclusionCounts.nextActionHourNotReached}, authorNotAllowed=${exclusionCounts.authorNotAllowed}, notAssignedToManager=${exclusionCounts.notAssignedToManager}`,
-    );
-    return { rotationOrder };
-  };
-}