Skip to content

spec(issue): labs show a failed turn inline with its reason and Retry (FIX-2550) - #4725

Merged
jhoffner merged 5 commits into
mainfrom
spec/FIX-2550
Nov 4, 2026
Merged

jhoffner merged 5 commits into
mainfrom
spec/FIX-2550

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Spec for FIX-2550, a child of FIX-2369. Merging this PR is approval. Read SPEC.md, then DECISIONS.md.

Who feels it

Someone who… Today After
sends a turn that fails in either lab The working line stops and nothing says why A red line names who failed and the reason, with Retry
presses Retry — The turn runs again and streams in; a refusal says so
watches a reply fail half-way The half reply reads as finished It is marked Incomplete, with the failure line under it

The goal

In both labs, a failed turn reads as a failure, with its reason and a working Retry, drawn by the registry's request-recovery. The direction is FIX-2370's (approved 2026-11-01); its two lab slices never landed. Control that must fail: dropping the "error" branch from each adapter fails its adapter case; Retry on every failed entry fails the newest-only case.

Need your sign-off

  • D1: Retry is a new adapter verb, retry(sessionId, requestId), over the client's existing request(id).retry(). It keeps each lab's rule that only the adapter touches a package.
  • D2: "Newest turn" is read from the thread's own items, so Retry shows on the last turn the person saw.
  • Decided, not asked: no startup key warning (E3). The failure line now carries the reason, and FIX-2406 is moving the Claude Code-style host file.

Debt: none new. No package changes. Docs: each lab README gains a row; no apps/docs change.

The implementation is being built now on a branch stacked on this one, and opens as soon as this merges.


Generated by Claude Code

… (FIX-2550)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDAAfKeTwqH2bFcZLD
@vercel

vercel Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Nov 4, 2026 11:40pm UTC
3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Nov 4, 2026 11:40pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Nov 4, 2026 11:40pm UTC
flow-state-dev-ui Ignored Ignored Preview Nov 4, 2026 11:40pm UTC

Request Review

@linear-code

linear-code Bot commented Nov 4, 2026

Copy link
Copy Markdown

FIX-2550

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-04T23:25:41.757091Z 577acca New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@jhoffner

jhoffner commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

jhoffner commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (spec FIX-2550)

Verdict: direction is sound and right-sized. Reusing request-recovery, error.tsx and request(id).retry() beats a lab-local red line, and a verb on the adapter is the right place for Retry. Findings below are things to settle before the implementation PR, checked against the code.

1. Doc contradiction on "who can be retried" (worth fixing in this change set)

packages/ui/registry/components/request-recovery.tsx (header) says "The server retries only a session's latest failed or interrupted request." DECISIONS D2 says the opposite: "the server takes a retry of any failed request". The engine agrees with D2: handleRetryRequest (packages/engine/src/routes/recovery-routes.ts) only checks status is failed/interrupted, with no latest-in-session check.

So newest-only is a UI rule, not a server rule. That is still a good rule (retrying an older failed turn after a newer one succeeded appends a reply out of order), but the spec should say that is why, and the component docstring (and apps/docs/docs/ui/flow-aware-components.md if it repeats it) should stop claiming the server enforces it. This is the one place the PR is an opportunity to fix a stale statement rather than carry it into two more apps. It is a doc-only edit in the registry, so it keeps "no package changes" in spirit, but it does touch packages/ui; say so in the spec.

2. "Byte-identical to the registry" has no enforcement

The spec says each lab installs request-recovery "byte-identical to the registry". The only drift tests are packages/ui/test/registry-drift.test.ts and apps/kitchen-sink/test/registry-drift.test.ts (which explicitly excludes request-recovery.tsx). Neither lab has one, so the claim is unverifiable and the verify list does not include it. Either:

  • add a lab drift case that reuses compareRegistryCopies (the helper already takes targetDir/notInstalled/appOnly), or
  • drop the "byte-identical" wording and say "copied".

Recommend the first. BP-003: a claim the change rests on needs an evidence path, and two labs plus Kitchen Sink is exactly the spread where copies drift. Note also that labs already hold error.tsx copies with no check.

3. latest computed twice, in two adapters

D2's "mark a failed entry latest when no item of a later request follows it" is specified per lab, and the unfinished-message-is-incomplete rule is too. Two adapters, same two rules, two test suites. Both labs keep their code separate on purpose (only the adapter touches a package), so I would not force a shared package, but the rule is a pure function of an ordered item list. Suggest the implementer writes it once as a small pure helper in each lab's lib/ with identical tests, or confirms in DECISIONS that a lab-shared helper was considered and rejected. Right now the spec is silent.

4. Edge: "newest" when a later request wrote nothing

