Repository navigation
spec(FIX-1664): App Lab task view: a task's session, diff, checks and inspector - #2428
Conversation
… inspector The task level inside FIX-1662's frame: the Session is the task's own run session found by its dispatch key, Interrupt is the one shipped write, and every other act or value is a named gap. Open fork: no operation delivers a person's turn into a running coding run. 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 (direction only)Overall the shape is right: read-only except abort, gaps named with owners, no new engine API. One finding is above the bar. The rest is notes for the implementer. 1. S2's run lookup has no parent session to list under (above the bar, answers the "Reviewers · look here" question)
PLAN S2 says "list the assigned seat's dispatch runs". DECISIONS "Considered and dropped" rejects the parent-children route because the parent (the session that drained the board) "can't be learned by the client". Both can't hold. Either the seat's own session is the parent, in which case the drop reason is wrong and should be replaced by the real precondition, or it isn't, in which case S2 has no way to name the listing. Please settle this in the spec before approval, because V1 only proves the topic match once you already have a parent. Options, most to least preferred:
2. Filtering after listing can miss the run (same seam, BP-033)Even with a parent, 3. BR-8 needs the session policy, and the client may not know itTo tell "per-task" from "per-worker" or a custom 4. Architecture: don't grow a parallel run-lookup in the lab
5. Smaller notes (recorded for the implementer, no design round needed)
On the open forkRecommendation to file the turn operation as a child of FIX-1649 is sound, and building it inside this issue would be wrong for the reason given (attempt count, row and checkout are framework meaning). No objection. Generated by Claude Code |
There was a problem hiding this comment.
Summary
This is a spec-only PR for FIX-1664. I read the five documents plus figures and ran parallel simplify reviews (quality, performance, reuse).
Verdict: The product/engineering approach is the right one and is simpler than the alternatives the spec rejects (worker chat as Session, transcript API, shell hand-off/reassign, abort+cancel row). Day-one implementation is mostly: FIX-1662 frame + taskSessionKeyFor + list child dispatch runs by topic + useSession(..., { live: true }) + shipped abort + ER-5 disabled/empty props. No FSD churn is appropriate.
What went farther than necessary is mostly spec machinery, not runtime design: the same contract (watch run, stop run, name gaps) is repeated across SPEC, DECISIONS, BR-*, PLAN surfaces, DOCS, and figures. That matches epic ER-5 closure exhaustiveness, but it will drift unless consolidated.
I am not approving with APPROVE here because sign-off still depends on the open fork (file turn operation vs first-cut watch-only) and because a few plan gaps are worth tightening before implementers start—not because D1/D2 are wrong.
Did the approach go too far?
| Layer | Assessment |
|---|---|
| Decisions (D1, D2, rejected alts) | Tight. D1 (run session by dispatch key) and D2 (abort-only write) are the minimal honest story for ER-15. |
| Implementation sketch | Lean (~lookup, live session, interrupt, props). PLAN’s guardrails (single write, no optimistic interrupt, one live stream per open task) are correct. |
| Spec traceability (S1–S10, BR-1–BR-24, 4 decision SVGs + what-changes) | Heavy for a single labs/app-lab fill-the-frame issue. S1–S10 are a verification grid (like FIX-1661), not ten packages—but the sequence diagram reads like a multi-package epic. ~half the BRs restate “disabled + owner” for the full design screen, not only watch/stop. |
| Third-party packages | N/A (correctly uses shipped @flow-state-dev/react / core helpers; no custom SSE or transcript stack). |
Cleaner alternative (same behavior): Keep goal, D1, D2, open fork, goal check, and “considered and dropped.” Collapse one gap registry table (owner · UI location · day-one enabled) referenced by SPEC, BR-15–17/21, S5/S6, and DOCS “Not there yet.” Merge PLAN surfaces to ~4–5 (run resolution, task shell+tabs, interrupt+disabled matrix, inspector+--devtool, goal+docs). Move DECISIONS “Decided, not asked” into BR-only (or delete duplicate bullets). Tier BRs into core (BR-5/6/11/14 + goal) vs edge (BR-8/9/12/13/10) so SPEC front matter reads as watch+stop first.
Reuse (should stay explicit in PLAN): Mirror apps/kitchen-sink background-work-panel for Session body and picked-session-panel Composer/request settling for Interrupt truth—not imports from apps/. Use taskSessionKeyFor only; do not import devtool’s dispatch-run-links. Prefer FIX-1662 shared ER-5 primitives (NamedGap / disabled-with-owner) if frame ships them—otherwise flag 1662 so 1664 does not duplicate markup.
Performance / correctness notes (implement-time, not blockers)
- S2 list-then-filter is acknowledged as BP-033 follow-up; still add an at-implement-time note: child listing is paginated/newest-first—a busy seat can push the target
topicoff the first page (wrong/missing run or expensive paging). Policy: surface stale/truncated listing (childSessionsStale) with Retry; don’t silently scan offsets in App Lab. - Cache `(boardId, taskId) → run session + request id** for the open task; don’t re-list on tab switches.
- Lazy tabs: Consider mounting live
useSessiononly when Session is active if inspector can use one-shot reads from resolved ids—aligns “lazy tabs” with “one live stream per open task.” - BR-22 Blocks: Call out one board-level read (or row-embedded reverse deps)—avoid N+1 per dependency.
- BR-4 elapsed time: Derive from store/live subscriptions, not a standalone poll loop.
Skipped (needs product call, not simplify nits)
- Whether BR-8 (per-worker shared session disclosure) must ship in v1 for DevForce’s first board.
- Resolving the open fork (steering vs watch-only epic cut)—owner gate, not automation.
- Collapsing FIX-1664 into FIX-1662—already rejected in DECISIONS; epic scope.
What I did not ask for
- No new engine APIs in this issue (topic filter stays follow-up).
- No implementation in this PR (spec-only).
Direction is good; thinning the spec and hardening S2 pagination notes would make the change set easier to implement and review without changing what ships.
Sent by Cursor Automation: Review For Best Approach
| | ID | Where · role | Change | Rules | | ||
| |---|---|---|---| | ||
| | S1 | `labs/app-lab` · the task level | Fill FIX-1662's task route: header, the four tabs (lazy), the states of BR-2 and BR-3 | BR-1 to BR-4 | | ||
| | S2 | `labs/app-lab` · the run lookup | From board id and task id, derive the dispatch seam's per-task key with core's own helper (never re-spelled), list the assigned seat's dispatch runs, pick the one whose topic matches; hand its id and latest request id to S3 to S5. Owner-refused and shared-key cases per BR-8, BR-9 | D1 BR-5 BR-8 BR-9 | |
There was a problem hiding this comment.
Simplify / risk: List seat dispatch runs then pick topic === key is the right v1 seam (matches devtool pattern), but it is list-then-filter with paginated, newest-first child summaries. For a busy seat, the task’s run may not appear on the first page—silent wrong-session is worse than a named degraded state.
Recommend an at-implement-time bullet (not only Follow-ups): define behavior when the listing is truncated/stale (childSessionsStale / “more”), and forbid client-side offset scanning in App Lab. Keeps BP-033 follow-up honest without blocking this issue.
|
|
||
| | ID | Where · role | Change | Rules | | ||
| |---|---|---|---| | ||
| | S1 | `labs/app-lab` · the task level | Fill FIX-1662's task route: header, the four tabs (lazy), the states of BR-2 and BR-3 | BR-1 to BR-4 | |
There was a problem hiding this comment.
Simplify: S1–S10 are valuable as check IDs, but ten sequence nodes over-segment one route (resolve run → TaskView → goal/docs). Consider merging in the doc only: e.g. S2+S3+S4 as “run resolution + session + interrupt”, S5+S6 as “gaps + empty tabs”, S7+S8 as “inspector + devtool flag”—same V1–VG mapping, less DAG noise for implementers.
| **What would change my mind:** FIX-1651 shipping a hand-off that moves a row between seats. Then | ||
| the button calls it, with no change to the screen. | ||
|
|
||
| ## Decided, not asked |
There was a problem hiding this comment.
Simplify: This section largely duplicates BUSINESS-RULES §Tabs and inspector (Diff/Checks, Brief, plan/files, trace, @worker, post-interrupt board). Pick one home—I'd keep BR- as canonical* and leave DECISIONS for D1, D2, open fork, and rejected alternatives only—to reduce five-way drift.
| ## Tabs and the inspector | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| |
There was a problem hiding this comment.
Optional simplify: Hand off, reassign, and Open PR share the same day-one behavior (disabled, FIX-1651). Two buttons plus a third control add spec/CI surface without distinct logic—could be one disabled group + copy listing intents, unless the design requires separate affordances for closure photography.
| | A state changes on screen only when the store says so | *Interrupted* before the record says so is the shell's hope, not the run's answer | | ||
| | The run is found by the dispatch key, never by time, title or "latest session of this seat" | A near-miss shows another task's work as this one's, silently (D1) | | ||
| | Every gap's copy is a prop at the surface, naming its owner | The sibling fills it later without touching the surface (ER-5) | | ||
| | One live stream per open task; the inspector's recorded collections load once per open | A Lab with many running tasks must not open a stream per row | |
There was a problem hiding this comment.
Good guardrail. Worth pairing with PLAN sequence: defer mounting S3’s live stream until Session tab is active (if S7 can read plan/files from resolved ids without staying subscribed)—otherwise “lazy tabs” don’t buy much and you still pay item merge cost while user reads Brief/Diff.
| |---|---| | ||
| | **The real need** | The issue: *"see the worker actually doing it … steer it by sending a turn, interrupting it or handing it off, without leaving the app"*. The epic's leg a: a task's Session with the inspector beside it, and a message to a worker arriving as its turn ([FIX-1649](../../epics/FIX-1649/SPEC.md#the-goal-and-how-well-know-its-met)) | | ||
| | **Smaller, and rejected** | "The four tabs render." Met by a page of fixtures, or by showing the worker's chat instead of the run, which is where a person would be misled about what the task did | | ||
| | **Short of the need, and asked** | **Sending a turn.** Nothing ships that delivers a person's message into a running coding run, so this goal promises a disabled composer, not a working one. Whether to file that operation now is [the open fork](DECISIONS.md#open), and it is the hardest line on the sign-off | |
There was a problem hiding this comment.
Scope discipline here is strong (composer explicitly out of goal until fork resolves). When the fork is answered, update one gap registry (SPEC + BR-16 + DOCS table) in the same amend—dual owner strings (open fork vs FIX-1652) are easy to drift across five files today.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6c05e85a36
ℹ️ 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".
| | ID | Where · role | Change | Rules | | ||
| |---|---|---|---| | ||
| | S1 | `labs/app-lab` · the task level | Fill FIX-1662's task route: header, the four tabs (lazy), the states of BR-2 and BR-3 | BR-1 to BR-4 | | ||
| | S2 | `labs/app-lab` · the run lookup | From board id and task id, derive the dispatch seam's per-task key with core's own helper (never re-spelled), list the assigned seat's dispatch runs, pick the one whose topic matches; hand its id and latest request id to S3 to S5. Owner-refused and shared-key cases per BR-8, BR-9 | D1 BR-5 BR-8 BR-9 | |
There was a problem hiding this comment.
Use an authoritative task-to-run association
When the same board/task is dispatched from another coordinator session, this lookup is ambiguous: docs/architecture/server-and-client.md:227-230 defines topic as display-only, while deriveDispatchRunSessionId also incorporates the parent session and lineage, so distinct run sessions can share the same topic. It also cannot satisfy BR-8 because per-worker and arbitrary custom session policies do not produce the reconstructed per-task key. The task view can therefore show or abort the wrong run—or find none—so require a server-owned task-to-run association rather than matching the flat session listing by topic.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed against the code and fixed in the post-merge amendment #2434. topic is display-only, deriveDispatchRunSessionId folds in the parent session and lineage, and per-worker or custom policies never yield the per-task key. D1 no longer rebuilds a key. The board's claim gate runs in the run's own session on every handed-off attempt and stamps the row with that attempt's session id, request id and attempt number (the task-run link, in @flow-state-dev/orchestration, split out as its own child of FIX-1649). App Lab reads the run and the request to abort from the row. A shared session shows only the items stamped with this task's id. BR-3/5/7/8/11, PLAN S2 to S4 and V1, and the D1 and what-changes figures are updated.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
Generated by Claude Code
| | 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 | | ||
| | S6 | `labs/app-lab` · Diff, Checks, Brief | Two named empty states; Brief from the row | BR-17 BR-24 | | ||
| | S7 | `labs/app-lab` · the inspector | Fills the right panel's task slot: worker, team, harness, started, tokens, cost, acceptance gap, plan and files from the harness's recorded collections on the run session, linked, trace link | BR-18 to BR-23 | |
There was a problem hiding this comment.
Define a readable source for harness metrics
For handed-off coding runs, there is no client-readable source for the promised harness, token, and cost values: detached agents suppress the session-state run-handle log (packages/claude-code/src/sdk/agent.ts:142-169), block outputs are client-invisible trace items, and the harness manager persists these fields in a deliberately non-client-readable run record (packages/harness-manager/src/run-record.ts:149-175). Since DECISIONS.md:109 rejects using that record's Lab-specific status action, BR-18 cannot be implemented and the inspector will show dashes even when metrics were recorded; add a genuine public projection or classify these fields as a named gap.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed and fixed in the post-merge amendment #2434. A detached run suppresses the run-handle log, block outputs aren't client-visible, and the harness manager's run record is deliberately not client-readable. Harness, tokens and cost are now one named gap owned by FIX-1652 (BR-4, BR-18, DOCS "Not there yet"), listed in a single gap registry in BUSINESS-RULES. A public projection is recorded as FIX-1652's follow-up and not built here: it would be a second copy of the run record's numbers for three fields with no other consumer.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
Generated by Claude Code


Goal: a person opens one task in App Lab and watches that task's own run live, can stop it, and sees every other act and value the design draws either working from a shipped read or operation or saying what arrives and who ships it.
The check grades the screen against the run's stored session and request, never App Lab's own state. Check:
goals/app-lab/it-shows-and-stops-a-task-run/, scripted stub, controlsGOAL_CONTROL=worker-sessionandGOAL_CONTROL=optimistic-interrupt. Why this goal, and the part of the need it doesn't meet: SPEC.md.The top row is today's empty frame. The bottom is everything the task screen reads or writes: three shipped reads, one shipped write, and the gaps named where they sit.
How: a handed-off row runs in a child session keyed on its board and task, and the session listing already returns it. App Lab finds the run from the task alone, follows it live, and aborts its request on Interrupt. Nothing else writes.
Sign off
The goal, at that size: watch the run, stop it, a named gap for everything else, with the composer disabled until the fork below is answered. If wrong: the owner can't steer a run from the app, which is the issue's own problem.
Send a turn into a running coding run: file the operation now, or leave it out of this epic's first cut? · open, the one to weigh
@workerto a coding worker and an Inbox reply to a coding run.The Session tab is the task's own run, found by its dispatch key, shown live · D1
It comes down to truth about the task: the worker's chat can't say what this run did. If wrong: a Lab whose runs share one session per worker shows several tasks' steps under one task.
Of the four controls only Interrupt works; Hand off, reassign and Open PR are disabled and name FIX-1651 · D2
It comes down to the freeze: the board refuses to reassign a row it has handed off. If wrong: you expected hand-off on day one, and it needs a board rule changed first.
Open: one, above. Reasoning and what lost: DECISIONS.md. The cases: BUSINESS-RULES.md.
Reviewers · look here
Not here: the frame, routes and Tasks (FIX-1662) · the skin (FIX-1655) · what a hand-off, a check or acceptance means (FIX-1651).
Spec · Decisions · Rules · Plan · Docs · Linear FIX-1664 · epic FIX-1649 (#2421, retained at
specs/epics/FIX-1649/) · beside #2424 (FIX-1662) and #2425 (FIX-1655) · merges after human approval and required checks (contract)How to review this — altitude, what's in scope, what's deliberately unsettled
This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?
In scope to challenge:
SPEC.md— is the goal the real need at full size,for the people named, or a smaller goal that would let us call this done early? Would the
named check fail if the goal were not met?
docs/philosophy.md?DECISIONS.md— that's the sign-off surface.BUSINESS-RULES.mdmisses, or a rule that would invalidate the design.DOCS.mdand their fit with the rules; a missing ormisleading lineage claim in conditional
EVOLUTION.md.Out of scope — deliberately unsettled here, and owned by the implementing agent:
PLAN.mdpins on purpose.PLAN.mdleft open on purpose — it is directional by design, and a gap at thataltitude is intended, not an omission.
or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
decisions don't say is.
PLAN.mdmay include a rough pseudocode sketchshowing the shape of the proposed solution. It is knowingly incomplete, is not real code,
and is not what will ship. Review it for directional viability only. Do not report
that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
wouldn't build: all of that is true on purpose.
poc/are retained,not production code. Read them for directional evidence, not production completeness.
Their isolation from production/default discovery and absence of secrets or generated
dependencies are in scope; retention is not permission to weaken repository checks.
One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.
Feedback in the second list is welcome and gets recorded verbatim in
PLAN.md → Notes from reviewfor the implementer to weigh against real code. It will not be argued with, and itwill not be folded into the design prose. Please don't re-raise it: one mention is enough.
The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.
Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
Generated by Claude Code