diff --git a/specs/issues/FIX-1664/BUSINESS-RULES.md b/specs/issues/FIX-1664/BUSINESS-RULES.md
index 373c051354..db5f788a30 100644
--- a/specs/issues/FIX-1664/BUSINESS-RULES.md
+++ b/specs/issues/FIX-1664/BUSINESS-RULES.md
@@ -12,17 +12,17 @@ names the kind of check the plan runs.
|---|---|---|---|
| BR-1 | A task is opened from Tasks, a board card, or a workstream's task list | FIX-1662's task route shows this issue's header, the four tabs and the inspector in the right panel's slot; the tab is in the URL | Goal check |
| BR-2 | The route names a board or task the Lab doesn't hold | A named state saying no such task on that board; no other read is made | CI |
-| BR-3 | The task has never been claimed | Session says the task hasn't started; Interrupt is disabled with *nothing is running*; the inspector shows the row's fields and dashes | CI |
-| BR-4 | The header renders | Title (or goal), the row's status word, elapsed time from the row's start while it runs, the worker, and the harness per BR-18. No branch | Goal check |
+| BR-3 | The row names no run: never claimed, handed off but not yet started in its session, or stored before the [task-run link](PLAN.md#the-task-run-link) existed | Session says no run has started for this task; Interrupt is disabled with *nothing is running*; the inspector shows the row's fields. The screen updates when the row does; it never looks for a run any other way | CI |
+| BR-4 | The header renders | Title (or goal), the row's status word, elapsed time from the row's start while it runs, and the worker. No harness (a gap, BR-18) and no branch | Goal check |
## The Session
| # | When | Then | Proved by |
|---|---|---|---|
-| BR-5 | The task has a run | The Session is the items of the child session keyed on this board and this task, in stored order, drawn by the registry components; one live stream for it while the tab is open | Goal check under `worker-session` |
+| BR-5 | The row names a run | The Session is the items of the session the row's link names, in stored order, drawn by the registry components; one live stream for it, open only while the Session tab is | Goal check under `worker-session` |
| BR-6 | The run stores a new item | It appears with no reload | Goal check |
-| BR-7 | The task ran more than once | Every attempt's items, in order, in the one session | CI |
-| BR-8 | The board's seat keys sessions per worker or by a custom key | The Session shows that shared session whole, with a line saying it holds other tasks' work too; it never filters by guess | CI |
+| BR-7 | The task ran more than once | Every attempt the named session holds, in order. An earlier attempt that ran in another session (a re-drain from another conversation, or a custom key) isn't shown; the header says which attempt is showing | CI |
+| BR-8 | The named session is shared with other tasks (a per-worker or custom session policy) | The Session shows only the items stamped with this task's id, with a line saying the session is shared. It never shows the whole session as this task's, and never filters by time or order | CI |
| BR-9 | The run's session exists but the caller's principal can't reach it | A named state saying the run isn't visible to this user; no fallback to another session | CI |
| BR-10 | The row is parked | The Session shows the log and the row's reason; the ask is answered from Inbox (FIX-1662), and the task screen links there | CI |
@@ -30,32 +30,51 @@ names the kind of check the plan runs.
| # | When | Then | Proved by |
|---|---|---|---|
-| BR-11 | Interrupt is pressed, or Esc with the Session focused | The run's in-progress request gets the shipped abort. The view shows *interrupted* only after that request reads `aborted` | Goal check under `optimistic-interrupt` |
+| BR-11 | Interrupt is pressed, or Esc with the Session focused | The request the row's link names gets the shipped abort. The view shows *interrupted* only after that request reads `aborted` | Goal check under `optimistic-interrupt` |
| BR-12 | The abort answers that the request already finished | The view refreshes to what the request and row say; nothing is drawn as interrupted | CI |
| BR-13 | The abort is refused or fails | The error shows by the button; the run is drawn as still running | CI |
| BR-14 | The run was interrupted | App Lab writes nothing to the row; its next status is whatever the board records | CI |
-| BR-15 | Hand off, reassign or Open PR is shown | Disabled, with a line naming FIX-1651 and what arrives | CI |
-| BR-16 | The composer is shown | Disabled, with a line naming the operation from [the open fork](DECISIONS.md#open), or FIX-1652 if the fork goes the other way. *Also post to the workstream* is disabled with it | CI |
+| BR-15 | Hand off, reassign or Open PR is shown | Disabled, with a line naming what arrives and its owner from the [registry](#gap-registry) | CI |
+| BR-16 | The composer is shown | Disabled, with its owner line from the [registry](#gap-registry), which follows [the open fork](DECISIONS.md#open). *Also post to the workstream* is disabled with it | CI |
## Tabs and the inspector
| # | When | Then | Proved by |
|---|---|---|---|
-| BR-17 | Diff or Checks opens | A named empty state naming FIX-1651; the tab label carries no count | CI |
-| BR-18 | The inspector renders | Worker and team from the inventory; harness from the run's reported handle, else a dash naming FIX-1652; started from the row; tokens and cost from the reported handle, else a dash, with *estimated* when the harness estimated | Goal check |
+| BR-17 | Diff or Checks opens | A named empty state with its owner from the [registry](#gap-registry); the tab label carries no count | CI |
+| BR-18 | The inspector renders | Worker and team from the inventory; started from the row. Harness, tokens and cost are one named gap ([registry](#gap-registry)): no shipped read gives a client what the run reported | Goal check |
| BR-19 | The run recorded a plan or file operations | The plan lists its steps with their status; files list path and created or edited | CI, against a seeded record |
-| BR-20 | The run recorded neither | Each section says this harness records none | Goal check (the stub records none) |
-| BR-21 | Acceptance criteria and *review by* render | Named gaps naming FIX-1651 | CI |
+| BR-20 | The run recorded neither | Each section says this harness records none ([registry](#gap-registry)) | Goal check (the stub records none) |
+| BR-21 | Acceptance criteria and *review by* render | Named gaps, owners from the [registry](#gap-registry) | CI |
| BR-22 | Linked renders | *After*: the row's dependencies. *Blocks*: rows on the same board that depend on it. Each opens its task | CI |
| BR-23 | The trace link is shown | It opens the devtool App Lab was started with, with the run's session id beside it; with no devtool given, it is disabled and says how to start one | CI |
| BR-24 | Brief opens | The row's title, goal, context and input, as stored; acceptance criteria per BR-21 | CI |
+
+## Gap registry
+
+**The one place each gap's owner is written.** Every disabled control, empty tab and empty
+field on the task screen takes its owner line from this table, as a prop at the surface (ER-5);
+SPEC, PLAN and DOCS point here rather than repeat it. When a gap's owner ships, or the open fork
+is answered, this table changes and the rest follows.
+
+| Gap on the task screen | Day one | Owner | Rules |
+|---|---|---|---|
+| Typing to the worker, and *also post to the workstream* | Disabled composer | The operation from [the open fork](DECISIONS.md#open) if filed, else FIX-1652 | BR-16 |
+| Hand off, reassign, Open PR | Disabled | FIX-1651 | BR-15 |
+| Diff, Checks | Empty tab, no count | FIX-1651 | BR-17 |
+| Acceptance criteria, *review by* | Empty section | FIX-1651 | BR-21, BR-24 |
+| Harness, tokens, cost | Empty field | FIX-1652 | BR-4, BR-18 |
+| A harness that records no plan or files | A line saying so | FIX-1652 | BR-20 |
+
## Failure taxonomy
-Nothing on the task screen is fatal. The row read failing shows the route's Retry; the run
-lookup, the stream and each recorded collection failing degrade only their own tab or section
-to Retry. Nothing retries on its own, and nothing is drawn from a guess or from App Lab's hope:
-a state changes on screen when the store says it changed.
+Nothing on the task screen is fatal. The row read failing shows the route's Retry; the
+session read, the stream and each recorded collection failing degrade only their own tab or
+section to Retry. A read that answers with a truncated page says *more than shown* with Retry;
+App Lab never pages through a listing to find something. Nothing retries on its own, and
+nothing is drawn from a guess or from App Lab's hope: a state changes on screen when the store
+says it changed.
## Acceptance criteria this issue owns
diff --git a/specs/issues/FIX-1664/DECISIONS.md b/specs/issues/FIX-1664/DECISIONS.md
index 8cd16b0142..b3729f1046 100644
--- a/specs/issues/FIX-1664/DECISIONS.md
+++ b/specs/issues/FIX-1664/DECISIONS.md
@@ -9,8 +9,9 @@ Two decisions and one open fork are the sign-off surface. The epic's D1 to D3 an
```mermaid
flowchart TD
- I["FIX-1664"] --> D1["D1 · Session is the task's own run session"]
+ I["FIX-1664"] --> D1["D1 · Session is the run the task's row names"]
D1 -.->|"rejected · a chat, not the task"| X1["the worker's own conversation"]
+ D1 -.->|"rejected · display-only, ambiguous"| X1c["match the listing's topic to a rebuilt key"]
D1 -.->|"rejected · a new read in the engine"| X1b["a task transcript API"]
I --> D2["D2 · only Interrupt works"]
D2 -.->|"rejected · the board refuses it"| X2["reassign through the board's action"]
@@ -54,20 +55,24 @@ out when you needed it means the issue's first sentence, steer without a termina
It comes down to steering: without the operation, the task screen watches and stops, nothing more.
-## D1 · The Session tab is the task's own run session, found by its dispatch key, shown live
+## D1 · The Session tab is the run the task's own row names, shown live
| | |
|---|---|
-| **Instead of** | The assigned worker's own conversation session · a new "task transcript" read in the engine |
-| **Because** | A handed-off row runs in a child session the dispatch seam keys on the board and the task, and the session listing already returns dispatch runs with that key. Reading it is reading what ships (ER-5), and the live stream FIX-1609 shipped (`useSession` with `live`) follows it with no reload. The worker's own conversation is where it talks, not where this task ran. A transcript read would be a second API over the item log, which the Architect named an invent-kill |
-| **Locks in** | A task's screen is exactly one run's session. Every attempt of the task is in it, in order, because a per-task key re-enters the same child. A board whose seat uses a per-worker or custom session key shares one session across tasks; its Session tab says so rather than filtering by guess |
+| **Instead of** | The assigned worker's own conversation session · rebuilding the dispatch key and matching it against the session listing's `topic` · a new "task transcript" read in the engine |
+| **Because** | Only the run itself knows, for certain, which session it is in. A handed-off attempt enters its run session through the board's claim gate, whatever the seat's session policy and whichever conversation drained the board, so the gate is the one place that can write down *this task's attempt N is running in session S, request R*. Rebuilding the key from outside can't do that: the listing's `topic` is display-only, the run's session id also folds in the parent session and its lineage (so a re-drain from another conversation makes a second run with the same topic), and a per-worker or custom policy never produces a per-task key at all. So the association is **a small new field on the task row, stamped by the gate** in `@flow-state-dev/orchestration` (Layer 2, the substrate that already owns the row and the gate), filed as its own child of FIX-1649 under the epic's split trigger: [the task-run link](PLAN.md#the-task-run-link). The row already reaches App Lab through FIX-1662's board read, so the link arrives with it; the live stream FIX-1609 shipped (`useSession` with `live`) follows the session with no reload. The worker's own conversation is where it talks, not where this task ran. A transcript read would be a second API over the item log, which the Architect named an invent-kill |
+| **Locks in** | A task's screen is the run its row names, and Interrupt aborts the request the row names. A session shared across tasks (a per-worker or custom policy) shows only the items stamped with this task's id, which every item a task's worker emits carries from the moment the gate marks the scope; the screen says the session is shared. **FIX-1664's build waits on the task-run link**; nothing in Core or Engine changes |
-
+
-It comes down to truth about the task: the worker's chat can't say what this run did.
+It comes down to truth about the task: only the run can say where it ran, so the run writes it down.
**What would change my mind:** FIX-1651 defining a task as something other than a board row a
-seat runs. Then the key moves, and the tab stays.
+seat runs. Then the link moves to whatever it runs, and the tab stays.
+
+**If wrong:** one small orchestration field nobody else reads, and FIX-1664 a child issue later
+than it would otherwise be. Getting the lookup wrong instead shows another task's work, or
+aborts another task's run, as this one's.
## D2 · Of the four controls only Interrupt works; Hand off, reassign and Open PR are disabled and name FIX-1651
@@ -92,8 +97,12 @@ the button calls it, with no change to the screen.
- **Brief is the row's own fields**; acceptance criteria are a named gap (FIX-1651).
- **The plan and files are what the harness recorded** on the run session (Claude Code records
both), else a line saying this harness records none. Files show created or edited, no line counts.
-- **Started is the row's; tokens, cost and harness come from the run's reported handle**, a dash
- until then, as FIX-1662's BR-7 draws harness. **Branch** has no client read and is omitted.
+- **Started is the row's. Harness, tokens and cost are a named gap owned by FIX-1652.** The
+ run reports them in its return value, which the client never sees; a detached run keeps no
+ session-state log of it; and the harness manager's run record, which does hold them, is
+ deliberately not client-readable. No shipped read carries them, so the inspector says so
+ rather than drawing a dash that looks like *not reported yet* ([the gap registry](BUSINESS-RULES.md#gap-registry)).
+ **Branch** has no client read and is omitted.
- **Linked** is the row's dependencies and its dependents; *review by* names FIX-1651.
- **The trace link opens the devtool App Lab was started with** (`--devtool `), with the
run's session id beside it: the devtool can't open a session from its address yet.
@@ -106,8 +115,11 @@ the button calls it, with no change to the screen.
| Alternative | Why not |
|---|---|
-| Find the run through the harness manager's run record | Not client-readable by design; its read surface is a lab's own `status` action |
+| Find the run through the harness manager's run record | Not client-readable by design; its read surface is a lab's own `status` action. It also covers only boards the harness manager runs, and keys by the lab's own topic, not board and task |
| Find the run through its parent session's children | The parent is the session that drained the board, which the client can't learn: the row's claim coordinate is server-only |
+| Rebuild the dispatch key and match the session listing's `topic` (the approved draft) | `topic` is display-only; the run's id also folds in the parent session and lineage, so two runs can share a topic; a per-worker or custom policy never yields the per-task key. It can show or abort the wrong run, or find none |
+| Expose the row's claim coordinate (`claimedBy`) | Server-only by design, and it names the session that **claimed** the row, which on a handed-off board is the drain's, not the run's: the child never claims |
+| Publish the harness's tokens and cost through a new projection now | A second read of the same numbers, for three inspector fields, with no second consumer. FIX-1652 owns inspecting a run and can shape it once |
| Cancel the row as well as abort the run on Interrupt | A shell-written board change; what an interrupted row becomes is FIX-1651's |
| Fold the task level back into FIX-1662 (epic D1's mind-changer) | It reads a run session, a harness's records and a request, none of which the workstream level reads |
@@ -116,5 +128,10 @@ the button calls it, with no change to the screen.
- **Draft**: framed as watching and steering one run; the Session reads the task's own run
session; only Interrupt ships; the turn into a coding run found unshipped and put as the open
fork.
+- **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.
**Open: one** — [above](#open).
diff --git a/specs/issues/FIX-1664/DOCS.md b/specs/issues/FIX-1664/DOCS.md
index 2f0643723c..15d6763211 100644
--- a/specs/issues/FIX-1664/DOCS.md
+++ b/specs/issues/FIX-1664/DOCS.md
@@ -20,15 +20,17 @@ below, which differ from the epic's draft because the composer and Hand off don'
> ## A task
>
> Open a task from Tasks or from a card on a board. The Session tab is that task's own run:
-> every step the worker takes, the tool calls and edits as they happen, and every earlier
-> attempt above them. It isn't the worker's chat, so what you read is what this task did.
+> every step the worker takes, the tool calls and edits as they happen, and earlier attempts
+> above them when they ran in the same place. It isn't the worker's chat, so what you read is
+> what this task did. If the worker keeps one session for several tasks, the tab shows only
+> this task's steps and says the session is shared.
>
> **Interrupt** stops the run (Esc does the same). The screen says *interrupted* once the run
> has actually stopped. What happens to the task afterwards, whether it's retried or left, is up
> to the board, not App Lab.
>
-> The panel on the right shows who is on it, which harness, when it started, and tokens and
-> cost once the run reports them. If the harness records its plan and the files it touched, as
+> The panel on the right shows who is on it and when it started. If the harness records its
+> plan and the files it touched, as
> Claude Code does, they're listed; otherwise the panel says so. *Open trace* opens the devtool
> for the full detail. Tell App Lab where it runs:
>
@@ -47,13 +49,14 @@ below, which differ from the epic's draft because the composer and Hand off don'
> | Hand off, reassign, Open PR | Disabled | The eng workstream kit |
> | Diff and Checks | An empty tab saying so | The eng workstream kit |
> | Acceptance criteria, who reviews | An empty section | The eng workstream kit |
+> | Which harness, tokens and cost | An empty field saying so | Attention and inspect |
> | A harness that records no plan | A line saying so | Attention and inspect |
>
> A board that hands work off keeps each task on the worker it was given to, which is why
> reassigning is off rather than refused.
-The first row's *Filled in by* follows the open fork: the operation's issue by name if it is
-filed, attention and inspect if not.
+The table mirrors the [gap registry](BUSINESS-RULES.md#gap-registry), which is canonical; the
+first row's *Filled in by* follows the open fork there.
## Voice watch-outs for the publisher
diff --git a/specs/issues/FIX-1664/PLAN.md b/specs/issues/FIX-1664/PLAN.md
index a5173a71d1..805cb99d0e 100644
--- a/specs/issues/FIX-1664/PLAN.md
+++ b/specs/issues/FIX-1664/PLAN.md
@@ -4,20 +4,34 @@
Written for the implementing agent. IDs cross-reference [BUSINESS-RULES.md](BUSINESS-RULES.md)
(BR-n), [DECISIONS.md](DECISIONS.md) (D-n) and the epic's rules (ER-n). `tdd`. One PR, branched
-after FIX-1662's `frame` PR merges; it uses that PR's route, panel slot, shared reads and
-registry copies.
+after FIX-1662's `frame` PR **and [the task-run link](#the-task-run-link)** merge; it uses the
+frame's route, panel slot, shared reads and registry copies, and the link on the row.
+
+## The task-run link
+
+**A dependency, filed as its own child of FIX-1649, not built here** (D1; the epic's split
+trigger: a level that needs a read nothing ships splits it out). It is small and lives in
+`@flow-state-dev/orchestration`, the Layer 2 substrate that owns the row and the claim gate.
+Nothing in Core or Engine changes (ER-7).
+
+| | |
+|---|---|
+| **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 |
+| **Why there** | The gate runs in the run's own session for every handed-off attempt, whatever the seat's session policy and whichever conversation drained the board, so it is the one writer that knows the answer rather than rebuilding it |
+| **Its rules** | Server-written only, absent from the fields a caller or model can set, like `claimedBy`. Client-visible, unlike `claimedBy`: it names a session, and reading that session still passes the server's owner check (BR-9, BP-031). Optional and `== null`-guarded, so rows stored before it read as *no run linked* (BP-030, BR-3). Written inside a write the gate already makes where one fits, never a second write that can fail after the run starts |
+| **What FIX-1664 needs from it** | The field on the row FIX-1662's board read returns, and its three values. The name is that issue's to choose |
## Surfaces
| 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 |
-| S3 | `labs/app-lab` · Session | `useSession(runSession, { live: true })` 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 | D1 BR-5 to BR-7 BR-10 ER-6 |
-| 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 |
+| S4 | `labs/app-lab` · Interrupt | The shipped abort route on the request S2 read; 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, from the [gap registry](BUSINESS-RULES.md#gap-registry) | 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 |
+| S7 | `labs/app-lab` · the inspector | Fills the right panel's task slot: worker, team, started, the harness-tokens-cost gap, acceptance gap, plan and files from the harness's recorded collections on the run session under S2's request id (one-shot reads, loaded once per open, no stream), linked, trace link | BR-18 to BR-23 |
| S8 | `labs/app-lab` · start script | Optional `--devtool `, passed to the page for S7's link | BR-23 |
| S9 | `goals/app-lab/it-shows-and-stops-a-task-run/` | The goal check, both controls, and its input tree ([at implement time](#at-implement-time)) | the goal |
| S10 | Docs | [DOCS.md](DOCS.md): the README's task sentences and task section | ER-14 |
@@ -30,6 +44,7 @@ for the live session's shape and imports nothing from `apps/`.
```mermaid
flowchart TD
F["FIX-1662 frame · merged"] --> S1["S1 · task level"]
+ L["the task-run link · merged"] --> S2
S1 --> S2["S2 · run lookup"]
S2 --> S3["S3 · Session"]
S2 --> S4["S4 · Interrupt"]
@@ -50,11 +65,11 @@ operation is a later, separate PR after it merges, not part of this DAG.
| ID | Runs after | Passes when |
|---|---|---|
-| V1 | S2 | Per-task key finds exactly the run's child session among several; per-worker key yields the shared case (BR-8); an unreachable session yields BR-9. Negative: with the key match removed, the test picks the wrong session and fails |
+| V1 | S2, S3 | The screen opens the session and request the row's link names, among several sessions of the same seat and a second run with the same board and task drained from another conversation; a row with no link yields BR-3; an unreachable session yields BR-9; a shared session shows only this task's stamped items (BR-8). Negative: reading the seat's latest session instead of the link picks the wrong one and fails |
| V2 | S3 | Items render in stored order across two attempts (BR-7); a stored item appears live (BR-6); parked shows the reason and the Inbox link (BR-10) |
| V3 | S4 | Abort is called with the in-progress request id; *interrupted* renders only after the record reads `aborted` (BR-11); 409 and refusal paths (BR-12, BR-13); no board write on any path (BR-14) |
| V4 | S5, S6 | Every disabled control and empty tab carries its owner line (BR-15 to BR-17) |
-| V5 | S7 | BR-18 dashes before a handle, values after; *estimated* on an estimated cost; BR-19 against a seeded recorded plan and file-op rows; BR-20 with none; BR-22 both directions; BR-23 with and without `--devtool` |
+| V5 | S7 | BR-18's gap line with its registry owner, whatever the run reported; BR-19 against a seeded recorded plan and file-op rows; BR-20 with none; BR-22 both directions; BR-23 with and without `--devtool` |
| V6 | S1 to S8 | Static: no literal colour outside token definitions; no tree name in `labs/app-lab/src`; registry copies byte-equal their source; no write call except the abort |
| VG | S9 | [The goal](SPEC.md#the-goal-and-how-well-know-its-met) PASSES, after `GOAL_CONTROL=worker-session` and `GOAL_CONTROL=optimistic-interrupt` each FAILED at their named signal |
@@ -75,9 +90,10 @@ Everything else is yours to name.
|---|---|
| The abort is the only write this screen makes | ER-15; D2. Anything else is a model the shell invented |
| 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 |
+| The run is the one the row's link names, never found by key, topic, time, title or "latest session of this seat" | A near-miss shows, or aborts, another task's run as this one's, silently (D1) |
+| Every gap's copy is a prop at the surface, naming its owner from the [gap registry](BUSINESS-RULES.md#gap-registry) | The sibling fills it later without touching the surface (ER-5), and one table changes when it does |
+| At most one live stream, and only while the Session tab is open; the inspector's recorded collections load once per open | A Lab with many running tasks must not open a stream per row, and a person reading Brief pays nothing for the Session |
+| No paging through a listing to find something; a truncated answer shows *more than shown* with Retry | A silent wrong answer is worse than a named partial one |
| No FSD package changes; a part that won't take the skin goes to FIX-1655 | ER-2, ER-6 |
## Docs
@@ -90,17 +106,21 @@ Reconcile [DOCS.md](DOCS.md) against the running app and publish it in this PR,
```
open task(board, id):
row ← FIX-1662's board read
- key ← the dispatch seam's per-task key(board, id)
- run ← the assigned seat's dispatch runs, where topic = key (D1)
- session ← live items of run (Session)
- inspector← row fields + run's recorded plan and files + reported handle
-interrupt: abort(run's in-progress request) → wait for the record → redraw (D2)
-everything else: disabled or empty, with its owner's line
+ run ← row's task-run link: { session, request, attempt } (D1; none → BR-3)
+ session ← live items of run.session, while the Session tab is open (Session)
+ shared session → only items stamped with id (BR-8)
+ inspector← row fields + recorded plan and files under run.request
+interrupt: abort(run.request) → wait for the record → redraw (D2)
+everything else: disabled or empty, with its owner's line from the gap registry
```
-**POC:** none. The premises are read off code, not argued: the per-task key and the topic on the
-listing (`packages/core/src/types/dispatch.ts`, the session record's `topic`), the assignee
-freeze on a handed-off board (`define-task-collection.ts`), the abort route
+**POC:** none. The premises are read off code, not argued: the claim gate runs in the run's
+own session on every handed-off attempt and marks the task scope, so every item the worker emits
+carries the task's id (`packages/orchestration/src/task-board/task-entry.ts`,
+`packages/contracts/src/items/task-attribution.ts`); the row's claim coordinate is server-only
+and names the drain, not the run (`tasks/schema/task.ts`, `task-board/hand-off.ts`); the recorded
+plan and files are keyed by the run's request id (`packages/claude-code/src/sdk/agent.ts`); the
+assignee freeze on a handed-off board (`define-task-collection.ts`); the abort route
(`packages/engine/src/routes/abort-routes.ts`). V1 and V3 exercise them first.
## At implement time
@@ -110,15 +130,40 @@ freeze on a handed-off board (`define-task-collection.ts`), the abort route
then, use DevForce; otherwise S9 carries a small fixture tree built from DevForce's kinds, and
the stub gains a hold-until-aborted script.
- Re-read FIX-1662's merged spec and `frame` PR for the route, slot and shared-read names.
-- Confirm the session listing still returns dispatch runs with `topic` and `latestRequestId`, and
- what the board does with an aborted attempt. If it re-queues and restarts, report that to
- FIX-1651 as what an interrupt means for a row; don't cancel from the shell.
-- Check whether FIX-1651 or FIX-1652 shipped anything; a shipped read replaces its gap.
+- Read the task-run link's merged spec for the field's name and shape, and confirm FIX-1662's
+ board read returns it.
+- Confirm what the board does with an aborted attempt. If it re-queues and restarts, report that
+ to FIX-1651 as what an interrupt means for a row; don't cancel from the shell.
+- Any listing the screen still reads (the recorded plan and files, the board's rows for *Blocks*)
+ that answers truncated follows the failure taxonomy: *more than shown* with Retry, no paging.
+- Check whether FIX-1651 or FIX-1652 shipped anything; a shipped read replaces its gap in the
+ [registry](BUSINESS-RULES.md#gap-registry), and only there.
## Follow-ups
- **The turn operation**, if the open fork is answered *file it*: a child of FIX-1649, then a
small PR wiring the composer.
- **A devtool address for a session**, so the trace link lands on the run. Devtool, not App Lab.
-- **Finding a run filters after listing** (BP-033): a topic filter on the listing at the source
- is engine work. Flagged, not in scope.
+- **Earlier attempts in other sessions** (BR-7): the link names the current attempt's run only.
+ A per-attempt history on the row would let the Session reach them. Not asked for yet.
+- **Harness, tokens and cost for a client** (BR-18): a read of what the run reported belongs to
+ FIX-1652's inspecting of a run, shaped once there, never a second copy of the harness
+ manager's record.
+
+## Notes from review
+
+Below the spec-review bar; for the implementer. From Cursor's review of PR #2428:
+
+- Merge the ten surfaces into four or five for the sequence (run and session and interrupt;
+ gaps and empty tabs; inspector and the devtool flag), keeping the S and V ids as check ids.
+- *Decided, not asked* in DECISIONS overlaps the BRs; the BRs are canonical where they differ.
+- Hand off, reassign and Open PR could be one disabled group with one owner line, unless the
+ closure needs them apart.
+- Tier the BRs as core (BR-5, BR-6, BR-11, BR-14 and the goal) and edge (BR-8 to BR-10, BR-12,
+ BR-13) when writing tests, so the watch-and-stop path is proved first.
+- Hold the resolved run for the open task; don't re-read it on a tab switch.
+- *Blocks* (BR-22) from one board read, never one read per dependency.
+- Elapsed time (BR-4) from the row and a clock, not a polling loop.
+- Mirror kitchen-sink's `background-work-panel` for the Session body and `picked-session-panel`'s
+ request settling for Interrupt, without importing from `apps/`. Use FIX-1662's shared
+ named-gap primitive if `frame` ships one, rather than new markup.
diff --git a/specs/issues/FIX-1664/SPEC.md b/specs/issues/FIX-1664/SPEC.md
index 742f0e57f3..ec4e1b1b1c 100644
--- a/specs/issues/FIX-1664/SPEC.md
+++ b/specs/issues/FIX-1664/SPEC.md
@@ -2,8 +2,9 @@
**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md)
-Feature · private app `labs/app-lab` · no FSD package changes · medium · 1 PR, after FIX-1662's
-`frame` PR · epic [FIX-1649](../../epics/FIX-1649/SPEC.md) (PR #2421) · beside
+Feature · private app `labs/app-lab` · no FSD package changes here, one small orchestration field
+split out ([the task-run link](PLAN.md#the-task-run-link)) · medium · 1 PR, after FIX-1662's
+`frame` PR and that link · epic [FIX-1649](../../epics/FIX-1649/SPEC.md) (PR #2421) · beside
[FIX-1662](https://linear.app/fixpoint-labs/issue/FIX-1662) (PR #2424) and
[FIX-1655](https://linear.app/fixpoint-labs/issue/FIX-1655) (PR #2425)
@@ -14,7 +15,7 @@ Feature · private app `labs/app-lab` · no FSD package changes · medium · 1 P
| **opens a running task** | Finds its run in the devtool by guessing which child session is which | Clicks a row in Tasks or a board card and watches that run's own steps arrive: narration, tool calls, edits, test runs, with no reload |
| **wants a run to stop** | Aborts the request with curl, if they know its id | Presses **Interrupt** (or Esc). The view says *interrupted* once the run's request says so, never before |
| **wants to hand a task to another worker, open its PR, or type to the worker** | Can't | Sees each control disabled with a line naming what arrives and who ships it ([D2](DECISIONS.md#d2), [the open fork](DECISIONS.md#open)) |
-| **reads the task inspector** | n/a | Worker and team, harness, started, tokens, cost, the plan and files the harness recorded, linked tasks and the devtool link: each a shipped read or a named gap |
+| **reads the task inspector** | n/a | Worker and team, started, the plan and files the harness recorded, linked tasks and the devtool link from shipped reads; harness, tokens and cost as a named gap, because nothing a client can read carries them yet |
| **builds the closure check** (FIX-1663) | Nothing to walk to | A task route whose every tab, action and inspector value is either real or names its owner |
## The goal, and how we'll know it's met
@@ -54,10 +55,11 @@ against App Lab's own state.
## What changes
-
+
The top row is today's empty frame. The bottom row is everything the task screen reads or
-writes: three shipped reads, one shipped write, and the gaps named where they sit.
+writes: the row, the run its link names, one shipped write, and the gaps named where they sit.
+Every owner is in one place, the [gap registry](BUSINESS-RULES.md#gap-registry).
No person edits a file for this: a Lab opens as FIX-1662 already describes. The one addition
a person types is where the devtool is, so the trace link can open it:
@@ -71,20 +73,25 @@ a person types is where the devtool is, so the trace link can open it:
```mermaid
flowchart LR
- T["the task row · FIX-1662's board read"] -->|"board id + task id"| K["the dispatch key for that task"]
- K --> S["the run's own session · listed as a dispatch run"]
- S -->|"items, live"| V["Session tab"]
- S -->|"what the harness recorded"| I["inspector · plan, files"]
- S -->|"its running request"| X["Interrupt · the shipped abort"]
+ G["the board's claim gate · in the run's session"] -->|"stamps session, request, attempt"| T["the task row · FIX-1662's board read"]
+ T -->|"the link's session"| S["the run's own session"]
+ S -->|"items, live, while the tab is open"| V["Session tab"]
+ T -->|"the link's request"| I["inspector · plan, files it recorded"]
+ T -->|"the link's request"| X["Interrupt · the shipped abort"]
```
-A handed-off row runs in a child session keyed on the board and the task, so App Lab finds the
-run from the task alone and reads nothing the Lab's server doesn't already serve.
+The run is the one place that knows which session it's in, so it writes that on the row as it
+starts, and App Lab reads it there. Nothing is rebuilt or matched from outside: a key rebuilt
+by the shell can name a different run (the same task drained from another conversation) or no
+run at all (a worker that shares one session across tasks). The link is a small field in the
+orchestration package, filed as its own issue ([D1](DECISIONS.md#d1)); App Lab changes nothing
+else outside itself.
## What stays as it is
-- **Every FSD package.** Session items render through the registry copies FIX-1662 brings in,
- unedited.
+- **Every FSD package, but for the task-run link**, which is its own issue in the orchestration
+ package. Nothing in Core or Engine. Session items render through the registry copies FIX-1662
+ brings in, unedited.
- **The board, the run and the harness.** App Lab changes a task only by aborting its run; what
the board then does with the row is the board's.
- **FIX-1662's frame**: the route, the right-panel slot and the shared reads are used, not
@@ -101,12 +108,18 @@ If wrong: the owner can't steer a run from the app, which is the issue's own pro
operation now, or leave it out of this epic's first cut?](DECISIONS.md#open) Recommended: file
it now as a child of FIX-1649; the composer ships disabled and is wired when it merges.
-1. **[D1](DECISIONS.md#d1) · The Session tab is the task's own run, found by its dispatch key,
- shown live.** If wrong: a Lab whose runs share one session per worker shows several tasks'
- steps under one task.
+1. **[D1](DECISIONS.md#d1) · The Session tab is the run the task's own row names, shown live;
+ the row learns it from a small field the run stamps as it starts, filed as its own issue
+ that this one waits on.** Changed after merge: the approved draft matched a rebuilt key, which
+ could show or stop the wrong run. If wrong: one small orchestration field and a later start
+ for this issue.
2. **[D2](DECISIONS.md#d2) · Of the four controls only Interrupt works; Hand off, reassign and
Open PR are disabled and name FIX-1651.** If wrong: you expected hand-off to work on day
one, and it needs a board rule changed first.
+Also changed after merge, decided rather than asked: harness, tokens and cost are a named gap
+owned by FIX-1652, since nothing a client can read carries them
+([Decided, not asked](DECISIONS.md#decided-not-asked)).
+
Reasoning and what lost: [DECISIONS.md](DECISIONS.md). The cases:
[BUSINESS-RULES.md](BUSINESS-RULES.md).
diff --git a/specs/issues/FIX-1664/figures/d1-run-session.svg b/specs/issues/FIX-1664/figures/d1-run-session.svg
index d1156ecf6b..c11759fb77 100644
--- a/specs/issues/FIX-1664/figures/d1-run-session.svg
+++ b/specs/issues/FIX-1664/figures/d1-run-session.svg
@@ -1,4 +1,4 @@
-