Core flow

End-to-end execution

1. A user comments @porter <agent> on a GitHub issue.
2. GitHub sends an issue_comment.created webhook to Porter.
3. Porter validates signature, actor, repository scope, and command syntax.
4. Porter resolves actor OAuth/session context and loads D1-backed user settings and secrets.
5. Porter enriches the prompt with issue, repository, and optional AGENTS.md context.
6. Porter creates a Fly Machine with the task payload.
7. Worker container clones the repository and checks out a task branch.
8. Selected agent runs in non-interactive mode.
9. Worker pushes changes and opens a pull request when changes are produced.
10. Worker calls Porter completion callback with status and metadata.
11. Porter reconciles callback and watchdog state, then comments on the issue with result details.
12. Machine auto-destroys after process exit.

Why this flow

• Keeps GitHub as the user-facing control surface.
• Runs compute in isolated, short-lived workers.
• Preserves an auditable trail in issues and PRs.

State transitions

Typical status progression:

queued -> running -> success or queued -> running -> failed (with timed_out for stale runs)

Status is persisted so API consumers and UI components can render reliable task progress.

Retry behavior

• Webhook-level failures can be retried by re-posting the command comment.
• Worker runtime failures should include actionable error output in the issue comment.
• Duplicate commands create separate tasks, which can be useful for model comparison.

Operational notes

• One issue can have multiple Porter tasks over time.
• Agent choice is explicit (@porter opencode) or defaults to opencode when omitted.
• Cancellation flows can be bound to issue lifecycle events like close/reopen.