Repository navigation
spec(FIX-1664): amend task-to-run association and metrics source - #2434
Conversation
Post-merge amendment to the retained spec merged in #2428. - D1: the Session reads the run the task's own row names, via a small gate-stamped task-run link in @flow-state-dev/orchestration (Layer 2), split out as its own child of FIX-1649. Replaces matching a rebuilt dispatch key against the display-only topic, which was ambiguous across coordinator sessions and could not serve per-worker/custom policies. BR-3, BR-5, BR-7, BR-8, BR-11, PLAN S2/S3/S4/S7/V1, sketch and the what-changes and d1 figures follow. - Harness, tokens and cost become a named gap owned by FIX-1652: no client-readable source carries them (BR-4, BR-18, DOCS). - One gap registry in BUSINESS-RULES; live session mounted only while the Session tab is open; no paging through truncated listings. - Cursor's below-bar notes recorded in PLAN -> Notes from review. The open fork (a turn into a running coding run) is unchanged. Re-draft: baseline 482 lines (merged set at 6c05e85) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Second look + architecture pass on the D1 amendmentVerdict: the direction is right. Stamping the link at the claim gate is leaner and more correct than the rebuilt-key lookup. I checked the premises against the code and they hold:
The points below are for the spec author to fold into the PLAN or the child issue's brief. None changes D1. 1. "Written inside a write the gate already makes" doesn't hold on the common path (PLAN → The task-run link)In
2. Name the link's lifetime (BR-3, BR-7)
3. Stale-link window on a retry is uncovered (BR-3 / BR-11)On attempt N+1,
The stamped 4. Inline-drained boards aren't addressedThe gate only exists for handed-off seats. Rows the drain runs inline execute in the drain's own session. There
Note (b) points to a simpler shape than "gate stamps on handed-off only". It's a child-issue call, but the PLAN should say which. 5. Architecture: don't grow a second, near-duplicate coordinate
PLAN already leaves "the name is that issue's to choose". This only asks that the shape be chosen deliberately. 6. Alternative considered: stamp from the parent at dispatchThe parent can compute the child session id (
Worth one line in "Considered and dropped", since it's the obvious counter-proposal. Smaller
Generated by Claude Code |
There was a problem hiding this comment.
Simplify review (spec amend)
Verdict: The amendment is the right direction. Replacing rebuilt-key / topic matching with a gate-stamped task-run link on the row is simpler at runtime (no listing, no guessing, abort targets the request the row names) and matches what the codebase already has: claimedBy is server-only and names the drain, not the run (hand-off.ts), and DevTool’s dispatch-run-links is explicitly best-effort—not a product source of truth.
Splitting the field into a small orchestration child under FIX-1649 adds coordination (frame + link + FIX-1664), but that cost buys correctness and keeps Core/Engine untouched. I would not revert to the merged draft’s lookup model.
Bundling harness / tokens / cost into one FIX-1652 gap (instead of dashes from an unshipped client read) is also a simplification: one registry row, no fake “not reported yet” UI.
What went further than necessary (spec shape, not architecture)
- Gap registry composer owner —
else FIX-1652on the turn/composer row conflicts with the open fork andDOCS.md(“a way to add your message…”). FIX-1652 owns inspect/metrics, not steering. See inline onBUSINESS-RULES.md. - Surface count — PLAN still lists S1–S10 while “Notes from review” already suggests merging to ~4–5 groups for the sequence. Consider folding for implementer clarity (keep V-ids).
- Duplication — D1’s gate-stamps-row story appears in SPEC, DECISIONS, PLAN, figures, and much of “Decided, not asked” repeats BRs. BRs + gap registry are canonical per your own note; trimming “Decided, not asked” to rationale-only would shrink the amend.
- Attempt on the link — clarify whether
attemptis required for Interrupt/inspector or mainly header/BR-7 display, so implementers don’t treat three ids as three lookup keys everywhere.
Performance / reuse (spec-level)
Good guardrails already: tab-gated useSession live, one-shot inspector reads, no listing pagination, kitchen-sink mirror without apps/ imports. Residual smells to pin at implementation time (not blockers): BR-8 still streams the full shared session and filters client-side; BR-22 “one board read” can still mean a large row set; “row updates when the link appears” should use FIX-1662’s push/subscription path, not a poll loop.
Skipped (larger than this amend)
- Resolving the open fork before merge (product gate).
- Exposing
claimedByto clients or a new transcript API (correctly rejected). - Merging FIX-1662 frame + task level (correctly dropped).
Recommendation: Fix the composer row in the gap registry (and align DOCS.md first table row if needed), then merge. I’m not requesting changes on the task-run link decision itself.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2b04ce19f5
ℹ️ 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".
|
|
||
| | | | | ||
| |---|---| | ||
| | **What it adds** | When a handed-off attempt passes the board's claim gate in its run session, the gate stamps the row with that attempt's run: the session id, the request id, and the attempt number. The next attempt replaces it | |
There was a problem hiding this comment.
Clear stale run links when claiming a new attempt
When a task is retried or reclaimed, the parent claim advances the row to attempt N+1 before the child reaches this gate; queued or external dispatch can delay that gate while attempt N's link remains stored. During that window S2 treats the stale link as current, so the page can show or try to interrupt the previous run instead of entering BR-3's “nothing is running” state. Clear the link atomically in the claim/reclaim write, or require its attempt number to match the row before using it.
Useful? React with 👍 / 👎.
| | S4 | `labs/app-lab` · Interrupt | The shipped abort route on S2's in-progress request; Esc binds to it; state drawn from the request record only | D2 BR-11 to BR-14 | | ||
| | S5 | `labs/app-lab` · the disabled acts | Hand off, reassign, Open PR, the composer and *also post*: disabled, each with its owner line as a prop | D2 BR-15 BR-16 ER-5 | | ||
| | S2 | `labs/app-lab` · the run | Read the run's session id, request id and attempt off the row's [task-run link](#the-task-run-link); no listing, no key rebuilt. No link per BR-3; owner-refused per BR-9. Hand the ids to S3, S4 and S7 | D1 BR-3 BR-5 BR-9 | | ||
| | S3 | `labs/app-lab` · Session | `useSession(runSession, { live: true })`, **mounted only while the Session tab is open**, over the registry item components FIX-1662 copied in; add any item component a harness run emits that `frame` didn't copy, by `fsdev ui add`, unedited. A shared session (BR-8) keeps only items stamped with this task's id, through the attribution helper the substrate and the UI already share, never a copy | D1 BR-5 to BR-8 BR-10 ER-6 | |
There was a problem hiding this comment.
Preserve collection identity when filtering shared sessions
When two boards use custom session policies that return the same key and both contain a task with the same ID, they can share one child session, but emitted items carry only the bare taskId. The existing attribution helper explicitly filters by that bare ID after establishing collection membership, so it cannot distinguish these tasks and will include the other board's items while BR-8 promises only this task's work. Carry collection identity in attribution, constrain which boards may share a session, or narrow the promise accordingly.
Useful? React with 👍 / 👎.
| - **Amendment after merge** (review on PR #2428, Codex): the run lookup by rebuilt key and | ||
| `topic` was ambiguous and couldn't serve a shared session, so D1 now reads a link the gate | ||
| stamps on the row, split out as the task-run link; and harness, tokens and cost had no | ||
| client-readable source, so they became a named gap. The goal, D2 and the open fork are | ||
| unchanged. |
There was a problem hiding this comment.
Add the required evolution record for this amendment
This explicitly replaces an approved D1 after the original spec merged, but the directory still has no EVOLUTION.md. The retained-spec contract in docs/contributing/orchestration.md:711-728 requires that file when an earlier design is amended, including the precise predecessor anchors, disposition, evidence, replacement, and compatibility consequences; scattering only a short summary through the rewritten documents loses that required lineage.
Useful? React with 👍 / 👎.


The problem
FIX-1664's approved spec (#2428) found a task's run by rebuilding its dispatch key and matching it against the session listing's
topic. Two Codex P1s on #2428, both checked against the code, show that doesn't hold:topicis display-only (docs/architecture/server-and-client.md). The run's session id also folds in the parent session and its lineage (deriveDispatchRunSessionId), so the same task drained from another conversation makes a second run with the same topic. A per-worker or custom session policy never produces the per-task key, so BR-8 couldn't be met. The task screen could show, or abort, another task's run.packages/claude-code/src/sdk/agent.ts), block outputs don't reach the client, and the harness manager's run record is deliberately not client-readable (packages/harness-manager/src/run-record.ts). The spec already rejects using the Lab'sstatusaction.What this does
@flow-state-dev/orchestration(Layer 2), split out as its own child of FIX-1649 under the epic's split trigger. FIX-1664 waits on it. Nothing changes in Core or Engine. A session shared across tasks shows only the items stamped with this task's id. The gate already marks the task scope, so every item a worker emits carries that stamp.BUSINESS-RULES.md. The BRs, PLAN S5, SPEC and DOCS point to it and no longer repeat owners.What's asked of you
Renewed direction approval for D1, because the direction changed after merge. The approved spec said "no FSD package changes". Now FIX-1664 depends on one small orchestration field that ships first as its own issue. If wrong: one field nobody else reads, and a later start for FIX-1664. The alternative risks showing or stopping the wrong run. The harness/tokens/cost gap was decided, not asked.
Not asked here: the open fork (send a turn into a running coding run) is unchanged and still waits on you.
Parts worth reviewing closely
DECISIONS.md→ D1, and PLAN → "The task-run link": the link must be client-visible, whereclaimedByis server-only. Reading the named session still passes the server's owner check (BR-9, BP-031).Links: original review #2428 · Codex r4140151826, r4140151831 · Cursor review 5360654361 · FIX-1664 · epic FIX-1649
Contract
main, underorchestration.md→ "Merging and amending a spec". spec(FIX-1664): App Lab task view: a task's session, diff, checks and inspector #2428 is not reopened or pushed to.specs/issues/FIX-1664/{SPEC,DECISIONS,BUSINESS-RULES,PLAN,DOCS}.md,figures/d1-run-session.svg,figures/what-changes.svg. No other issue's spec is touched.node scripts/validate-spec-folder.mjspasses, and both edited SVGs parse as XML.🤖 Generated with Claude Code
https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
Generated by Claude Code