Migrations: shared queue

[og2701]

Summary

• put background and lazy migration tasks on one shared Trigger.dev queue
• process customers sequentially and yield between customers when another migration is waiting
• remove the dashboard's per-run concurrency control while treating legacy concurrency input as an effective value of 1

Why

Migration concurrency was partitioned by organization or migration, then multiplied again inside each run. Overlapping organization migrations could therefore saturate the primary database. This change uses Trigger.dev's existing queue and checkpoint primitives instead of adding a Redis capacity controller or database schema.

Validation

• cd server && bun test --isolate tests/unit/migrations-v2 — 29 passed
• cd server && bun ts
• cd vite && bun test tests/views/migrations/migration/build-run-migration-request.test.ts — 2 passed
• cd vite && bun ts
• scoped Biome check
• git diff --check
• commit hooks: Knip plus server and Vite typechecks

Remaining live verification

• exercise two competing organization migrations in deployed Trigger staging
• the secret-backed run-handler integration test was updated and typechecked, but was not run locally

---

Summary by cubic

Share migration fleet capacity across runs by moving customer work to a single shared @trigger.dev queue and coordinating background runs in time-sliced chunks. The coordinator submits finite slices, yields quickly, and ignores per-run concurrency.

• New Features

  • Single shared queue migration-customer-work with concurrency 1 for customer slices and lazy tasks; the coordinator runs off-queue.
  • Time-sliced execution: up to 100 customers or ~10s per slice, then yield; each chunk caps at 15m and does not auto-retry; lazy tasks are queued with higher priority.
  • Idempotent chunk continuations using a frozen prepared migration snapshot; cancellation is honored between slices.
  • Cursor-based continuation across chunks with afterInternalId; count queries are skipped during slices to reduce overhead.
  • Trigger options no longer partition by org; region set only in dev.

• Migration

  • Legacy concurrency input is accepted for compatibility but ignored; effective concurrency is 1.
  • Dashboard removes concurrency controls and no longer sends a value; API response returns concurrency: 1.

^{Written for commit 717e33b. Summary will update on new commits.}

Greptile Summary

This PR moves migration work onto shared fleet capacity. The main changes are:

• Improvements: Share one Trigger.dev queue across background and lazy migration tasks.
• Improvements: Process customers sequentially and checkpoint between customers during contention.
• API changes: Treat legacy concurrency input as an effective value of one.
• Improvements: Remove dashboard concurrency controls and add scheduling tests.

Confidence Score: 5/5

This looks safe to merge after confirming the new queue-state call matches the installed Trigger.dev SDK.

• The shared scheduling flow is internally consistent.
• The remaining item is a conditional SDK compatibility check rather than a demonstrated runtime bug.

server/src/trigger/migrations/migrationTaskQueue.ts

Important Files Changed

Filename	Overview
server/src/trigger/migrations/migrationTaskQueue.ts	Adds the shared queue, queue-state inspection, and checkpoint scheduler.
server/src/trigger/migrations/runMigrationTask.ts	Moves background runs to the shared queue and fixes effective customer concurrency at one.
server/src/trigger/migrations/runMigrationCustomerTask.ts	Moves lazy customer work to the shared queue while retaining database item claims.
server/src/internal/migrations/v2/run/orchestrators/iterateScope.ts	Adds sequential, time-sliced customer iteration when a scheduler is present.
server/src/internal/migrations/v2/handlers/handleRunMigration.ts	Keeps legacy concurrency input compatible while reporting and applying concurrency one.
vite/src/views/migrations/migration/live/MigrationLiveView.tsx	Removes concurrency state, validation, and controls from the migration dashboard.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant API as Migration API
    participant Queue as Shared Queue
    participant Run as Background Run
    participant Lazy as Lazy Customer Task
    participant DB as Item Tracking

    API->>Queue: Enqueue migration run
    Queue->>Run: Start run
    loop Customers
        Run->>DB: Claim and process customer
        Run->>Queue: Check queued work after slice
        alt Work is waiting
            Run->>Queue: Checkpoint
            Queue->>Lazy: Process queued customer task
            Lazy->>DB: Claim and migrate customer
            Queue->>Run: Resume run
        else Queue is idle
            Run->>Run: Continue immediately
        end
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant API as Migration API
    participant Queue as Shared Queue
    participant Run as Background Run
    participant Lazy as Lazy Customer Task
    participant DB as Item Tracking

    API->>Queue: Enqueue migration run
    Queue->>Run: Start run
    loop Customers
        Run->>DB: Claim and process customer
        Run->>Queue: Check queued work after slice
        alt Work is waiting
            Run->>Queue: Checkpoint
            Queue->>Lazy: Process queued customer task
            Lazy->>DB: Claim and migrate customer
            Queue->>Run: Resume run
        else Queue is idle
            Run->>Run: Continue immediately
        end
    end

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
server/src/trigger/migrations/migrationTaskQueue.ts:19-24
**Queue State Shape May Break Build**

The new scheduler assumes `queues.retrieve()` accepts this custom-queue selector and returns a `queued` field. If the installed Trigger.dev SDK exposes a different selector or count field, the server typecheck fails and none of the migration tasks can deploy; this call needs to match the SDK version used by the server.

_{Reviews (1): Last reviewed commit: "feat(migrations): share fleet capacity a..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

Context used (4)

• Context used - CLAUDE.md (source)
• Context used - server/CLAUDE.md (source)
• Context used - AGENTS.md (source)
• Context used - When generating the key changes section of the sum... (source)

[cubic-dev-ai]

All reported issues were addressed across 16 files

Confidence score: 5/5

• Safe to merge after the addressed issues were fixed.

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
checkout	Ignored		Jul 22, 2026 11:45am
landing-page	Ignored		Jul 22, 2026 11:45am

[cubic-dev-ai]

All reported issues were addressed across 16 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[capy-ai]

Capy auto-review is paused for this organization because the usage-cycle auto-review limit has been reached. Increase the limit or turn it off in billing settings to resume automatic reviews.