feat(firstmate): pair one Paseo conversation with GitHub review #134

Use one ordinary Paseo mobile conversation to give Firstmate work and steer priorities, with GitHub issues and PRs as the place to review deliverables and give feedback. The Pi session owning a task handles its GitHub conversation directly: it reads feedback, makes revisions, validates changes, and replies in the same thread. Firstmate owns the queue and cross-task coordination, receiving outcomes and escalations through task records. Routine use should require no worker-session management or copying feedback into Paseo. Pi is the proposed primary harness; direct task feedback uses Pi sessions where selected, without changing every project's configured crew harness.

The acceptance criterion is that work continues and finishes without the user remembering which agent owns each task.

Implementation status

The replacement is implemented for review in PR #116, with the old standalone dispatchers removed. The opt-in firstmate-mobile set configures a dedicated Paseo provider, native Firstmate issue intake/ownership, durable GitHub event delivery into the owning Pi inbox, direct threaded replies, and outcome/recovery records. See the setup and migration guide.

The representative runtime regression exercises actual Pi processes and Paseo RPC/session recovery with native Firstmate ownership/inbox scripts, a local git remote, and controlled model/GitHub responses. Native dispatch metadata and the primary lock are seeded; upstream watcher/guard/branch execution is outside that fixture. This issue remains open for live autonomous supervision, the work Bedrock credential path, actual GitHub operation, and phone reconnect/notification evidence. Review approval remains separate from delivery authority.

Proposed design

Center coordination on a durable task. Firstmate owns its lifecycle and assignment; the assigned Pi owner handles implementation and the GitHub review loop. The task owner can be the primary when no separate worker is assigned, subject to Firstmate's existing project-change boundary.

Ownership and routing

flowchart TB
    P["Paseo conversation"] <-->|intake, steering, status| F["Firstmate"]
    F -->|create and triage| I["GitHub issue"]
    F -->|assign and supervise| W["Owning Pi worker"]
    F <-->|maintain ownership| T["Durable task record"]

    W <-->|questions and progress| I
    W <-->|changes and review| R["GitHub PR"]

    I -->|activity| A["GitHub event adapter"]
    R -->|activity| A
    T -->|resolve owner| A

    A -->|assigned feedback| W
    A -->|unassigned work or recovery| F

Firstmate's existing task records are authoritative for the issue-to-task-to-session/branch/worktree binding. GitHub labels may expose progress; worker ownership and leases stay in machine records. Preserve the binding after a PR becomes ready so later feedback returns to its owner.

The event adapter is a deterministic responsibility within the host/extension integration. Reuse Firstmate's existing contribution observation and ownership machinery where compatible. Route new/unassigned tracked work to Firstmate, assigned feedback to the recorded owner, and completion, blockers, changed scope, or cross-task decisions back to Firstmate.

Direct feedback and recovery

sequenceDiagram
    participant G as GitHub
    participant A as Event adapter
    participant F as Firstmate
    participant W as Pi worker

    G->>A: New tracked issue
    A->>F: Unassigned work
    F->>F: Triage and persist task ownership
    F->>W: Dispatch task
    W->>G: Implement, verify, open PR

    G->>A: Comment, review, or check change
    A->>A: Persist pending event and deduplicate

    opt Recorded owner unavailable
        A->>F: Request task recovery
        F->>W: Resume or reassign with saved context
    end

    A->>W: Deliver pending feedback
    W->>G: Read current thread, revision, and checks
    W->>W: Revise and verify
    W->>G: Push revision and answer feedback
    W->>F: Record outcome or escalate blocker

Persist pending events before advancing the observation cursor, and track their acknowledgment separately so a crash between observation and delivery does not lose feedback. Repeated observations and agent-authored acknowledgments must not cause duplicate revisions or reply loops. Firstmate resolves unavailable ownership through the supported worker lifecycle; the adapter delivers to the resulting recorded owner.

Task lifecycle

This state machine describes the normal GitHub PR delivery path. Map these conceptual states onto existing Firstmate task and contribution records. Opening a PR leaves the task under ownership through review and delivery.

