[brentkelly]

Part 4 of 4 of T3O-55: syncs the fork to upstream v0.1.0 (the first orchestration-v2 release) and moves the board onto v2 behind a new board/ThreadGatewayV2.ts.

How: main fast-forwarded to v0.1.0 and merged into this branch with a merge commit (never squash — land this as a no-ff merge per docs/t3o/seams.md). v1 deletions taken, ThreadGatewayV1 replaced by ThreadGatewayV2 (commands through ThreadManagementService, reads from v2 stores, signals from the v2 event stream), board MCP tools re-declared through McpToolAccess, board RPCs added to WsRpcGroup, board kept inside the ServerSettings schema, usage-limit recovery delegated to v2's limitRecovery, and a one-time boards.pre-v2.sqlite backup on first v2 boot. Seam decisions are recorded in docs/t3o/seams.md.

Upgrade note: a Building column should ideally be drained before upgrading. In-flight steps whose runs vanish at the upgrade go through the existing restart and orphan recovery.

Not done: no end-to-end card run with real providers, no live usage-limit recovery pass, and no visual check of the web board.

Model: Claude Opus 5.5 via Claude Code (T3o board).

🤖 Generated with Claude Code

[brentkelly]

High-level summary

This PR syncs the fork to upstream v0.1.0 with a merge commit and ports the board onto orchestration-v2. ThreadGatewayV2 replaces the v1 gateway. Board MCP tools are re-declared through McpToolAccess, board RPCs join WsRpcGroup with scopes, board stays inside the ServerSettings schema, boards.sqlite gets a one-time pre-v2 backup, and usage-limit resumes are handed to v2's limitRecovery. The port is careful. Seams are small and marked, and the gateway's command mapping (create plus first turn without launch preparation, mode setting before send, snapshotAt-guarded auto-settle) matches v2's semantics. The v2 contract suite on the real engine gives good confidence.

I found five improvements and one nitpick, and nothing critical:

• Usage-limit handoff: an armed limit that v2's worker declines to resume leaves the step parked forever.
• Signal stream: one error ends the gateway's signal stream for good.
• Latest assistant message: each turn end loads the thread's whole assistant history, because v2 never fills the shell's latest-message fast path.
• PR summary reads: the T3O-54 missing-scope fallback on the batched summary read was dropped, which regresses tokens without the Checks permission.
• waiting runs: the shared board-thread-state adapter maps a waiting (post-turn checkpoint) run to running, which contradicts the gateway.

The nitpick is a stale seams.md inventory row.

Not reviewed in depth: the 1,000+ upstream commits themselves, and the web board's visual behaviour. The build notes say no end-to-end card run with real providers was done; that still needs a supervised pass before landing.

Important

This PR touches 16,062 files (mostly vendored .repos/), and GitHub exposes only the first 3,000 for line comments. None of the files below are among them, so the API rejects inline anchors. Each finding is posted here instead, with a permalink to the exact lines at 18ef762bbb.

Findings

---

apps/server/src/board/ThreadGatewayV2.ts:120-130

Warning

Improvement (1/5): resumeArmed trusts an arm that v2 will never act on, so the step stays parked forever

resumeArmed is true whenever limitRecovery matches the latest run and reset time with autoResume. armLimitRecovery arms any limited thread that has a resetAt. v2's limitRecoveryCommand (orchestration-v2/UsageLimitRecoveryWorker.ts:27-33) declines to resume when the reset time is not after latestRunCompletedAt ("an already-expired window reported with a fresh failure"). It also declines while a runtime request is pending, or once the thread is archived or settled. boardWokenLimitParks (supervisorReactor.ts:3632) then excludes the armed step from both wake paths. The provider sweep at supervisorReactor.ts:7011 sees no parked steps and clears the provider limit. Neither v2 nor the board ever resumes the step.

This is reachable: a provider that reports a coarse reset time ("resets 3pm") resolved to a past instant, or a small clock skew, gives resetAt <= completedAt. The card then sits parked with no recovery path and no human signal.

Suggested fix: Have resumeArmed (or boardWokenLimitParks) apply v2's own eligibility test. Export or mirror the resetMs > latestRunCompletedAt / no-pending-request / not-archived checks from limitRecoveryCommand, and don't arm a limit v2 will refuse in armLimitRecovery. Add a supervisor test where the reported reset precedes the run's completion and assert the board's probe wakes the step.

