feat: add manual agent triggering and run retry

[zbigniewsobiecki]

Summary

Adds the ability to manually trigger agent runs and retry failed runs via CLI (web UI in future PR).

• New tRPC mutations: runs.trigger and runs.retry with org access validation
• CLI commands: cascade runs trigger and cascade runs retry
• Core runner: manual-runner.ts following the debug-runner.ts pattern (fire-and-forget, duplicate prevention)
• Type update: Added 'manual' to triggerType union

Implementation Details

manual-runner.ts

• triggerManualRun() — accepts project/agent/card params, builds AgentInput, calls runAgent fire-and-forget
• triggerRetryRun() — reads original run from DB, extracts params, delegates to triggerManualRun
• In-memory tracking prevents duplicate concurrent triggers for same project+agent+card+PR combo

tRPC Mutations

• runs.trigger — validates org ownership, loads project config, fires trigger
• runs.retry — verifies run exists + org access, loads config, fires retry
• Both use fire-and-forget pattern (matches debug analysis)

CLI Commands

• cascade runs trigger --project ID --agent-type TYPE [--card-id ID] [--model MODEL]
• cascade runs retry RUN_ID [--model MODEL]

Test Coverage

• 9 unit tests covering trigger/retry flows, duplicate prevention, error handling
• All existing tests pass (1310 tests)
• Type checking: ✓
• Linting: ✓

Related

Trello card: https://trello.com/c/6993656f949847855086dc50

Implements steps 1-5 and 8-9 from the card (CLI layer). Web UI (steps 6-7) deferred to future PR.

🤖 Generated with Claude Code

[aaight]

🔍 Reviewing PR...

[aaight]

Summary

Clean implementation that follows existing patterns well. No blocking issues. Two minor items worth considering.

Code Issues

Should Fix

• src/api/routers/runs.ts:181 — agentType: z.string() has no .min(1) constraint. Other routers in this codebase (agentConfigs.ts:57, prompts.ts:30) consistently use z.string().min(1) for agentType. An empty string would pass validation and silently fail in the fire-and-forget runAgent call, making it hard to debug.

Minor

• src/api/routers/runs.ts + src/triggers/shared/manual-runner.ts — The retry mutation fetches the run via getRunById for auth validation (line 248), then triggerRetryRun fetches the same run again from DB (manual-runner.ts line 128). The existing triggerDebugAnalysis pattern avoids this by extracting run data at the router level and passing it down. Not a bug, but an unnecessary extra DB call per retry. Consider passing the already-fetched run data to triggerRetryRun instead.

[aaight]

Minor: agentType: z.string() — other routers use z.string().min(1) for agent type validation. Without it, an empty string silently fails in the fire-and-forget path.

[aaight]

This getRunById call duplicates the fetch already done in the retry tRPC mutation. Consider accepting the run data as a parameter (similar to how triggerDebugAnalysis receives its inputs from the router) to avoid the extra DB round-trip.

[zbigniewsobiecki]

👀 Checking this out...

[zbigniewsobiecki]

🔍 Reviewing PR...

[zbigniewsobiecki]

Code Review Summary

I've reviewed the manual agent triggering and run retry implementation. The code is well-structured and follows the existing patterns (particularly debug-runner.ts). Here are my findings:

✅ Strengths

1. Excellent test coverage - 9 comprehensive unit tests covering duplicate prevention, parameter extraction, error handling, and fire-and-forget behavior
2. Follows established patterns - Mirrors debug-runner.ts design with in-memory tracking and fire-and-forget execution
3. Clean separation of concerns - tRPC mutations handle auth/validation, runner handles business logic
4. Type safety - Proper TypeScript types and Zod validation
5. Good error handling - Catches and logs errors in fire-and-forget promises

💡 Observations & Questions

1. Fire-and-forget Return Timing

The triggerManualRun and triggerRetryRun functions return immediately (fire-and-forget), but the tRPC mutations call them with await:

// In runs.ts line 215+
await triggerManualRun(...).catch((err) => { ... });

This seems inconsistent. If these are truly fire-and-forget, should we remove the await? Or is the await intentional to catch the duplicate detection error before returning { triggered: true } to the client?

Recommendation: Consider clarifying the intent - either:

• Remove await if truly fire-and-forget (like triggerDebugAnalysis on line 166)
• Keep await but document that we want to catch duplicate errors synchronously

2. Duplicate Prevention Scope

The duplicate prevention only checks project+agent+card+pr. This means:

• ✅ Can't trigger the same card twice concurrently
• ❓ Can trigger with different modelOverride values while another is running

Is this intentional? Should modelOverride be part of the deduplication key?

3. Missing PR Context on Retry

From manual-runner.ts:156:

// For PR-based agents, we don't store branch/SHA in DB, so we can't restore them.
// The retry will fetch fresh data from GitHub if needed.

This is a known limitation and well-documented. However, retrying a PR-based agent might fail if:

• The original PR branch was deleted
• The PR was closed/merged

Question: Should we validate that PR-based runs have an accessible PR before allowing retry? Or is failing gracefully acceptable?

4. Schema Migration Not Included

The PR adds 'manual' to the triggerType union in src/types/index.ts, but I don't see a database migration to add this value to any enum constraint (if one exists).

Question: Does the trigger_type column have an enum constraint in PostgreSQL? If so, we need a migration to add 'manual' to the allowed values.

🔍 Minor Observations

1. CLI UX: The CLI commands use --agent-type (kebab-case) but the API uses agentType (camelCase). This is consistent with the existing codebase pattern, so no change needed - just noting for future consideration.

2. Error messages: Very clear and actionable (e.g., "Manual trigger already running for project=X, agent=Y"). Great UX!

3. Test quality: The tests properly use setImmediate to handle async fire-and-forget behavior. Nice attention to detail!

🎯 Verdict

This is solid work that follows established patterns and includes excellent test coverage. The questions above are mostly about clarifying intent rather than bugs. The implementation is production-ready pending answers to the questions above.

Primary concerns:

• Clarify the await intent in tRPC mutations (observation #1)
• Verify database schema handles 'manual' trigger type (observation #4)

Nice to address (optional):

• Document the duplicate prevention scope (observation #2)
• Consider PR validation on retry (observation #3)