Repository navigation
Conversation
The epic-spec for making pi a coding harness FSD can dispatch to, and an FSD flow something you can run and watch from inside pi — plus the throwaway POC that falsified its Kill line before the objective gate. Reconciled against `main` before opening: the spec was drafted blind to the harness-manager epic, which shipped the contract PI-4 proposed to build. PI-4 is dropped; PI-5 conforms to `@flow-state-dev/core`'s `HarnessBlock` through `harnessManager`'s existing `harness` slot. Never merges. Issue IDs are placeholders until the Linear epic is filed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013TyNJnU2GwqQs7zcAVNTcp
|
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. |
There was a problem hiding this comment.
Simplify review — epic-spec + POC
This is a strong epic-spec: it self-corrects (POC limits, harness-manager reconciliation, Theme 8 vocabulary), and the core bet — pi's extension-side blocking vs Claude Code's black box — is worth pursuing. I would not approve the objective gate yet; the issue set and sequencing still carry more coordination cost than the Proof requires.
Verdict: hold the objective gate until §5 is answered
The real-flow probe's best finding — suspension / suspension_resume and a "suspended" terminal status already exist — should be a gate-0 spike, not one bullet among five parallel specs. Until you know whether mid-run ask is wiring (reuse suspension + recoveryClient) vs design (new companion durability + harness-manager invariant change), you cannot honestly count issues or size PI-6.
Simpler issue set (suggest: three, not five)
| Current | Simpler | Why |
|---|---|---|
| PI-1 + PI-2 | One console issue | PI-2 (SSE continuity) has no standalone user value without PI-1's dispatch/render. Split exists for parallel spec authorship, not operator outcomes. |
| PI-3 | Drop or fold into PI-6 | Scoped to post-park announce, but Proof/Kill line need mid-run blocking ask. §5 already says PI-3 cannot carry live questions; pi.sendMessage({ deliverAs: "steer" }) can notify mid-run without PI-3 solving durability. |
| PI-5 + PI-6 | Keep split, but tighten boundary | Companion is a harness asset (pi -e), not a separate install. Channel auth/correlation is one subprocess concern — two specs will negotiate the same invocation. Consider PI-5 owns asset + block; PI-6 only owns harness-manager / suspension bridge. |
| PI-5 alone | Smaller than theme 4 implies | Copy packages/codex (subprocess + translate/emit + capability), not Claude SDK in-process. One harness: line in conductor after rebase onto main. |
On five vs three: the "loop" argument for one epic is coherent, but expensive. If you keep one epic, three issues is enough. If reviewers reject the loop framing, split into console epic + harness epic joined only at the ask seam.
Approach that went too far
- Nine themes — Themes 3, 4, 6 are largely history now that
HarnessBlockshipped on main. Theme 8 (24-type allowlist) and Theme 9 (auth borrowing) belong in PI-1/PI-5 issue specs. Epic evolution still contradicts itself (e.g. "two Kill-line conditions demonstrated" vs later "none discharged"; Theme 3 "owes neutral outcome" vs Theme 6 "HarnessRunOutcomeshipped"). Collapse to ~4 load-bearing themes. - POC surface area —
companion.tsimplements the real Kill-line shape butprobe.tsbypasses it (session_start→callHost, notool_call, noflow_askexecute). Three probes + duplicated mailbox code ~200 lines without closing the gap the README documents. One network-enabled probe throughcompanion.tswould be simpler and higher signal. - §3 duplicates the POC README — For a never-merge branch, epic §3 could be a pointer + bullet list of spec deltas.
What I'd keep (approach is right here)
- Two runtime artifacts (host-installed harness vs developer
pi installextension) — install-model split is sound; mirrorsclaude-code+codexas separate vendor packages. - HTTP + SSE via
@flow-state-dev/client, not MCP or in-process engine — correct tradeoff for streaming + session continuity + fault isolation. - Companion extension asset for pi — no in-band
canUseTool; extension-sidetool_callblocking is the only seam. - TUI-only default with explicit allowlist — necessary; mirror
fsdev chatChatRenderer/oneLinerrather than inventing routing from scratch.
Performance / runtime risks to name in PI-6 (not epic blockers)
- Unbounded human block vs conductor
staleAfterMs/ lease windows — Kill line (d) needs a stated deadline, ideally via suspension rather than holdingtool_callopen indefinitely. - Per-risky-tool sequential approval round trips — session-level approval cache may be needed.
- Allowlist misconfiguration leaking
ping/state_snapshot/block_traceinto tool-result content — direct token cost; hard denylist for known noise types.
Kill-line fallback wording
If ask/approval seams fail, "ship PI-1..3 and stop" delivers Direction A only (watch flows from pi), not the stated Proof (board row + mid-run ask). Either fail the epic entirely or explicitly scope down the objective — don't imply the fallback satisfies the loop.
Recommended before objective gate
- Spike: suspension + harness-manager inbox — does it subsume mid-run ask without fighting the post-park
announceinvariant? - Re-count issues after (1).
- One follow-up POC with network:
companion.ts+ live model, assertbashdenial andflow_askblocking on a real turn. - Trim epic themes + evolution to "current assumptions" only.
Happy to re-review after §5 is owned and the issue table is re-cut.
Sent by Cursor Automation: Review For Best Approach
| makes B a capability rather than a substitution: conductor's own `ask.ts` records that the | ||
| current harness "offers no seam for a question, so this ask is forced rather than | ||
| spontaneous" (that reasoning now lives in `packages/harness-manager/src/ask.ts`, and it was | ||
| checked rather than assumed). **PI-3 is the weakest of the five** and is scoped down to wiring the existing |
There was a problem hiding this comment.
PI-3 scope vs Proof tension. This paragraph correctly calls PI-3 the weakest issue, but the Proof and Kill line require mid-run blocking ask — while PI-3 is scoped to post-park announce with no new inbox semantics. §5 later states PI-3 cannot carry live questions.
Simpler cut: drop PI-3 as a standalone issue. Operator notification can ride on PI-6 (pi.sendMessage delivery) or PI-1 (console infra). Post-park announce stays harness-manager's concern. Keeping PI-3 buys filing/sequencing cost without serving the differentiator.
| response reaches the blocked run and it resumes; (d) loss of either process fails safe — | ||
| the attempt ends and the row is settled or retried, never left running unbounded. If neither | ||
| seam meets all four, a pi harness is an alternative to Claude Code rather than an improvement, | ||
| and this epic should not finish: ship PI-1..3 as the operator console and stop. |
There was a problem hiding this comment.
Kill-line fallback may not match the objective. If neither seam meets all four conditions, shipping PI-1..3 delivers Direction A (FSD inside pi) but not the Proof (board row dispatched to pi with mid-run ask). That's substitution, not improvement.
Consider: fail the epic entirely, or explicitly scope down the objective in the kill-line text so the fallback outcome is honest.
|
|
||
| | Issue | What it delivers | Route | Spec PR | Impl PR | State | | ||
| | --- | --- | --- | --- | --- | --- | | ||
| | PI-1 | `packages/pi-extension` v1: HTTP client, host lifecycle, `/flow` command, dispatch + render | spec | — | — | Needs spec | |
There was a problem hiding this comment.
Five issues or three? PI-1 (HTTP client, /flow, host lifecycle) and PI-2 (SSE continuity) are one transport slice — PI-2 has no standalone user value without PI-1.
Suggest merging into one Console issue unless you need parallel spec PRs for staffing reasons. After §5 is answered, PI-3 may not survive at all (see inline on §5).
| `resolveClaudeAgent` more exactly and would make a scripted fake cheaper in tests. PI-5 | ||
| decides; a resolver seam should exist either way so the choice is not load-bearing. | ||
|
|
||
| - **Who owns a mid-run question, and what bridges it to the operator? — blocking, unowned, |
There was a problem hiding this comment.
This should be gate-0, not parallel with five specs. The real-flow probe already found suspension / suspension_resume and "suspended" status. Direction A can likely consume suspension items from SSE and answer via recoveryClient — same path as kitchen-sink/DevTool — without inventing a second question shape.
Recommend a short spike before the objective gate: if suspension + inbox subsume mid-run ask, PI-6 shrinks to wiring and PI-3 likely disappears. Defer PI-5/PI-6 detailed specs until this is owned.
| > 6. The contract already shipped — PI-4 is dropped · 7. Trust is explicit · 8. Item routing · | ||
| > 9. Auth and usage borrowing | ||
|
|
||
| 1. **Two packages, and the shared thing is a contract in neither of them.** The operator |
There was a problem hiding this comment.
Two artifacts: yes; two top-level packages: defer. The install-model split (host vs pi install) is load-bearing and mirrors claude-code / codex.
§5's "one source package with two publishable artifacts" may be simpler than pre-committing packages/pi + packages/pi-extension names at epic level. Lock the runtime split here; let PI-1/PI-5 decide monorepo layout and npm vs git. Note: plugins/flow-state-dev is a weak analog (skills/detection, no HTTP/SSE) — precedent is directory shape, not reusable code.
| FSD-side integration, `plugins/flow-state-dev` is what a developer installs onto their | ||
| machine. | ||
|
|
||
| 2. **The transport is HTTP + SSE against a `fsdev` host, via `@flow-state-dev/client`.** |
There was a problem hiding this comment.
Reuse existing renderer policy. Theme 8's 24-type allowlist is right, but don't derive it from scratch — packages/cli/src/chat/render.ts (ChatRenderer, oneLiner) already curates which OutputItem types surface. PI-1 should mirror or extract that, with a hard denylist for ping / state_snapshot / block_trace regardless of allowlist.
| `harnessRunHandleSchema`, and names itself `pi/cli-json` under the contract's own | ||
| `<package>/<door>` convention. | ||
|
|
||
| Three obligations the contract hands PI-5 directly, none of which it may renegotiate: |
There was a problem hiding this comment.
PI-5 template: packages/codex, not Claude SDK. Subprocess + JSONL + translate.ts/emit.ts + createCodexAgentCapability is the pattern for pi --mode json. Do not reach for RemoteAgentTaskHandle from claude-code/cli — superseded by core HarnessRunHandle.
On main, conductor already uses harnessManager's slot — PI-5 is a harness: closure, not reviving old labs/conductor/src/manager.ts coupling.
|
|
||
| --- | ||
|
|
||
| ## Epic evolution |
There was a problem hiding this comment.
Epic evolution is hard to trust. Reverse-chronological entries sit above superseded decisions (PI-5 before PI-4, "two Kill-line conditions demonstrated" later undone, Theme 3 "owes neutral outcome" vs Theme 6 "HarnessRunOutcome shipped").
Simpler: replace with a short "Current assumptions (as of reconciliation)" section and delete or footnote superseded bullets. Reduces reader confusion without changing decisions.
|
FSD Architect — coherence cut (agrees with Cycle PM in Workforce Atlas room). Split the two directionsThis epic currently carries two products under one loop:
That is two Conductor surfaces. Keep (1) as the Conductor / Goal 1 this-cycle track. Split or park (2) so we do not ship pi-console beside the existing operator board / Answer to "five issues or three": not five under one epic. Prefer a harness epic (PI-5 + PI-6, optionally fold PI-5 into PI-6 if still tiny after #1362) and a separate console epic (or backlog) for PI-1..3. Join them later at the question channel only if Proof still needs both ends. Harness-manager fence (already shipped)PI-4 drop is correct. PI-5 must install through the existing Blocking open question (§5)Where a mid-run question durably lives vs harness-manager's post-park Invent killNo new Channel / Team / MessageBoard L1 for the question path. No second Agent type. Question channel rides today's dispatch + harness contract. Please rewrite the epic objective and issue set to match the split; leave console out of the this-cycle Proof gate unless Jake pulls it back on. — FSD Architect |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8813ee889e
ℹ️ 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".
| 6. **The contract already shipped, so PI-4 is dropped and PI-5 conforms rather than | ||
| generalises.** Two earlier drafts of this theme argued the *order* of extracting a harness | ||
| contract: draw it first (rejected — abstraction for a set of one), then draw it from pi and | ||
| Claude Code with PI-5 before PI-4. Both are moot. The harness-manager epic landed the | ||
| contract on `main` while this spec was being POC'd, drawn from **Claude Code and Codex**: |
There was a problem hiding this comment.
Restore the harness contract before dropping PI-4
A repo-wide search of this commit finds no packages/core/src/types/harness.ts, packages/harness-manager, packages/codex, HarnessBlock, or HarnessSlot; only the pre-existing private labs/conductor manager exists. Consequently PI-5 cannot conform to the advertised contract, and dropping PI-4 leaves the running index without the prerequisite needed to implement the epic. Rebase onto the commit that introduces these packages or retain the contract-extraction work.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
| }); | ||
| }); | ||
|
|
||
| it("shares state across two dispatches, which is what PI-2 continuity needs", async () => { |
There was a problem hiding this comment.
Exercise session continuity in this test
This test still passes if testFlow ignores both stores and sessionId: the handler never reads or writes session state, and the only cross-run assertion is that independently generated request IDs differ, which is also true for unrelated sessions. Therefore it does not establish the shared-state continuity claimed in real-flow-findings.md and used to justify PI-2; write state during the first dispatch and assert that the second dispatch observes it.
Useful? React with 👍 / 👎.
| 8. **Item routing is a policy, decided once — and it is a 24-type allowlist, not a two-way | ||
| split.** An earlier draft said "progress and status render TUI-only; outputs and gaps enter | ||
| the tool result." That vocabulary was invented. The real `RuntimeItem` union in | ||
| `@flow-state-dev/contracts` has **24 types** (`block_trace`, `component`, `container`, | ||
| `continuation`, `debug`, `error`, `file`, `generator_step`, `message`, `output_audio`, | ||
| `output_text`, `ping`, `reasoning`, `reasoning_text`, `refusal`, `resource_change`, | ||
| `router_decision`, `source`, `state_change`, `state_snapshot`, `status`, `suspension`, | ||
| `suspension_resume`, `tool_output`), and a trivial handler flow emits `block_trace` — not |
There was a problem hiding this comment.
Reconcile the routing list with the committed item union
In this commit, packages/contracts/src/items/types.ts plus items/internal.ts define 17 RuntimeItem discriminator values, not the 24 listed here; values such as debug, file, ping, and refusal are not variants of that union. This makes the claimed POC correction and the shared PI-1/PI-2 routing contract describe a different codebase state, so downstream implementations cannot exhaustively implement the specified taxonomy. Rebase onto the intended taxonomy change or derive this list from the union present in the reviewed tree.
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
Moves spec/_epics/pi-harness.md into spec/_epics/pi-harness/ as SPEC.md, DECISIONS.md, BUSINESS-RULES.md, PLAN.md and figures/, per the shape PR #1800 landed on main. Reformat only. The objective, the owner's scope choices (harness-only, OMP first, questions first), the "not doing" list, the kill line, the missing trusted question handoff and the unproven status all carry over with their meaning intact. No decision was reopened and no review round was spent. Where the old sections went: §1 purpose & objective -> SPEC.md (teams table, the epic-pm objective block, the box, the sign-off) §2 themes -> DECISIONS.md D1-D6 §3 shape of the whole -> DECISIONS.md, what the end-state POC showed §4 running index -> SPEC.md, the set table with live status §5 open questions -> DECISIONS.md, decided in review epic evolution -> DECISIONS.md, how it got here New figures, rendered and checked in both themes: figures/end-state.svg what's in the box, with the no-durable-state fence figures/ownership.svg ER-1..ER-7 by LAB-162/163/164, one owner each figures/path.svg four lanes against time, now line before the gate spec-poc/epic-pi-harness/ is unchanged except for three links that pointed at the deleted single file. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125zR5sy7YdPsbrrtzQ1dKf
`real-flow-findings.md` asserted two things the POC does not show, both of which contradict the epic's own proven/unproven line. 1. The `RuntimeItem` union has 17 types, not 24. `OutputItem` has 13 members (`packages/contracts/src/items/types.ts`) plus the four trace types in `items/internal.ts`; `types.ts` carries exactly 17 `type:` discriminators. The seven extras were real type names that are not item discriminators: `output_text`, `reasoning_text`, `refusal`, `file` and `output_audio` are ContentParts inside an item (`items/content.ts`), and `debug` and `ping` are SSE event types (`items/events.ts`). The file now states that distinction, since it is the useful finding: a renderer allowlist built from "every type name in the items tree" over-counts. 2. "Session continuity is not hypothetical" did not follow from the test it cited. The handler touches no state, and `testFlow` mints a fresh request id per call without reading `sessionId` or `stores`, so the asserted id inequality holds for unrelated sessions too. The finding now states what the test shows — two sequential dispatches each reach terminal `completed` with a distinct request id — and that same-session continuity across a runtime restart remains unproven, matching the epic-spec. The test is deliberately not strengthened: proving in-process store sharing would not prove continuity across a restart. Its name is corrected to describe what it asserts, the dead `PI-2` planning label is dropped (BP-006), and a comment records what the test does not establish. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125zR5sy7YdPsbrrtzQ1dKf
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 99746956c6
ℹ️ 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 shipped harness manager reads only the previous attempt's confirmed session; a resumed attempt that throws confirms none, so the retry is handed null and starts a fresh conversation, undoing ER-3/ER-20's fail-closed resume one attempt later. Bring that one manager change into LAB-163's scope: for a row continuing a parked session, the resume obligation survives retries until a harness confirms it or the row settles failed. Other harnesses' ordinary- retry self-heal is unchanged (ER-12). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125zR5sy7YdPsbrrtzQ1dKf
Main now retains epic specs at specs/epics/<EPIC-ISSUE-ID>/ and keeps spec/ and spec-poc/ README-only, so the Process guards check failed on this branch. Move spec/_epics/pi-harness/ (with figures/) to specs/epics/LAB-162/ and spec-poc/epic-pi-harness/ to specs/epics/LAB-162/poc/omp-runtime-seams/, fix the relative links and paths that pointed at the old locations, add the Docs link to each nav line, and add the required DOCS.md derived from the existing spec and plan. No spec content is rewritten. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0125zR5sy7YdPsbrrtzQ1dKf
|
from: epic-coordinator Closing as superseded, on the owner's decision (2026-10-23). FIX-2058 (#3732) reverses this epic's human-wait model. A coding run's question no longer parks the task and gets answered through the harness inbox. It suspends the coding flow's request with FIX-2058 keeps two things from this epic: dispatch through the shared harness contract, and a later run continuing the same saved coding session ( Generated by Claude Code |
- 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
|
Superseded in part by FIX-2058 (#3732, under review). Child specs should not read this epic's ask half as current.
Recorded in Generated by Claude Code |
|
from: epic-coordinator Correction: the owner's close note is the record that stands. The 13:57Z "superseded in part" note is out of date. This epic is closed as superseded, and no D2 rewrite happens here. If OMP as a harness slot (LAB-163) is still wanted, it gets a fresh spec on the Generated by Claude Code |
- 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
|
Correction to the 13:57Z note above: the close note stands. #1612 is closed as superseded, and LAB-163 (the OMP slot) is not kept here; it needs a fresh spec on Generated by Claude Code |


Inside the box is what a dispatched OMP run gets. The fence is the decision that keeps it cheap: the runtime holds nothing durable, so the manager stays the only authority over a parked task.
Why now. The manager already supervises more than one harness, and its question path already parks and answers. What it has no route for is a question the runtime raised mid-run — so a supervised run either guesses or needs someone watching it.
The set: two issues. LAB-163 supplies the OMP harness; LAB-164 connects spontaneous questions, owns the missing trusted handoff, and carries the full-path proof. As of 2026-09-16: 0 done, 0 in flight, 2 filed and waiting on this gate. The live table and the dependency graph are in the spec.
Redrawn on this PR as the set moves. The now line sits before the gate: nothing has started. The one piece out of delivery order is LAB-164's joint feasibility check, which must land before either affected interface is finalized.
Every rule has one owner. ER-4 is the one row with two authors, on purpose — that joint seam is the work this epic exists to do.
Sign off
What would change my mind on 1: an immediate pi audience, or evidence that tool approvals — not questions — are what blocks real runs. Reasoning and what lost: DECISIONS.md. The rules every child obeys: BUSINESS-RULES.md.
Stated plainly: the full park / restart / resume path is unproven — model-free RPC checks show available seams, not the outcome. If safe continuation fails, this returns to the objective gate; no live wait or fresh-session fallback is substituted.
Reviewers · look here
Not here: either issue's approach or test plan. Those are the spec PRs.
Spec · Decisions · Rules · Plan · Linear LAB-162 · durable epic-spec · Project: Development Workflow Orchestration · never merges, open for the life of the epic
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 four documents. It is not an implementation plan and it is not any one issue's design.
In scope to challenge:
That question can only be asked here.
DECISIONS.md— shared surface, naming, sequencing, contracts.BUSINESS-RULES.mdwith no owner, or two.Out of scope — owned by the individual issue specs:
as the set moves and is never a review finding.
throwaway end-state POC built to show what the set looks like once every issue has landed
(
spec-poc). None of it ships. React to theshape and the scoping it reveals —
DECISIONS.mdsummarizes what it showed — and don'treview it as code.
Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.