Skip to content

spec(FIX-1664): amend task-to-run association and metrics source - #2434

Merged
jhoffner merged 1 commit into
mainfrom
spec/FIX-1664-amend
Sep 30, 2026
Merged

jhoffner merged 1 commit into
mainfrom
spec/FIX-1664-amend

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

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:

  • The lookup can pick the wrong run, or none. topic is 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.
  • Harness, tokens and cost have no source a client can read. A detached run keeps no session-state log of its handle (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's status action.

What this does

  • D1 now reads the run from the task's own row. The board's claim gate runs in the run's session on every handed-off attempt, whatever the session policy. It is the one place that knows the answer, so it stamps the row with that attempt's session id, request id and attempt number. This is the task-run link: a small field in @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.
  • Harness, tokens and cost become a named gap owned by FIX-1652 (BR-4, BR-18, DOCS "Not there yet"). A public projection for three fields with no second consumer isn't worth building ahead of FIX-1652's design for inspecting a run.
  • One gap registry in BUSINESS-RULES.md. The BRs, PLAN S5, SPEC and DOCS point to it and no longer repeat owners.
  • The live session mounts only while the Session tab is open. A truncated listing shows more than shown with Retry, and App Lab never pages through a listing to find something.
flowchart LR
  G["claim gate · in the run's session"] -->|"stamps session, request, attempt"| T["task row"]
  T --> S["Session · live while open"]
  T --> X["Interrupt · abort that request"]
  T --> I["inspector · recorded plan, files"]
Loading

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, where claimedBy is server-only. Reading the named session still passes the server's owner check (BR-9, BP-031).
  • BR-7: the link names only the current attempt's run. An earlier attempt that ran in a different session isn't shown. A history is recorded as a follow-up.

Links: original review #2428 · Codex r4140151826, r4140151831 · Cursor review 5360654361 · FIX-1664 · epic FIX-1649

Contract
  • Post-merge amendment on a new branch from main, under orchestration.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.
  • Files: 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.
  • Cursor review items taken: truncated-listing rule, lazy live session, one gap registry. Below-bar items are in PLAN → Notes from review.
  • node scripts/validate-spec-folder.mjs passes, and both edited SVGs parse as XML.
  • No changeset: spec only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq


Generated by Claude Code

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
@vercel

vercel Bot commented Sep 30, 2026

Copy link
Copy Markdown

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

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 30, 2026 4:51pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 30, 2026 4:51pm UTC
flow-state-dev-ui Ignored Ignored Sep 30, 2026 4:51pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 30, 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-09-30T17:02:13.216719Z 2b04ce1 PR opened
ℹ️ 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.

@linear-code

linear-code Bot commented Sep 30, 2026

Copy link
Copy Markdown

FIX-1664

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass on the D1 amendment

Verdict: 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:

  • claimedBy is server-only (SERVER_ONLY_TASK_FIELDS = ["claimedBy"], tasks/collection/change-event.ts:91).
  • claimedBy names the drain's session, not the run's. hand-off.ts:189-196 says so: the child never claims.
  • The gate runs in the run's session and calls ctx._markTaskScope (task-board/task-entry.ts:286).
  • A new Task field is client-visible by default, because redaction is a deny-list. So "client-visible, unlike claimedBy" needs no extra work. It also means the child issue must make a deliberate call on it.

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 createTaskGate, the only row write before the worker starts is adoptLapsedLease, and that runs only when the lease has lapsed. Otherwise the gate does patchState({ currentClaim }), _markTaskScope, and starts the renewal driver, which writes on a later tick. So the stamp will usually be a new ticket-fenced row write per handed-off attempt.

  • It should run before the worker step. A stamp that fails or is declined should be a stale-claim refusal (the existing StaleTaskClaimError path), not a silent miss.
  • It adds one write and one task-change emission per attempt.
  • Suggest rewording to "a ticket-fenced write before the worker step, refused like the start gate's other arms". As written, an implementer can't follow "where one fits" on the usual path.

2. Name the link's lifetime (BR-3, BR-7)

claimedBy is "cleared wherever the claim ends" (schema/task.ts). This link must be the opposite: it survives settle, park, error and reclaim, because the screen exists to show finished runs. The next attempt replaces it. The spec says "the next attempt replaces it" but never says "settle doesn't clear it". An implementer copying the claimedBy precedent will clear it.

3. Stale-link window on a retry is uncovered (BR-3 / BR-11)

On attempt N+1, row.attempts advances at claim. The gate stamps only when the child run starts. Until then the link still names attempt N, which has finished. BR-3 covers "never claimed / not yet started", but not "link.attempt < row.attempts". In that window:

  • the screen shows the previous run as if it were current, and
  • Interrupt would abort attempt N's finished request.

The stamped attempt number is what lets the screen detect this. Add a rule: if link.attempt !== row.attempts, treat it as "starting", disable Interrupt, and label the Session as the previous attempt.

4. Inline-drained boards aren't addressed

The gate only exists for handed-off seats. Rows the drain runs inline execute in the drain's own session. There claimedBy is exactly the run's coordinate, but it is server-only and the link is never stamped. BR-3 lumps these rows into "no run started", so the screen would say no run has started for a task that is running or finished. Two options:

  • (a) scope the task screen to handed-off boards and give inline rows their own named state, or
  • (b) have the claim write (applyClaimToTask) stamp the same link on the inline path, so one client-visible field serves both.

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

claimedBy {sessionId, requestId, tenantId?} and the new link {session, request, attempt} are the same idea. One is redacted and one isn't. If the child issue defines an unrelated third shape, the row carries two execution coordinates with different clear/replace rules (see #2) that nobody can tell apart. Suggest the child spec:

  • reuses the claimedBy object schema (plus attempt) under a name that says run, and
  • puts both lifetimes in one comment block, as claimedBy's block already does for assignee.

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 dispatch

The parent can compute the child session id (deriveDispatchRunSessionId). It could record it in the claim write, which avoids a new gate write and closes the "handed off, not yet started" gap. I'd still stay with the gate, for two reasons:

  • I didn't find the child request id available to the parent at dispatch, and Interrupt needs it.
  • The gate is the only writer that sees a dispatch that actually ran.

Worth one line in "Considered and dropped", since it's the obvious counter-proposal.

Smaller

  • PLAN/S2 says "no link per BR-3; owner-refused per BR-9" but V1 doesn't test the stale-link window from Infer resource state types in projections and add portable projection resource schema options #3. Add a case.
  • The PR's "Nothing changes in Core or Engine" is true for the field. The taskId stamp is collection-ambiguous on its own (task-attribution.ts uses scope-marker items to disambiguate). S3 already says to use the shared attribution helper, which is correct, so keep it there.
  • No restraint concerns: the gap registry consolidation is a net simplification.

Generated by Claude Code

@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 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)

  1. Gap registry composer owner — else FIX-1652 on the turn/composer row conflicts with the open fork and DOCS.md (“a way to add your message…”). FIX-1652 owns inspect/metrics, not steering. See inline on BUSINESS-RULES.md.
  2. 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).
  3. 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.
  4. Attempt on the link — clarify whether attempt is 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 claimedBy to 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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1664/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1664/PLAN.md Resolved
Comment thread specs/issues/FIX-1664/PLAN.md Resolved
Comment thread specs/issues/FIX-1664/DECISIONS.md Resolved
Comment thread specs/issues/FIX-1664/PLAN.md Resolved
Comment thread specs/issues/FIX-1664/SPEC.md Resolved
@jhoffner
jhoffner merged commit 0a5ded8 into main Sep 30, 2026
15 checks passed

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 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 |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge 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 |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge 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 👍 / 👎.

Comment on lines +131 to +135
- **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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge 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 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants