[Feature]: Agent-driven workspace board status transitions with heartbeat polling

[slashdevcorpse]

Problem

The workspace board is a manual kanban. Users drag cards between columns (todo, in-progress, in-review, completed), but nothing keeps these states accurate. Cards sit in "in-progress" long after a PR is merged. Agents finish work but the card stays where it was. The board goes stale because nobody remembers to update it.

Proposal

Two board modes, toggled in settings:

1. Manual board (current behavior, default). User drags cards. Nothing changes.
2. Agent-driven board. Agents infer workspace status from corroborating signals. The user acts as the PM: final authority, can override or lock any transition.

This requires agent tokens/activity to function, so it must be an explicit opt-in toggle. Users who do not want agent cycles spent on board management keep the manual board.

Core Principle

Agents prove work happened. The system proposes a transition only when multiple signals agree. The user's last word is law.

Signal to Status Mapping

Signal	Corroborating Evidence	Proposed Transition
Worktree created, no commits	None needed	to do
First commit on branch OR agent status reports working	Both ideally, either sufficient	in progress
PR opened (linkedPR detected)	Branch has commits	in review
Agent status reports done + no PR exists yet	Commits exist on branch	in review
PR merged	CI passed (if available)	completed
PR review has comments/requested changes	Feedback detected on linked PR	back to in progress
Re-push after addressing feedback	New commits after review comments	in review (again)

That last row is critical. When a PR is "in review" and gets feedback (requested changes, blocking comments), the workspace moves back to "in progress" because there is work to do. Once the agent or user pushes fixes, it returns to "in review". This loop continues until the PR is approved and merged.

Heartbeats via Automations

The feedback detection (PR comments, review status, CI failures) should run as a heartbeat automation using Orca's existing automations system. This keeps the polling visible and configurable.

Proposed implementation: a built-in automation type (or a preset template) that runs on a schedule and checks linked PR status:

orca automations create \
  --name "Board status heartbeat" \
  --trigger "*/15 * * * *" \
  --prompt "Check linked PR status for all active workspaces. If review feedback exists, move to in-progress. If approved and CI green, move to completed." \
  --provider claude \
  --workspace-mode existing

The heartbeat checks:

• PR review state (approved, changes requested, commented)
• CI status (passing, failing)
• New comments since last check
• Merge status

These heartbeats should be visible in the Automations tab so users can see when they last ran, what they found, and what transitions they proposed. This is the same pattern as GitHub bots that review PRs, but operating on the local board state.

Configuration

Settings > Workspace Board:
  Board mode:
    ( ) Manual (default, current behavior)
    ( ) Agent-driven (uses agent tokens for status inference)
  
  When agent-driven:
    [x] Move to "in progress" on first commit or agent activity
    [x] Move to "in review" when PR is opened
    [x] Move back to "in progress" when review feedback received
    [x] Move to "completed" when PR is merged
    
  Heartbeat interval: [every 15 minutes v]

The heartbeat automation appears in the Automations tab alongside user-created automations, clearly labeled as a system automation. Users can pause it, change its schedule, or view its run history like any other automation.

Existing Plumbing

• worktree.set RPC accepts workspaceStatus (the write path exists)
• Agent hook server already emits agent states (working, blocked, done)
• linkedPR field already exists on worktrees
• Board UI already reacts to status changes in real-time
• Automations system already supports scheduled agent runs with workspace targeting
• Automations tab already shows run history and status

Most of the wiring is already in place. What's missing is a thin inference layer connecting these signals to the write path, plus a heartbeat template for PR/review polling.

[nwparker]

Triaged against current origin/main (399ad3e42d). I do not think this is safe to implement as one feature slice yet, because the issue crosses several existing ownership boundaries: manual board metadata, live agent hook state, hosted-review/CI refresh, and the Automations scheduler.

Evidence from the current architecture:

