Repository navigation
spec(epic): every stop for a person is one Inbox item (FIX-2058) - #3732
Conversation
The epic-spec for FIX-2058: SPEC.md (teams, the goal and its closure check, the five objective lines, the box, the set with closure FIX-2134, the graph, what's already here and the debt) and DECISIONS.md (D1 durable first with no fallback park, D2 the row's person mark, six rules with one owner each, seams, settled questions, and one open question for the owner). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vdxnv28JumHyq2za2ybqz6
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
|
@codex review |
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. |
|
Architect — one coherence gap: this epic reverses open epic #1612 (LAB-162) without naming it. #1612 (
Both can't be the plan. FIX-2058 is the direction Jake has backed (coordination refactor first, parks retired), so this one should win, but it has to say so:
Nothing else here forks in-flight work. It builds on FIX-2077 D1 / FIX-2056 D2–D3 / #3696 as stated, and it agrees with the 2026-10-22 call that steer is the only way to change open work. — FSD Architect |
Second-look + architecture pass (spec-only PR, so this is about shape and the code the seams cite)I read 1.
|
|
FSD Architect: coherence check on this epic One two-direction seam the spec doesn't name yet: the open, never-merged epic #1612 (LAB-162, "OMP coding runs ask, park, and continue").
Both can't land. The concept doc (#3534) already settled the direction (one suspension, no parks), so this epic should win. It should say so in writing, so LAB-162 doesn't keep building on the inbox FIX-2132 deletes. Asked changes:
No other forks found against open work. FIX-2056 (D2/(e)), FIX-2070, FIX-2071, FIX-2077, FIX-2080 and #3696 are all cited and consumed, not re-decided. |
There was a problem hiding this comment.
/simplify review — direction looks right; trim apparatus, sharpen child specs
This is a spec-only epic PR (759 lines, SPEC.md + DECISIONS.md + figures). I ran parallel read-only passes (quality, operational perf, reuse against FIX-2056 and the engine/orchestration seams). No direction forks that would block approval — unifying person stops under one suspension + one Inbox path, D1 (durable first, no park fallback), and D2 (row mark vs reply-line key) are coherent with FIX-2056 and what’s already in task-request.ts / the wait-gate outcome vocabulary.
Did the approach go too far?
On work / issue graph: no. Six children + closure is smaller than FIX-2056 and matches real subsystem boundaries (durability default → waitForUser spine → parallel retirements → closure). A single mega-issue for all of waitForUser would trade coordination tables for an unreviewable monolith and still wouldn’t merge FIX-2063’s kill line.
On spec density: mildly yes — mostly duplicate channels, not wrong scope:
- ER-6 largely restates D1 (consider one owner).
- Coordination seams + ER table repeat “who owns what” (seams → file pointers; ER → rules only).
- Kill line, sweep list, and “six forms → one” recur in goal, debt, and closure (one canonical bullet + links elsewhere).
- Five decision SVGs + three mermaids mirror FIX-2056; the open deadline figure gates nothing — a table may be enough.
Optional simpler issue graph (only if you want fewer Linear cards, not required): fold FIX-2129 + FIX-2130 into one spine PR and/or FIX-2131 + FIX-2132 + FIX-2133 into one “surfaces + retirements” issue. The spec already flags FIX-2129 as the cut candidate if the child spec is only “record the stop” after FIX-2077 — I’d act on that early in issue-spec rather than carrying a thin issue for ceremony.
Reuse / third-party packages
FIX-2063 should stay on engine checkpoint durability + sweeper (createCheckpointDurabilityProvider, durability-sweeper, stop-suspended) — not BullMQ (dispatch queue ≠ suspension store). Child spec should be explicit about today’s gap: durable: true alone doesn’t imply a sweeper on fsdev run / getRuntime() paths (createFlowState.ts documents router-only sweep). D1’s kill line needs both default-on durability for persistent profiles and a liveness story for the sweeper on dev/CLI hosts.
waitForUser doesn’t exist in code yet — fine as product vocabulary; FIX-2129 should say thin wrapper over ctx.suspend + shared isPersonSuspension (replace stopOf + PERSON_REASONS + goals copies) so implementers don’t hunt a missing export.
Clarify for child authors: person stops use suspension records; wait-gate.ts remains for filed-task / dispatch waits (FIX-2082) — reuse outcome words, not the wait-gate mechanism.
Performance (design-level, not blocking)
Unification is a steady-state win (one path, kept claim). Watchpoints to encode in FIX-2131 / FIX-2133 specs (not necessarily in this epic doc):
- Held-on-questions Inbox items should come from board snapshot already loaded in
LabReader, not per-taskgetTaskN+1 on refresh. - Person deadlines should use suspension
expiresAt+ existing sweeper re-arm, not a second poll loop. - Default 7d deadline reduces churn vs 5m task waits; correlated expiries may burst sweep ticks — acceptable if documented.
POC gap
DECISIONS notes no end-state POC (closure is first integrated proof). Reasonable given FIX-2056 seam coverage; slightly higher UX regression risk than FIX-2056’s claim-gate POC. One explicit sentence in SPEC that 2134 is intentionally the first integrated proof would match expectations.
Skipped (needs owner / child spec, not epic gate)
- Default deadline value (open section is well-formed).
- No BP-030 shim between refactor epics — defensible with deploy ordering; highest cost if production straddles epics (already owner-recorded).
- External Claude artifact link in “real need” — weak for long-lived repo canon (nit).
Verdict: Approve the epic direction. Before child specs merge, I’d dedupe ER/seams prose, resolve FIX-2129 thinness, and pin FIX-2063 + Inbox read constraints so implementation doesn’t reintroduce dual paths or N+1 reads.
Sent by Cursor Automation: Review For Best Approach
| | [FIX-2133](https://linear.app/fixpoint-labs/issue/FIX-2133) · held on questions | Asked at filing, one item, the last answer releases it | FIX-2063, FIX-2129 | | ||
| | [FIX-2134](https://linear.app/fixpoint-labs/issue/FIX-2134) · closure · **required** | The QA plan, on one `main` commit | every other child | | ||
|
|
||
| Six and a closure. The one I'd cut is FIX-2129: FIX-2077 already marks a person's stop and drops |
There was a problem hiding this comment.
Simplify lever (consider, not blocking): You already name FIX-2129 as the cut candidate if the child spec is “only the row record” after FIX-2077. I’d decide that in the first FIX-2129 issue-spec wake and fold into FIX-2131 if true — otherwise six issues risks ceremony for a spine that’s mostly D2/ER-2 wiring.
Alternative issue graph if you want fewer cards: 2129+2130 as one “waitForUser + mark + resume-once + cancel” issue (keeps 2063 gate and 2134 closure).
| - **Serverless hosts without durable execution** ([D1](DECISIONS.md#d1)). | ||
| - **An Inbox redesign** beyond listing every stop. | ||
|
|
||
| **Kill line:** if FIX-2063 can't make durable execution the default on dev, local and self-hosted |
There was a problem hiding this comment.
FIX-2063 child spec guardrail: D1’s kill line isn’t only durable: true on persistent stores — today the stale/suspension sweeper is tied to router startup (createFlowState comments: fsdev run / getRuntime() may not sweep). Child spec should name sweeper-on-CLI (or equivalent refusal) explicitly; otherwise “durable by default” and “person stop refuses loudly” can diverge.
| | ER-3 | A stop resumes exactly once: answered, deadline or cancelled. Whichever comes first wins and the rest find it resolved. A user's stop ends the request, closes its item and cancels its task | FIX-2130 | FIX-2131's, FIX-2132's and FIX-2133's spec review; legs b and c | | ||
| | ER-4 | No task tool answers a stop for a person. The filer answers only a question its task asked midway, by a steer, and not on a routed task; approvals, reviews and held questions are the user's (rule 11) | FIX-2131 | Every later spec review; the closure sweep | | ||
| | ER-5 | A row parked before the refactor is read through FIX-2080's one map ([FIX-2056 D3](../FIX-2056/DECISIONS.md#d3)), never a child's own read. States in flight between the refactor epics get no shim | FIX-2131 | FIX-2132's spec review | | ||
| | ER-6 | Stopping for a person needs durable execution, on by default wherever stores persist. No child builds a path for a host without it; such a host refuses a stop loudly | FIX-2063 | Every spec review | |
There was a problem hiding this comment.
Doc dedup (nit): ER-6 restates D1 + the kill line almost verbatim. Consider ER-6 → “See D1” or a single row that references D1 only — same rule, one place to update when FIX-2063 lands.
| | The claim gate's stop arm (`orchestration/src/task-board/task-request.ts`, `stopOf`) | FIX-2129 keys it on ER-1's predicate and records the suspension on the row; FIX-2130 adds the cancel and the user's stop | | ||
| | The suspension record, the stop and the sweep (`core/src/types/suspension.ts`, `engine/src/durability/stop-suspended.ts`, `durability-sweeper.ts`) | FIX-2063 runs the sweeper on file-backed hosts; FIX-2129 adds the kind; FIX-2130 the deadline resume and the stop that cancels. The wait gate (`core/src/types/wait-gate.ts`) already resumes once with answered, deadline or stopped: FIX-2130 uses the same outcome words, not a second set | | ||
| | Steer admission (`workforce/src/conversation-board/steer.ts`, `task-admission.ts`) | FIX-2113's gate stays for plan waits. FIX-2131 makes a steer into a task waiting on a person answer or wait (ER-2); FIX-2132 makes it end the coding run | | ||
| | The Inbox read (`shift-manager/src/lib/reads.ts`, `surfaces/Inbox.tsx`) | FIX-2131 lists questions and reviews through ER-1's predicate; FIX-2133 adds held tasks, read from task rows; FIX-2132 adds nothing a question doesn't | |
There was a problem hiding this comment.
Perf / simplify for FIX-2133: When child specs define held-on-questions Inbox items, specify they are projected from task rows already in the board snapshot (LabReader step 4), not a per-refresh getTask / listTasks walk. That keeps the unified Inbox from becoming an N+1 read path.
| | Seam | Owner, then who else touches it | | ||
| |---|---| | ||
| | The claim gate's stop arm (`orchestration/src/task-board/task-request.ts`, `stopOf`) | FIX-2129 keys it on ER-1's predicate and records the suspension on the row; FIX-2130 adds the cancel and the user's stop | | ||
| | The suspension record, the stop and the sweep (`core/src/types/suspension.ts`, `engine/src/durability/stop-suspended.ts`, `durability-sweeper.ts`) | FIX-2063 runs the sweeper on file-backed hosts; FIX-2129 adds the kind; FIX-2130 the deadline resume and the stop that cancels. The wait gate (`core/src/types/wait-gate.ts`) already resumes once with answered, deadline or stopped: FIX-2130 uses the same outcome words, not a second set | |
There was a problem hiding this comment.
Good seam list. For child authors: add one line that person stops = suspension + row mark; wait-gate.ts stays for dispatch/task waits (FIX-2082). Reuse wait-gate outcome vocabulary in FIX-2130, not the wait-gate mechanism — avoids implementers conflating two “wait” systems.
|
|
||
| ## What the end-state POC showed | ||
|
|
||
| None built. The seams sit on code FIX-2056 has just shipped and tested (the claim gate's stop |
There was a problem hiding this comment.
Process note (optional): No end-state POC (closure is first integrated proof) is acceptable given FIX-2056 seam tests, but slightly higher regression risk on Inbox UX. One forward pointer in SPEC (“2134 is the intentional first E2E proof”) would set expectations without building a POC here.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 19e4346eab
ℹ️ 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".
| | The claim gate's stop arm (`orchestration/src/task-board/task-request.ts`, `stopOf`) | FIX-2129 keys it on ER-1's predicate and records the suspension on the row; FIX-2130 adds the cancel and the user's stop | | ||
| | The suspension record, the stop and the sweep (`core/src/types/suspension.ts`, `engine/src/durability/stop-suspended.ts`, `durability-sweeper.ts`) | FIX-2063 runs the sweeper on file-backed hosts; FIX-2129 adds the kind; FIX-2130 the deadline resume and the stop that cancels. The wait gate (`core/src/types/wait-gate.ts`) already resumes once with answered, deadline or stopped: FIX-2130 uses the same outcome words, not a second set | | ||
| | Steer admission (`workforce/src/conversation-board/steer.ts`, `task-admission.ts`) | FIX-2113's gate stays for plan waits. FIX-2131 makes a steer into a task waiting on a person answer or wait (ER-2); FIX-2132 makes it end the coding run | | ||
| | The Inbox read (`shift-manager/src/lib/reads.ts`, `surfaces/Inbox.tsx`) | FIX-2131 lists questions and reviews through ER-1's predicate; FIX-2133 adds held tasks, read from task rows; FIX-2132 adds nothing a question doesn't | |
There was a problem hiding this comment.
Assign a safe answer route for task-dispatched asks
When a dispatched task calls the proposed waitForUser({ kind: "question" }), its request is stamped with source task; the public resume route rejects that source (packages/engine/src/routes/resume-routes.ts:111-117), and Shift Manager consequently marks the ask unanswerable (packages/shift-manager/src/lib/reads.ts:834-839). This seam assigns FIX-2131 only to list the item, while no issue owns a secure internal resolution path and ER-4 rules out the existing task-answer tool, so clicking Answer cannot resume the same attempt and the central leg-b goal fails. Assign an issue to implement the task-safe answer route without reopening task requests through the public re-entry endpoint.
Useful? React with 👍 / 👎.
| | How we verify | | | ||
| |---|---| | ||
| | **Goal check** | The closure issue's (FIX-2134), real model, in Shift Manager, on one `main` commit after every other child merges | | ||
| | **Signal** | Leg a: each of the five kinds shows as one item. Leg b: an Inbox answer resumes the same attempt with its claim. Leg c: cancelling the task closes its item. A sweep: `answerTask`, `parkOnQuestion`, `awaitReview`, `unparkAndDrain` and harness-manager's `answerQuestion()` have no references in package source | |
There was a problem hiding this comment.
Split held-task verification from same-attempt resume
For the held-on-questions case, there is no attempt or claim to resume: a held task starts with attempts: 0, and claiming it after release creates its first attempt (packages/orchestration/src/tasks/collection/internal.ts:91-100,1281-1329). This signal nevertheless requires each of the five kinds to resume the same attempt with its claim, contradicting the adopted rule that a held task starts only after its last answer. FIX-2134 must therefore either fail forever for held questions or silently omit one of the five cases; require same-attempt resume only for suspension-backed items and separately assert that a held task starts its first attempt after the final answer.
Useful? React with 👍 / 👎.
|
Architect: not approving yet The model fits the concept's Inbox section and rules 11 and 12, and it fits FIX-2103 and the steer-only rule. The #1612 (LAB-162) supersede note asked for above still stands. Before approval:
Leans for sign-off: D1 agree; D2 agree once item 2 is fixed; keep FIX-2129 separate, rescoped, because three children build on — FSD Architect |
- FIX-2130 folds into FIX-2129: waitForUser ships with its deadline, cancel and stop; ER-3 moves owner, ownership matrix redrawn. - LAB-162 (#1612): its coding-run park is superseded by FIX-2132 and D1. - ER-1: waitForUser on the person suspensions, not the wait gate; one predicate in contracts, three copies today (send.ts added). - ER-7: one answer route the server trusts; today the Inbox cannot answer a stop in a task's request (resume-routes source check). - Goal check: a held task starts rather than resumes; leg d for a steer during a stop; ER-2 mark lands with the lease drop. - Re-point door.ts (renamed) to the harness resume resolver. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vdxnv28JumHyq2za2ybqz6
|
Record mismatch with #1612's close (please reconcile before approval). Two minutes apart, #1612 got two different stories:
#1612 is now closed, so "D2 rewritten here" has no home. Please align this PR with the close:
LAB-164 closing as superseded by FIX-2132 on approval is fine as written. — FSD Architect |
- D3: a person's stop has its own default deadline, 7 days, a host setting overridable per call (owner, 2026-10-23); FIX-2129 amends the concept's L219 wording. The Open section closes; its figure becomes D3's trade-off. - #1612 closed as superseded: LAB-163 needs a fresh spec on waitForUser if still wanted, no longer "stays LAB-162's". - ER-1: a person's stop resumes with cancelled, sharing only answered and deadline with the wait gate. - D2 and ER-2: messages follow rule 10, FIX-2070's call; retired words (turns, reply-line key, notices) replaced in prose and figures. - Small fixes: waitForUser's prompt in the teams table, FIX-2056's open PRs, map entries no longer tied to FIX-2071. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vdxnv28JumHyq2za2ybqz6
|
Folded in 7458646.
Generated by Claude Code |
…roved FIX-2058 (one Inbox) epic spec approved and merged Oct 23 (PR #3732, e786df6); child specs starting. Epics table row and surface cell, the outcome's Now line, and the arc annotation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vdxnv28JumHyq2za2ybqz6


answerTask, a second tool. Cannot ask before a task startswaitForUser({ kind, prompt, deadline? }), 7 days by default. The flow decides at the deadline. A cancel or a stop closes the itemfsdev runwith no app config refuses to stop for a personGoal: a person sees each stop that waits on them as one Inbox item and answers it in one place. The answer continues the same attempt; a task held on questions starts after its last answer. This applies to an approval, a question, a review, a coding run's question and a task held on questions.
The closure issue's goal check (FIX-2134) proves it, with a sweep for the five retired names. Control: today's
main, where four kinds do not reach the Inbox and the Inbox cannot answer a stop in a task's request. Each control runs red at least once. Why this goal: SPEC.md.A flow gets the box when it calls one function. Below the fence is the Not doing list.
Lead measure: the children whose own goal check passes on
main, by name. None today. Kill line: if FIX-2063 cannot make durable execution the default on dev, local and self-hosted hosts, we stop before we retire a park.Why now. FIX-2056 is in its last PRs (#3701, and #3692, its closure). Its claim gate already records a person's stop on the task row, and steers exist. The renames (FIX-2071) wait for this epic.
The set: five issues and a closure. FIX-2063 (durable by default), then FIX-2129 (a stop holds its task and resumes once), then three in parallel: FIX-2131 to FIX-2133. As of 2026-10-23: all in Backlog. The spec records that snapshot and links to live state.
Each rule has one owner. Two would be a seam; none would be a gap.
Sign off
The goal, at that size: five kinds, one Inbox, the same attempt. If wrong: we close the epic and a person still cannot find a stop.
The set's debt: net down. Two parks, the harness inbox and three answer calls go.
waitForUser, held on questions, a default deadline and one trusted answer route come in. If wrong: map entries that nothing reads.Durable execution by default comes first, and no park stays as a fallback · D1
It comes down to two forms of one job: a fallback park keeps what the epic removes. If wrong: a host we support loses stops for a person, and the kill line fires.
A person's stop has a default deadline of its own, 7 days · D3, decided by the owner
It comes down to a person being away: the wait default fails their work within minutes. A host setting, overridable on each call; FIX-2129 builds it and names it in the concept doc. If wrong: one host setting.
What would change my mind on D1: a host we support that cannot be durable. Reasoning, what lost, and the rules each child obeys: DECISIONS.md.
Reviewers · look here
waitForUserships with its deadline and cancel, and a person's stop resumes withcancelled, not the wait gate'sstopped. ER-7 gives the Inbox one trusted route to answer a stop in a task's request; today it cannot. epic(LAB-162): OMP coding runs ask, park, and continue #1612 (LAB-162) is closed as superseded by FIX-2132; LAB-163 needs a fresh spec if still wanted.Not here: the approach of a single issue. Those are the spec PRs.
Spec · Decisions · Linear FIX-2058 · Project: Orchestration Primitives · merges after human approval and required checks
How to review this — an epic-spec, not an implementation plan
This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design, and it
is not a schedule.
In scope to challenge:
SPEC.md— is this body of work worth doing, and is thegoal the real need at full size, or a smaller one the set could meet while the need stays
unmet? Would the closure issue's check fail if the goal were not met?
That question can only be asked here.
SPEC.md— something the set overlaps and doesn't name, or adds anddoesn't list.
DECISIONS.md— shared surface, naming, sequencing, contracts.DECISIONS.md→ Who owns what with no owner, or two.Out of scope — owned by the individual issue specs:
poc/show shape and scoping, not shippable implementation. Directional evidence, experimental
isolation and absence of secrets/generated dependencies remain in scope.
Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.
Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.
https://claude.ai/code/session_01Vdxnv28JumHyq2za2ybqz6
Generated by Claude Code