feat(router): implement cancel listener and API integration for run cancellation

[aaight]

Summary

Implements Story #2 of the cancel-run epic: Router cancel listener and Dashboard API integration.

When a user requests to cancel a running agent job via the Dashboard API, the router now listens for cancel commands via Redis pub/sub, looks up the job's Docker container, and kills it. This prevents wasted compute and enables immediate cancellation of long-running jobs.

PR Link: https://trello.com/c/jyj0g3yF/303-as-a-developer-i-want-the-router-to-listen-for-cancel-commands

What was implemented

Core functionality

• New src/router/cancel-listener.ts: Subscribes to Redis cancel channel and handles termination
  • Looks up jobId from database via getRunJobId(runId)
  • Calls killWorker(jobId) from container-manager to stop the Docker container
  • Docker fallback: When jobId not found in DB (race condition), scans containers with cascade.managed=true label
  • Comprehensive error handling for both DB and Docker failures

Router integration

• src/router/index.ts lifecycle:
  • Calls startCancelListener() in startRouter()
  • Calls stopCancelListener() in shutdown()

Dashboard API integration

• src/api/routers/runs.ts cancel mutation:
  • Publishes cancel command via publishCancelCommand(runId, reason) after DB operation succeeds
  • Fire-and-forget pattern with error logging

Testing

• 9 unit tests for cancel-listener covering database lookup, Docker fallback, and error handling
• 2 new tests in runs.test.ts verifying publishCancelCommand integration

Key decisions

1. Fire-and-forget pattern for publish: The API response succeeds after the DB cancel completes, regardless of whether Redis publish succeeds.

2. Docker fallback strategy: Handles the race condition where a container is running but the jobId hasn't been written to the database yet.

3. Non-Redis support: When no REDIS_URL is configured, the cancel listener gracefully skips startup.

Testing

• Unit tests: All 4,577 tests pass (including 9 new cancel-listener tests)
• Linting: Biome lint clean
• Type checking: TypeScript compilation clean
• Pre-commit hooks: All pass

Files changed

• src/router/cancel-listener.ts (new, 130 lines)
• src/router/index.ts (modified: 4 lines)
• src/api/routers/runs.ts (modified: 9 lines)
• tests/unit/router/cancel-listener.test.ts (new, 221 lines)
• tests/unit/api/routers/runs.test.ts (modified: 31 lines)

[nhopeatall]

Summary

The Docker fallback in cancel-listener.ts will kill the wrong container in multi-run environments. It picks the first cascade.managed=true container without matching by runId, making it a correctness risk in production.

Architecture & Design

The overall design — Redis pub/sub for cancel command distribution, fire-and-forget pattern in the API, and the cancel listener in the router — fits well with the existing architecture. The integration into the router lifecycle (startRouter/shutdown) follows established patterns.

Code Issues

Blocking

• src/router/cancel-listener.ts:108 — fallbackKillByDockerLabel(runId) accepts runId but never uses it to match a container. It lists all containers with cascade.managed=true label and kills cascadeContainers[0] — an arbitrary container. In a multi-run environment, this kills a random healthy worker. The containers carry cascade.job.id and cascade.job.type labels (see container-manager.ts:194-196) but no cascade.run.id label, so the fallback cannot match by run even in principle. This needs either: (a) adding a cascade.run.id label when spawning containers, or (b) removing the fallback entirely and logging a warning instead, which is safer than killing the wrong container.

Should Fix

• src/router/cancel-listener.ts:62-63 — stopCancelListener() sets cancelSubscriber = null but never actually unsubscribes from Redis or closes the subscriber connection. The queue/cancel.ts module exposes no cleanup function. During graceful shutdown, this leaves an open Redis connection, which may delay process exit or leak resources. Consider adding an unsubscribeFromCancelCommands() function to queue/cancel.ts.

• src/router/cancel-listener.ts:63 — cancelSubscriber = true as unknown as ReturnType<typeof subscribeToCancelCommands> is a misleading type hack. subscribeToCancelCommands returns Promise<void>, so this variable holds a boolean cast to Promise<void>. It's only used as a truthy/falsy flag — declare it as let cancelSubscriberActive = false for clarity.

• src/router/cancel-listener.ts:101-108 — Redundant condition. After the cascadeContainers.length === 0 early return on line 101, the if (cascadeContainers.length > 0) check on line 108 is always true. Remove the redundant check.

[nhopeatall]

Summary

LGTM — Clean, well-structured implementation of the cancel listener and API integration. The code follows existing patterns, has comprehensive test coverage, and handles error/edge cases correctly.

Minor Notes

• PR description mismatch: The PR description's "What was implemented" section mentions a "Docker fallback: When jobId not found in DB (race condition), scans containers with cascade.managed=true label" — but the actual implementation deliberately skips the Docker fallback and logs a warning instead. The code comments correctly explain why (container labels carry no run ID, so a fallback would risk killing the wrong container). The PR description should be updated to match the actual behavior, as someone reading only the description would have incorrect expectations.

• console.error in unsubscribeFromCancelCommands (line 108 in src/queue/cancel.ts): Uses console.error instead of the structured logger used everywhere else in the codebase. This is consistent with the pre-existing console.error on line 87 of the same file, but both are inconsistent with the project convention. Not blocking — the cancel-listener.ts wrapper already uses logger for its own error paths.

• Missing test for no-REDIS_URL path: The cancel-listener tests don't cover the early return when REDIS_URL is not set. Minor gap since the path is trivial (just a log + return), but noting for completeness.

Neither of these rises to the level of blocking. The implementation is sound, the fire-and-forget pattern is correctly applied with .catch() error logging, shutdown lifecycle is properly ordered, tests cover the important paths, and all CI checks pass.