---

apps/server/src/board/ThreadGatewayV2.ts:648-660

Warning

Improvement (2/5): One stream error ends the supervisor's thread signals until the next restart

observe is eventSink.stream(...) with Stream.catchCause turning any failure into a log line and a normal end. supervisorReactor.ts:9028 consumes it with a single Stream.runForEach inside forkParked, so when the stream ends, nothing re-subscribes. Unlike v1's in-memory PubSub streams, EventSinkV2.stream reads the database for its catch-up replay (catchUp pages through the event store), so a transient SQLite error (busy, I/O) can fail it. After that the board silently stops seeing turn ends, questions, interrupts and human restarts. Every running step then waits for the timeout sweep, and parked steps never resume on a human reply. The only trace is one logError.

Suggested fix: Make the subscription self-healing. Track the last stored.sequence seen and wrap the stream in a retry with backoff (for example Stream.retry(Schedule.exponential(...)) over a Stream.suspend that resumes from that sequence). Keep the makeSignalReader instance across retries so dedup survives. A test that fails the sink once and asserts a later run.updated still arrives would pin it.

---

apps/server/src/board/ThreadGatewayV2.ts:586-600

Warning

Improvement (3/5): latestAssistantMessage always loads the thread's entire assistant history

The fast path reads shell.latestVisibleMessage, but the v2 projection store never fills it: both shell builders set latestVisibleMessage: null (ProjectionStore.ts:1568, :1832), and nothing else in the server writes it. Every call therefore takes the fallback, getThreadRecords(threadId, ["messages"], { messageRoles: ["assistant"] }). That query has no limit (ProjectionStore.ts:3243-3245, ORDER BY created_at ASC), and the code keeps only .at(-1). endedWithQuestion calls this on turn ends and stops. A long Building or review thread has hundreds of assistant messages, each with its full text, so every turn end decodes the whole history to read one message. That is the kind of hidden cost AGENTS.md asks us to avoid, and the dead fast path makes the code misleading.

Suggested fix: Remove the latestVisibleMessage branch and bound the read. Pass messageRunIds: [shell.latestRunId] (falling back to the unbounded read only when that run has no assistant message), or add a small "latest message by role" read. Either way, cover it with a test on a thread with several runs.

---

packages/source-control-github/src/server/GitHubPullRequestApi.ts:1864-1873

Warning

Improvement (4/5): The batched PR summary read lost the T3O-54 missing-scope fallback

PULL_REQUEST_SUMMARY_SELECTION (gitHubPullRequestJson.ts:2110) asks for commits(last: 1) { ... statusCheckRollup ... }. GitHub refuses the whole document for a fine-grained token without the Checks permission. The batched read then falls back to viewPullRequestSummary per entry, which sends the same selection and is refused again. With such a token, every linked pull request's summary read fails on every background sync tick. The board loses the open/merged/closed state it advances cards on, and each tick spends 1 + N doomed GraphQL calls. T3O-54 (f0b78a2a16) fixed exactly this, and this PR drops it (only the core detail read's T3O-8 fallback is re-seamed). The build notes acknowledge it as not done, but nothing tracks it, and it silently regresses shipped behaviour.

