CODER-006 — (Optional) Aggregate live session-status endpoint (one call for all sessions)

[serge-ivo]

Type: Backend

Description

Today the frontend polls /capture once per active session to learn each agent's busy/idle state. For a multi-repo "which agents are working" overview, provide a single lightweight status endpoint so the count of network calls doesn't scale with session count.

Acceptance Criteria

• GET /v1/instances/:id/coding/status returns { runnerConnected: boolean, sessions: Array<{ sessionId, repoId, runState, runnerConnected }> }.
• Returns quickly without dumping full terminal panes (status only — cheaper than /capture).
• Owner-scoped; reflects only the caller's sessions.

Technical Notes

• File: workers/api/src/routes/coding.ts. Reuse the runtime/relay status plumbing that /capture already uses, minus the pane payload. Frontend then replaces its per-session /capture status fan-out (in CodingTab.pollStatuses) with this one call.
• Trade-off: current per-session polling already works and is simple; this is an optimization for many concurrent sessions. Defer unless session counts grow.

Dependencies

None (enhances CODER-005).

[serge-ivo]

Architectural clarification (CODER-006)

Purpose. This is the polling implementation of the all-repos Working/Idle/Error indicator (the backend CODER-005 defers to). A single aggregate call replaces N per-session /capture calls.

Rate-limit tiers apply to status polling too. Active-tier sessions (active + recent user activity) → ~30s. Idle-tier sessions → 5–10 min or skip. This is unrelated to GitHub's limit — status comes from the runner via the relay, not GitHub — but the same active/idle tiering keeps request volume flat as session count grows.

Auth. Owner-scoped by the account JWT; the data is runner/relay state, so no GitHub token is involved (only build data touches GitHub).

Relationship to CODER-007. CODER-007 (WebSocket push) supersedes this as the primary mechanism; CODER-006 remains the fallback when the socket is unavailable.

[serge-ivo]

Decision recorded: CODER-006 demoted to fallback-only

Decision: Skip polling (CODER-006) as a stepping stone — build WebSockets (CODER-007) as the primary mechanism, with polling only as a fallback.

• CODER-006 (polling-based aggregate status) will NOT be built as a standalone feature first.
• It will only be implemented as a degraded fallback for clients that cannot maintain a WebSocket connection.
• The polling fallback must respect the same Active/Passive/Halted tiers decided in CODER-003: active ≈ 30s, passive ≈ 5min, halted = null (no polling).
• Building polling as a stepping stone and then replacing it with WebSockets would waste effort — skip the stepping stone.
• Priority: LOW — only build if WebSocket (CODER-007) cannot serve a particular client.

See CODER-007 (#83), now the primary deliverable.

[serge-ivo]

Status: intentionally deferred (kept open) — last, lowest-priority item

Per the recorded decision, CODER-006 is fallback-only, Priority LOW, and is superseded by CODER-007. Deferring it deliberately rather than building speculatively, for two concrete reasons:

1. Marginal benefit as a standalone endpoint. An aggregate /coding/status reduces the frontend from N /capture calls to 1, but the server still fans out N runner round-trips (there's no lightweight per-session status on the runner without a CLI change). The saving is client→edge requests only.
2. Would either be unwired or risk a regression. Shipping the endpoint alone = no consumer (the console's pollStatuses already reads /capture directly). Wiring the console to it means rewiring the core status-polling loop — real regression surface — for that marginal gain, on an item explicitly marked LOW/optional.

When to build it: if CODER-007 (WebSocket push) proves it can't serve some clients (so polling stays the mechanism) and repo/session counts grow enough that the N-call fan-out actually matters. At that point it's a clean change: add GET /v1/instances/:id/coding/status (status-only, no panes) and switch CodingTab.pollStatuses to it in one commit.

Shipped this session in the build order: CODER-001, -002, -003, -004, -005 (+ CODER-008 and #100). Remaining open: this (#82, deferred) and CODER-007 (#83, deferred — blocked on its own consumer/producer). Leaving both open.