D2 accepts that a request with no thread items (a Teammates board pass) can be the session's newest, so Retry shows on a turn that is not the server's latest. Since the server does not care (see #1) that is harmless, but the table row "Retry shows only on the newest turn" then reads as stronger than it is. Reword to "the last turn in the thread".

5. Smaller points

  • Control that must fail lists two red runs. Add a third for the incomplete mark: dropping the "unfinished message of a failed request" branch should fail an adapter case. As written that rule has no stated control.
  • FIX-2406 it.fails coupling: "whichever lands second removes the mark" is a hand-off with no owner. Name which PR is responsible, or the mark outlives the fix (an it.fails that starts passing fails the suite, so it will at least be noisy).
  • E3 (no startup key warning) is a reasonable cut; no objection.

Architecture pass

No refactor is warranted here beyond #3. The shallow-module risk to watch is Entry.tsx in each lab growing another failed branch next to interrupted; keep that mapping in the adapter (as specced) so Entry stays a switch on entry kind.

Nothing here blocks the direction. #1 and #2 should be folded into the spec or implementation; #3–#5 are notes for the implementer.


Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: b2995e19b9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/simplify review (spec-only PR)

Verdict: The overall approach is the right one — this is FIX-2370’s lab adoption, not a new product direction. Keeping RequestRecovery, routing Retry through the adapter (lab package boundary), and mapping engine error items in entriesOf / toEntries matches how both labs are built today. I would not introduce a shared @flow-state-dev/lab-* package or have screens call the client directly; D1’s chosen option is the thin, conventional wrapper.

Where this spec adds complexity beyond FIX-2370 (and where a cleaner shape is available):

1. Two owners for “newest Retry” (spec inconsistency)

FIX-2370 already models latest-only Retry as caller responsibility: pass onRetry or omit it (isLatest ? … : undefined in the KS example). This spec also has the adapter set “whether it is the newest turn” / “retryable” (SPEC verification + “What changes”) while the debt table says “newest-only Retry is the screen’s rule” and D2 has both adapter latest and screen gating.

That duplicates FIX-2370’s rule in two layers and can drift (adapter marks retryable, screen still hides while running — fine — but two flags for “newest” is easy to get wrong in tests).

Simpler alternative (recommended): Adapter maps error → an error/failed entry with reason + requestId + incomplete message flags only. Entry/screen derives newest retryable turn from ordered entries + “nothing running” (same as FIX-2370). Drop a persisted latest / retryable field on the entry unless you document one canonical owner.

2. D2 (thread items vs session requests) — defensible but heavy

The Teammates “invisible board pass” case is a real reason to prefer thread order over sessions.requests. The tradeoff (Retry visible when thread says newest but session’s newest request differs) is subtle; worth one explicit sentence in verification expectations so implementers don’t assume server “latest” === button visibility.

If that edge case is rare in practice, aligning with session latest failed request would match server retry rules more directly — optional simplification, not a blocker if product wants “what you see in the thread.”

3. Spec surface area vs delta spec

Large mirror of FIX-2370 (tables, mermaid, per-lab verification bullets) is readable but repeats closed direction. A shorter delta spec (gap → lab-only changes → pointer to FIX-2370 verification) would be easier to implement and review. Naming “failed entry” / kind: "failed" vs FIX-2370’s “error entry” adds a second taxonomy next to Teammates result.failed (task board).

4. E4 (Claude Code-style task run thread)

watchTaskWork already uses entriesOf on a run session that also omits "error" today (THREAD_ITEMS + suspension). Surfacing failures there is consistent once mapping exists, but it is extra scope beyond the main conversation rows in the title — Entry must not pass onRetry in task context. Fine as E4 if intentional; otherwise defer to keep the implementation PR smaller.

5. Verification / reuse (implementation hygiene, not direction)

  • FIX-2406 contract row (it.fails → FIX-2550): prefer one failed-turn spine (adapter pure-function tests + contract scenario) over four near-duplicate “per lab” integration narratives.
  • Kitchen Sink already has compareRegistryCopies for request-recovery; labs only say “byte-identical” in prose — consider calling out drift tests when implementing (same pattern as KS).
  • Reuse the ErrorItem fixture shape from packages/ui/test/render/request-recovery.test.tsx in lab adapter tests instead of re-specifying only in prose.

Performance

No spec-level concern. Implement failure + newest + incomplete in one pass over items already loaded in entriesOf / toEntries (avoid triple scans on an already hot mapper).


Summary: I’m not asking to reopen FIX-2370 or skip adapter.retry. I am asking to pick one place for newest-only Retry (prefer FIX-2370’s screen/Entry pattern), resolve the SPEC/debt-table contradiction, and optionally trim mirror prose + E4 scope. Happy to approve after that tightening; as written the direction is mergeable but the dual latest story is the main implementer hazard.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2550/SPEC.md Resolved
Comment thread specs/issues/FIX-2550/SPEC.md Resolved
Comment thread specs/issues/FIX-2550/SPEC.md Resolved
Comment thread specs/issues/FIX-2550/SPEC.md Resolved
Comment thread specs/issues/FIX-2550/SPEC.md Resolved
Comment thread specs/issues/FIX-2550/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2550/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2550/DECISIONS.md Resolved
…ly shows once stored

Folds review of the impl PR into D2 and SPEC.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiDAAfKeTwqH2bFcZLD
@jhoffner jhoffner added the spec label Nov 4, 2026
@jhoffner
jhoffner added this pull request to stack #4752 November 4, 2026 23:24
@jhoffner
jhoffner added this pull request to the merge queue Nov 4, 2026
Merged via the queue into main with commit ebec532 Nov 4, 2026
13 of 15 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2550 branch November 4, 2026 23:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants