feat(crews): a Crew thread's provider approvals and questions reach the Inbox API

[bryantderosier]

Important

⚠️ Merge order: merge these in this exact order

#309 is based on #308, so #308 merges first. Neither has migrations or ordering against the other Crews PRs.

1. feat(crews): a Crew thread's provider approvals and questions reach the Inbox API #308: A Crew thread's provider approvals and questions reach the Inbox API ⬅️ this PR
2. feat(crews): answer a Crew thread's provider approvals and questions from the Inbox #309: Answer a Crew thread's provider approvals and questions from the Inbox

Problem

When a thread is a Crew Captain or a live seat, every approval or question its provider raises (tool approvals, and user-input questions like Claude's AskUserQuestion or Codex's request_user_input) renders only in that thread's composer. Captains and seats run while I'm elsewhere, so those prompts sit unseen and the Crew stalls (#263). My rule: anything a Captain or seat needs from me goes to my Inbox; the initial roster card is the one exception.

What I changed

• apps/server/src/j5/a2a/CrewRuntimeRequestService.ts (new):
  • list reads the pending requests on every live Crew's Captain and seat threads straight from their projections.
  • pendingCrewThreadRequests does the selection, mirroring client-runtime's derivePendingThreadRequests, which the server can't import: pending only, questions with their item, and no auth_refresh or dynamic_tool_call.
  • respond checks that the thread belongs to a live Crew and the request is still pending, then dispatches runtime-request.respond.
• apps/server/src/j5/a2a/CrewRuntimeRequestsHttp.ts (new): POST /api/j5/a2a/crews/runtime-requests (read scope) and .../respond (operate scope). 404 for anything outside a live Crew, 409 once resolved, 400 for the wrong answer kind.
• packages/contracts/src/j5.ts: CrewRuntimeRequestItem, the list response, and the respond request and response; both paths are added to J5_API_PATHS.
• Wiring: the service in j5/a2a/runtimeLayer.ts, the routes in J5AuthenticatedRoutes.ts, and the two aggregate tests gain a service mock.

After Tyler's review

• Thread reads go through getThreadProjectionIfPresent, so only a real not-found or an archived thread reads as absent. A store or listLive failure now propagates: list returns a logged 500 instead of an empty Inbox, and respond no longer calls a live request not found.
• respond looks requests up through the same selector as list. Hidden kinds and questions without their item are never answered, and a request that isn't live is refused with the way out.
• A dispatch refusal carrying the decider's string reason is a 409. Any other dispatch failure is CrewRuntimeRequestDispatchError, a logged 500.
• list reads a Crew's threads concurrently. The narrower read is Crew request polls read only pending runtime requests #324.
• The selector moved to J5-owned packages/shared/src/j5/crewRuntimeRequests.ts and matches derivePendingThreadRequests. packages/client-runtime/src/j5/crewRuntimeRequests.test.ts runs both over every branch and fails if they drift.

Why this shape

I serve this as its own Inbox source rather than as ledger Exchanges: HumanInboxService.answer writes an A2A reply, not a provider response. I read live state from the projection rather than copying it into a table, so there's nothing to keep in sync and a resolved or retired request just stops appearing. Each answer gets a fresh command id, so a second answer is refused by the request's own state instead of being silently deduplicated.

Invariants

• Only live Crews count: a thread outside every live Crew is never listed or answered, and a retired Crew's requests leave the list.
• An answer to a request that already resolved, including one answered inline on another device, is refused and dispatches nothing. A race lost between our read and the command is refused by the orchestrator and mapped to 409.
• A reserved seat with no thread, or an archived thread, is skipped.

Surfaces

Surface	Decision
Entry points (chat, Settings, command palette, keybinding)	Unaffected; the web Inbox is #264 (next in this stack).
Clients (web, desktop, mobile)	Server and contract only here.
Providers	Provider-agnostic: it reads the orchestrator's runtime requests.
Contracts (packages/contracts)	J5 contract additions only.
Reverse states	A request leaves the list once resolved or its Crew retires.
Connection modes (local, remote, tunnel)	Same authenticated J5 route pattern as the Crew stop and proposal routes; POST for the CORS allowlist.
Upstream files / FORK.md	None.
Docs	In #264.

Out of scope

• A Crew thread's provider approvals and questions are answered from the Inbox, not inline (web) #264: the Inbox section, the bell count, and the thread note.
• Mobile: it has no J5 Inbox yet.

Upgrade and data

None. No table, no migration.

Verification

• CrewRuntimeRequestService.test.ts uses the real Crew store and a thread mock that resolves a request once, as the orchestrator does. It covers:
  • seat and Captain requests listed with their Crew and seat;
  • the stranger thread never listed;
  • one answer resolving and a second refused with nothing dispatched;
  • an answer after an inline answer refused;
  • a wrong-kind answer refused;
  • a retired Crew leaving the list.
• CrewRuntimeRequestsHttp.test.ts: readers list, readers get 403 on answer, operators 200 then 409, plus 404 and 400.
• A dispatch-race case: a request resolved between the read and the command is refused with the orchestrator's own reason (434e1f47ef, found in feat(crews): answer a Crew thread's provider approvals and questions from the Inbox #309's seeded dev-server pass, where the refusal only named the command id).
• vp test run apps/server/src/j5: 686 passed at open; the J5 a2a suite passes after the fix. Server typecheck clean.

Review focus

• respond reads, checks pending, then dispatches, and the orchestrator rechecks pending. Is the 409 mapping right for every dispatch error, or should some be 500?
• list walks every live Crew's threads on each poll; there are usually a handful, but check the cost assumption.

Closes #263

Claude Opus 5.5 via Claude Code

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository: Jacksondr5/j5code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: c8cdd59b-dbc9-49b2-9c19-3c686061f37d

---

_{Comment @coderabbitai help to get the list of available commands.}

[bryantderosier]

@tyler-barton-horizon Thanks for the careful review. All eight points were real, and I've addressed each one in its thread and resolved it. In short:

• feat(crews): a Crew thread's provider approvals and questions reach the Inbox API #308, 81b6e3f:
  • Store and listLive failures now propagate: list returns a logged 500 instead of an empty Inbox, and respond no longer calls a live request not found.
  • respond answers only what list shows.
  • A dispatch refusal is a 409; any other dispatch failure is a logged 500.
  • list reads a Crew's threads concurrently.
  • The selector now matches derivePendingThreadRequests, and a client-runtime test holds the two together.
• feat(crews): answer a Crew thread's provider approvals and questions from the Inbox #309, dd3046d: the Inbox offers answers only for live requests, and the composer keeps message-mode and non-resumable requests inline.
• Crew request polls read only pending runtime requests #324: the narrower "pending requests only" read, which needs a new projection-store query in upstream-owned code.

CI is running on both branches now.

[Jacksondr5]

[Review panel: Opus 5.5 + Astra] FORK.md: this row points at a case that doesn't exist in this PR.

#308 changes the packages/shared/package.json row to 43, 46, but case 46's text only arrives in #309. If #308 lands alone, the row cites a missing case. Worse, per the known collision: if #302 lands between #308 and #309 and takes case 46, this row then points at the Captains case. Nobody will notice, because #309's renumbering pass only touches rows #309 itself edits.

Fix: give #308 its own short case covering what it adds to upstream-owned files (the ./j5/crewRuntimeRequests export in packages/shared/package.json and the parity test's dependency on derivePendingThreadRequests), and have #309 extend that case for ChatView.tsx. Alternatively, if you take the simplification in my other comment, the shared/package.json edit goes away and so does this row change.

[Jacksondr5]

[Review panel: Opus 5.5 + Astra] A Captain's request is listed once for every live Crew it commands.

A Captain can command several live Crews at once (docs/j5/product/features/crews.md:29, "One Captain, many Crews"). liveCrewThreads adds the Captain's thread once per Crew, so with two live Crews under one Captain, list returns every pending Captain request twice, differing only in crewInstanceId/crewName. In #309 this means:

• two cards with the same itemKey (env:thread:request), which gives duplicate React keys and a shared answer draft;
• the bell counts the request twice;
• answering one card resolves the request, and answering the other gets a 409.

Fix: emit each Captain thread once (dedupe by threadId). A Captain's request isn't about any single Crew, so either list it with the first Crew or drop the Crew name for Captain rows. Add a test with two live Crews under one Captain that asserts one item.

[Jacksondr5]

Decision (Jackson, 2026-09-26): slim #308/#309 to seat approvals only.

The Captain is the thread the person watches by design, so the Captain's approvals and questions stay inline in its own thread. Seats are what the person isn't watching, and seats will no longer have native question tools; they ask their Captain instead (#325). What's left for the Inbox is seat approvals.

For #308 that means:

• List and answer only requests on seat threads. The Captain's thread is excluded.
• Approvals only. Drop the question-answer path from respond, the contract, and the selector.
• List only requests the Inbox can answer (live). Requests that can only be answered in the thread stay there and don't count on the bell.
• The panel's fixes that still apply:
  • the FORK.md row that cites a case before it exists;
  • list each thread's request once, even when a thread appears in more than one Crew record (dedupe by thread id).
• Keep the J5-owned selector copy and its parity test. Don't import from client-runtime: the server shouldn't take a dependency on a client package.

Related: custom seats will default to Full access and the roster card will warn about seats with limited access (#326), so seat approvals should be the exception rather than the norm.