stateDiagram-v2
    direction TB

    state "Waiting for input" as Waiting
    state "Under review" as Review
    state "Ready for delivery" as Ready

    [*] --> Queued
    Queued --> Working: Firstmate assigns owner

    Working --> Waiting: Question or blocker
    Waiting --> Working: Answer or resolution

    Working --> Review: PR ready and verification recorded
    Review --> Working: Actionable feedback
    Review --> Ready: Required review and checks satisfied for current revision

    Ready --> Review: Revision changes or approval becomes stale
    Ready --> Working: Check failure requires changes
    Ready --> Delivering: Firstmate authorizes delivery

    Delivering --> Working: Integration requires changes
    Delivering --> Done: Delivery verified
    Done --> [*]

• Ownership survives waiting and restarts. A stopped Pi process is a runtime condition; preserve the assignment while Firstmate resumes the recorded context or explicitly reassigns it. Reconcile surviving workers before replacement.
• GitHub carries meaningful questions, decisions, review responses, and deliverables. Keep event cursors, leases, and heartbeats in machine records.
• Approval satisfies the applicable review requirement. Delivery also requires current revision/check evidence and authority from explicit instructions or the project's delivery policy. Invalidate stale readiness when the revision, checks, or review state changes.

The first slice to prove is one complete loop: GitHub feedback arrives while Paseo is disconnected, the correct Pi owner revises and replies, and Firstmate receives the updated outcome. Include owner recovery in the same representative integration workflow.

Paseo interaction

The same conversation accepts requests such as “fix this issue,” “also investigate this,” “prioritize the second task,” “what needs my attention?” and “merge both when checks pass.”

• Accept new requests and steering while workers continue. The primary must remain responsive between dispatch and completion.
• Resolve project and task context from the conversation and durable records; ask a focused question only when ambiguity affects the action.
• Acknowledge accepted work briefly, then report completed outcomes, meaningful blockers, or decisions. Keep routine supervision out of the main chat.
• Return concise handoffs with the relevant GitHub issue or PR link. A status request shows active work and outstanding decisions, including GitHub review feedback awaiting action.
• Accept steering and delivery instructions through Paseo or the linked GitHub discussion. Apply them to the identified work under the project's existing delivery policy, preserving that authority across reconnects and restarts.

The Firstmate Paseo plugin/dashboard, custom mobile UI, and terminal status bars are outside this feature's scope. Workers remain available for inspection.

GitHub review loop

The normal sequence is: request work in Paseo; Firstmate assigns a task; the owning Pi session opens or updates its issue/PR; the user reviews and comments in GitHub; that same Pi session revises the work and replies directly. Firstmate receives completion, blockage, or decisions spanning tasks. Detailed review feedback goes straight to the task owner.

• Bind each tracked issue/PR to one task and its owning agent session. Issue comments, PR conversation comments, submitted reviews, inline review threads, and check/state changes wake that owner directly, including while Paseo is idle. The primary Pi session can own the GitHub conversation when no separate worker is assigned; Firstmate's existing delegation boundary still governs project changes.
• Feedback from the configured owner becomes task direction without a special command prefix or a duplicate Paseo message. Other reviewers' findings remain review input under the existing project policy. Preserve author, source link, thread, and revision context.
• The owning Pi session handles actionable feedback using authenticated GitHub tools, performs the revision, and posts a concise response with the resulting change, relevant validation, and unresolved questions. Preserve the existing screenshot and review standards. Escalate changed scope, cross-task priority, missing authority, or an unavailable owner to Firstmate.
• Review approval, requested changes, explicit merge instructions, and automatic merge policy retain their distinct meanings. An approval satisfies review requirements; merge authority comes from the project's policy or an explicit instruction. Recheck the current PR revision and checks before delivery.
• Reconcile answers across GitHub and Paseo so resolving a question in either place clears the same pending decision. Keep detailed review discussion in GitHub and use Paseo for concise handoffs and requested status.

Implement event delivery as a Pi extension or reuse an existing compatible integration before creating new infrastructure. Pi's extension API supports external integrations, persisted entries, and messages that trigger a turn. Start with authenticated host-side polling of tracked GitHub objects at a configurable interval; deliver events inside the owning Pi runtime without competing with Paseo for its RPC input. Keep polling and event routing deterministic, waking model execution only for actionable changes.

Persist task-to-session bindings, event identities, and cursors so downtime is caught up and repeated observations do not trigger duplicate revisions or replies. An in-process extension operates while Pi is alive; the host lifecycle must resume the recorded session after exit, or escalate recovery to Firstmate. Reuse supported session and supervision mechanisms. Agent-authored acknowledgments must not create feedback loops. This path requires no public webhook endpoint or separate agent to relay each comment.