• The workspace board status is currently modeled as user-authored metadata, not derived state. src/shared/types.ts:316-317 documents workspaceStatus as a "User-assigned workspace board status" field, defaults live in src/shared/workspace-status-defaults.ts:10-20, and getWorkspaceStatus falls back to the configured default in src/shared/workspace-statuses.ts:267-274.
• The board writes status directly from user gestures. src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.tsx:117-125 writes a single status move via updateWorktreeMeta(worktreeId, { workspaceStatus: status }); src/renderer/src/components/sidebar/WorkspaceKanbanDrawer.tsx:180-188 does the same for drag/drop batches. src/renderer/src/components/sidebar/workspace-kanban-worktree-groups.ts:16-32 groups cards purely from the current workspaceStatus.
• The write seam exists, but it is generic metadata persistence. The renderer persists local vs remote updates through src/renderer/src/store/slices/worktrees.ts:453-468 (worktree.set for remote runtimes), and optimistically updates local store before persistence in src/renderer/src/store/slices/worktrees.ts:1306-1427. The runtime RPC schema/method accepts workspaceStatus (src/main/runtime/rpc/methods/worktree-schemas.ts:54,131, src/main/runtime/rpc/methods/worktree.ts:89-113), and runtime create paths carry it through (src/main/runtime/orca-runtime.ts:7357-7438, 7688-7721, 7937-7990). The CLI worktree set surface does not currently expose a workspace-status flag (src/cli/handlers/worktree.ts:142-151, src/cli/specs/core.ts:123-134).
• Agent status is live pane state, not a durable worktree-status source. The hook server snapshots cached pane status via src/main/agent-hooks/server.ts:443-450, updates/notifies from src/main/agent-hooks/server.ts:640-670, and clears/drops entries in src/main/agent-hooks/server.ts:1121-1163. The renderer slice says agentStatusByPaneKey is "Real-time only — lives in renderer memory, not persisted to disk" in src/renderer/src/store/slices/agent-status.ts:34-37, and mapping status to worktrees depends on current tab ownership in src/renderer/src/components/sidebar/useWorktreeAgentRows.ts:97-115.
• Linked review/CI state is provider-specific and partly cache-driven. PR creation links GitHub PR numbers to worktree metadata in src/renderer/src/components/right-sidebar/ChecksPanel.tsx:1296-1318; runtime worktree.ps only reads GitHub PR cache/fallback metadata and falls back to state: 'unknown' from linkedPR in src/main/runtime/orca-runtime.ts:4991-5011. GitHub visible/background refresh has rate-limit budgets and state-dependent intervals in src/main/github/pr-refresh-coordinator.ts:31-37 and 291-307; the Checks panel separately polls visible PR checks in src/renderer/src/components/right-sidebar/ChecksPanel.tsx:681-697. The repo also has GitLab/Bitbucket/Gitea/Azure hosted-review clients, so an agent-board transition policy should not bake in GitHub-only semantics.
• Automations are currently agent-run scheduling, not a neutral metadata poller. src/main/automations/service.ts:14-72 defines a 60s internal scheduler that creates automation runs and dispatches them; src/main/automations/service.ts:176-214 evaluates due runs. src/shared/automations-types.ts:57-80 models an automation as prompt + agent + workspace execution metadata, and src/renderer/src/components/automations/AutomationsPage.tsx:580-636 marks runs complete from agent-status done entries. A board heartbeat that polls PR/CI/comment state needs a clear product/runtime contract before reusing this surface, otherwise it may accidentally look like an agent job or conflict with SSH/external automation managers.

Suggested decomposition:

1. Define the status authority contract first: default remains Manual, Agent-driven is opt-in, manual overrides/locks win, and every automatic proposal records provenance/reason. This likely needs settings plus per-worktree metadata such as mode/lock/manualOverrideAt/proposedStatus rather than immediately overwriting workspaceStatus.
2. Add a provider-agnostic, deterministic status transition reducer with tests and no side effects. Inputs should be a normalized signal snapshot (currentStatus, status IDs/config, board mode, lock/manual override state, commit/dirty/ahead state, latest agent state, linked review state, check state, review-feedback timestamps, last push timestamp). Output should be a proposed transition {status, reason, confidence, requiresUserConfirmation} or no-op.
3. Build signal collectors separately: git/worktree activity, live + retained agent state, and hosted review/CI state for GitHub and non-GitHub providers, with SSH-aware paths.
4. Add an apply layer that writes through the existing worktree.set/updateWorktreeMeta seam only after the reducer and authority contract allow it.
5. Only then add the heartbeat/Automations integration and UI affordances, because the current Automations model is prompt/agent-run oriented and the issue describes provider polling/history.

First safe PR recommendation: add the pure reducer + contract types under src/shared/ with focused tests covering precedence and stale-signal behavior, but do not write workspaceStatus from it yet. Example test cases: manual/locked status never changes; first commit or live working proposes in-progress; PR/MR open or agent done with commits proposes in-review; merged review plus successful required checks proposes completed; review feedback after the last agent submission proposes in-progress; a re-push after feedback proposes in-review; missing/custom status IDs produce no destructive write. This gives us an evidenceable core policy before touching board UI, runtime polling, provider APIs, or automations.