Suggested fix: Re-apply the fallback. t3oGraphQlScopeFallback.ts already has the selection-removal helper. Wrap the batched and single summary reads in readCoreWithScopeFallback-style retries that drop commits( on a scope refusal, then fill an empty rollup back in before decodePullRequestSummariesJson. Restore the T3O-54 tests against the API client. If you defer it instead, open a follow-up card and record it in seams.md as a known regression rather than a footnote.

---

packages/shared/src/boardThreadState.ts:25-45

Warning

Improvement (5/5): The shared adapter and the gateway disagree on what a waiting run is

This module exists "so the two cannot disagree", but it treats a waiting run as "held on a runtime request, still mid-turn" and maps it to running. In v2, waiting is the post-turn checkpoint drain: RunExecutionService.ts:663 writes completed → waiting, and Orchestrator.ts:548 says the agent turn is over. The server gateway knows this. turnOutcomeOf ends the board turn at waiting, and its own sessionStatusOf (ThreadGatewayV2.ts:74-87) maps waiting to idle, so the session status is derived twice with opposite answers. On the client, a card whose turn has ended reads as working (blue) for as long as checkpoint capture takes. boardThreadBackgroundLiveness returns null for any non-null activityRunStatus, so background work also goes unseen during that window. Pending input and approvals come from pendingRuntimeRequest, not the run status, so nothing needs waiting → running.

Suggested fix: Map waiting the way the gateway does: treat it as not running and let background liveness through. Correct the docstring, and have ThreadGatewayV2 use boardThreadSessionStatus instead of its private sessionStatusOf, so one definition serves both. Add a boardThreadState.test.ts case for a waiting shell.

---

docs/t3o/seams.md:874-875

Note

Nitpick (1/1): Seam inventory still lists the retired headSha seams

This sync deleted the fork's headSha on PullRequestDetail and its carry in PullRequestService.ts, because upstream v0.1.0 ships the field natively. The inventory still lists both rows as live seams, so the next sync's census will look for markers that no longer exist.

Suggested fix: Drop these two rows, or move them to the "retired" notes with a line saying upstream now provides headSha.

[brentkelly]

I1 — fixed (ba7a7a9bf7). resumeArmed now also requires that v2's recovery worker would actually act on the arm, read through the worker's own policy: limitRecoveryCommand(shell, true, +∞) !== null, which rules out archived and settled threads, a pending runtime request, and a reset no later than latestRunCompletedAt. armLimitRecovery returns false for such a thread, so the board keeps its own wake path. Test: ThreadGatewayV2.test.ts › "reads an arm v2 will never act on as not armed, so the board still wakes it". It fails without the fix and passes with it.

[brentkelly]

I2 — fixed (51ece73e05, 830139cb20). New followStoredEvents keeps a cursor at the last delivered sequence. On a stream error it logs, then resubscribes after that cursor with capped exponential backoff (1 s, up to 30 s), the shape server.ts uses. Only a defect still ends the stream. The signal reader's once-only memory lives outside the retry, so nothing is reported twice. Test: ThreadGatewayV2.test.ts › "resubscribes after the last delivered event when a read fails" (events 11, 12, fail, then 13, resubscribed after 12). It fails with the retry removed.

[brentkelly]

I3 — fixed (25812f54a8). latestAssistantMessage now reads assistant messages with messageRunIds: [shell.latestRunId], so the read covers one run, not the whole history. I dropped the always-null latestVisibleMessage branch. Nothing is lost: endedWithQuestion, the only caller, already discards anything older than the last resume, and that resume is the latest run. Contract test on the real v2 engine: ThreadGatewayV2.contract.test.ts › "the latest assistant message is read from the latest turn only". A newer message from another run is ignored; the test fails on the unbounded read.

[brentkelly]

I4 — fixed (b4fd9e2beb). Re-applied T3O-54 as readSummariesWithScopeFallback in t3oGraphQlScopeFallback.ts. On a scope refusal it reads again with coreQueryForFields(query, ""), which strips every commits(...) rollup selection. It wraps both the batched aliased read and the single-entry fallback, each behind a T3o: marker, so neither path is refused on every tick. The summary decoder already reads absent commits as checksState: null. Test: GitHubPullRequestApi.test.ts › "reads the batch again without the check rollup when the token is refused it". It fails before the change; seams.md is updated.

[brentkelly]

I5 — fixed (e8f4973232). Confirmed: RunExecutionService persists a completed provider turn as waiting (line 663). @t3tools/shared/boardThreadState is now the single definition. A waiting run reads as ready unless it still holds an answerable runtime request; that exception keeps T3O-16's permission-prompt rule intact. Its background work counts again. The gateway's sessionStatusOf now only renames the shared status (ready→idle, null→none), so the two cannot drift. Test: boardThreadState.test.ts › "reads a run awaiting only its checkpoint as a turn that has ended". It fails before. Server, client-runtime and web board suites pass.

[brentkelly]

N1 — fixed (e969491a78). Removed both headSha inventory rows. The PullRequestService.ts seam was still in the code, and it duplicated upstream's own headSha carry (line 1821), so I deleted it. The decisions section and the T3O-47 prose now say the seams are retired, and the census is 150 markers (−1 headSha, +2 summary fallback).

[brentkelly]

Adjudication round 1: I1, fix upheld. v2RecoversLimit calls limitRecoveryCommand(shell, true, +Infinity). That call returns null for exactly the refusals named in the finding: archived, settled, a pending runtime request, and a reset no later than the run's completion. A matching autoResume arm still gets a resume command. resumeArmed and armLimitRecovery both gate on it. The new test 'reads an arm v2 will never act on as not armed…' fails against the pre-fix source and passes at 830139c.

[brentkelly]

Adjudication round 1: I2, fix upheld. followStoredEvents updates its cursor on every delivered event, and Stream.retry re-runs the unwrap, so it resubscribes from afterSequence: cursor with a capped exponential backoff (infinite, max 30s). observe now uses it. The 'resubscribes after the last delivered event' test checks that delivery is [11,12,13] and the subscriptions are [10,12]: no signal is dropped or repeated. It passes, and fails pre-fix.

[brentkelly]

Adjudication round 1: I3, fix upheld. getThreadRecords is now filtered by messageRunIds: [shell.latestRunId], a filter the projection store supports (run_id IN json_each(...)). The dead latestVisibleMessage branch is gone. The contract test 'the latest assistant message is read from the latest turn only' runs on the real v2 engine, passes, and fails pre-fix.

[brentkelly]

Adjudication round 1: I4, fix upheld. readSummariesWithScopeFallback retries both the single and the batched summary reads through coreQueryForFields(query, "") on a scope refusal. That call strips the commits( selection, and the summary decoder treats the missing rollup as checks unknown (rollupChecksState → null). The test 'reads the batch again without the check rollup…' passes and fails pre-fix. Both seams carry T3o: markers.

[brentkelly]

Adjudication round 1: I5, fix upheld. I confirmed that RunExecutionService persists a completed terminal run as waiting (line 663). boardThreadSessionStatus now treats waiting as ended unless the run holds an answerable request, and background liveness now follows that status. The gateway's sessionStatusOf derives from the shared adapter, so the two places agree. The new shared test passes and fails pre-fix, and the existing question/permission test still passes.

[brentkelly]

Adjudication round 1: N1, fix upheld. The seam inventory in seams.md no longer lists the headSha rows; the only remaining mentions record the retirement. Removing the PullRequestService seam is safe because upstream already carries headSha (PullRequestService.ts:1821).

[brentkelly]

High-level summary — round 2 (re-review at 830139c)

This PR merges upstream v0.1.0 (orchestration-v2) into the fork with a merge commit and moves the board onto v2 behind ThreadGatewayV2. It also re-applies the fork's MCP, RPC, settings, persistence and source-control seams at their new homes. This round re-read the seven fix commits since 18ef762bbb against the v2 code they depend on, then took a fresh look at the gateway, the supervisor's usage-limit hand-off and the pre-v2 board backup.

Every fix holds up against how v2 behaves:

• v2RecoversLimit calls the recovery worker's own limitRecoveryCommand. An arm with autoResume is picked up by getLimitRecoveryCandidates whatever the global setting, so the board's boardWokenLimitParks exclusion now matches what v2 will actually resume.
• followStoredEvents keeps its cursor across Stream.retry, so a resubscribe neither drops nor repeats an event, and the signal reader's dedupe state lives outside it.
• latestAssistantMessage is bounded to the latest executed run (queued runs are skipped when that run is chosen).
• The summary scope fallback strips only the commits( rollup selection, which the summary decoder already reads as checks unknown.
• waiting now has a single reading in @t3tools/shared/boardThreadState, and it matches v2's post-terminal drain (Orchestrator.ts:548).

There are no unresolved human comments on the PR. This round has 0 critical, 0 improvement and 0 nitpick findings, and nothing blocks. The open items are the ones the build already flagged as not done: a supervised end-to-end card run and live usage-limit recovery with real providers. Those belong in the manual landing pass, not this review.

Status of round-1 findings

#	Prior finding	Status
I1	🟡 resumeArmed trusts an arm v2 will never act on; step stays parked forever	✅ closed
I2	🟡 One stream error ends the supervisor's thread signals until restart	✅ closed
I3	🟡 latestAssistantMessage always loads the thread's entire assistant history	✅ closed
I4	🟡 Batched PR summary read lost the T3O-54 missing-scope fallback	✅ closed
I5	🟡 Shared adapter maps a waiting run to running, contradicting the gateway	✅ closed
N1	🟢 Seam inventory still lists the retired headSha seams	✅ closed

🤖 Generated with Claude Code