Runtime ownership

Start Pi through Paseo's native provider in the selected Firstmate home, with the environment and project trust needed to discover Firstmate's extensions. Share preparation and validation with the existing launcher. The current firstmate start creates or attaches to a terminal session; it is not itself a Pi RPC provider entrypoint.

Paseo owns the primary process; Firstmate owns worker lifecycle. Each task owner handles its GitHub feedback within that lifecycle. Retain the configured tmux or Zellij worker backend independently of the primary harness. Worker execution and GitHub feedback handling must continue when the phone disconnects, without needing to interact with the host's desktop UI.

Prove the tracked Firstmate extensions actually load and supervise workers under Paseo's Pi RPC mode. File-existence checks and terminal-launch success are insufficient. Record any upstream gap explicitly before adopting this as the default work interaction.

Durable work and recovery

Reuse Firstmate's existing on-disk records. Each task needs an identity, project and requested outcome, worker/worktree association, status, outstanding decision, delivery authority, linked GitHub objects, and feedback-processing position. Keep project detail in task records so one conversation can manage several projects without depending on its entire chat history. GitHub remains the shared record of review discussion; local task state reconciles against it rather than creating a second review backlog.

Persist the primary session identity and reuse/resume it through supported Paseo APIs. Repeated starts and reconnects must find the existing supervisor. After a primary restart, reconcile running workers, task-to-session bindings, and unfinished records before dispatching replacements; never create concurrent primaries for the same home or duplicate already accepted work. A routine primary restart must preserve the existing task owner and its GitHub conversation.

Decisions remain visible until answered. Surface review questions in the relevant GitHub issue/PR and derive Firstmate's outstanding-decision summary from the same records. Use existing GitHub and supported Paseo notifications as appropriate; missed notifications must not lose a decision or require repeated feedback.

Dotfiles integration

• Build on the existing Firstmate launcher, primary selection, and Paseo lifecycle helper. Keep installation/configuration separate from explicitly starting a long-running supervisor.
• Add missing Pi/Paseo recipes to the tool catalog, and provide a composable configuration set for the mobile workflow. Tool switches and primary/worker preferences remain individually configurable and validated. Keep the native OS baseline minimal and setup idempotent; reuse existing installers.
• The current EasyPost set enables Bedrock. Validate the chosen Pi model through that work credential path; report missing configuration rather than silently switching providers. Preserve existing local credentials, Firstmate records, and private Paseo access/pairing.
• Reuse shared instructions and existing review practices, including a separate reviewer where required. Related work: feat(pi): share existing skills and role instructions #114 supplies Pi/shared-resource setup; feat(firstmate): allow Pi as the primary supervisor #117 supplies primary selection. The current Firstmate guide documents that existing checks use controlled agent shells and do not establish autonomous live supervision.

Done when

• A phone user can request two tasks and change priorities through one ordinary Paseo conversation, then review results and give feedback through GitHub issues/PRs without managing worker sessions.
• Issue comments and PR reviews/inline feedback wake the owning Pi session, trigger revisions, and receive a response in the same GitHub discussion without another Paseo prompt or a primary-agent relay. Approval and explicit delivery instructions follow the existing project policy.
• Work continues while the phone is disconnected, and reconnecting returns to the existing primary with outstanding decisions intact.
• Restarting the primary preserves accepted work, reconciles surviving workers, catches up GitHub feedback, and returns each result without duplicate dispatch, repeated revisions, or acknowledgment loops.
• Pi's real watcher/guard/branch extensions and the selected work provider are demonstrated through Paseo, including a worker completion that reaches the primary without another user prompt.
• Setup is opt-in, repeatable, and documented with start/resume/recovery commands and verified version constraints.
• One representative regression workflow exercises the actual integration entrypoint: submit work and steer it in Paseo, give GitHub review feedback while disconnected, observe direct delivery to the owning Pi session, recover the primary, and observe one revision cycle and the updated GitHub result. Extend existing detectors where applicable; keep controlled fixtures distinct from a live Pi/Paseo/GitHub smoke run and an actual phone check. Fixture success must not be reported as evidence of live supervision, GitHub event delivery, or mobile notifications.