From 8813ee889e5ccfa827d78962c401008c5d0f749b Mon Sep 17 00:00:00 2001 From: Jake Hoffner Date: Mon, 7 Sep 2026 08:22:09 -0400 Subject: [PATCH 1/7] epic(pi-harness): pi as a harness, and FSD from inside pi MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_013TyNJnU2GwqQs7zcAVNTcp --- spec-poc/epic-pi-harness/README.md | 97 +++ spec-poc/epic-pi-harness/auth-findings.md | 45 ++ spec-poc/epic-pi-harness/auth-probe.ts | 60 ++ spec-poc/epic-pi-harness/companion.ts | 68 +++ spec-poc/epic-pi-harness/host.mjs | 38 ++ spec-poc/epic-pi-harness/probe-result.json | 13 + spec-poc/epic-pi-harness/probe.ts | 85 +++ .../epic-pi-harness/real-flow-findings.md | 70 +++ spec-poc/epic-pi-harness/real-flow.test.ts | 118 ++++ spec-poc/epic-pi-harness/run-ask.jsonl | 44 ++ spec-poc/epic-pi-harness/tsconfig.json | 5 + spec/_epics/pi-harness.md | 561 ++++++++++++++++++ 12 files changed, 1204 insertions(+) create mode 100644 spec-poc/epic-pi-harness/README.md create mode 100644 spec-poc/epic-pi-harness/auth-findings.md create mode 100644 spec-poc/epic-pi-harness/auth-probe.ts create mode 100644 spec-poc/epic-pi-harness/companion.ts create mode 100644 spec-poc/epic-pi-harness/host.mjs create mode 100644 spec-poc/epic-pi-harness/probe-result.json create mode 100644 spec-poc/epic-pi-harness/probe.ts create mode 100644 spec-poc/epic-pi-harness/real-flow-findings.md create mode 100644 spec-poc/epic-pi-harness/real-flow.test.ts create mode 100644 spec-poc/epic-pi-harness/run-ask.jsonl create mode 100644 spec-poc/epic-pi-harness/tsconfig.json create mode 100644 spec/_epics/pi-harness.md diff --git a/spec-poc/epic-pi-harness/README.md b/spec-poc/epic-pi-harness/README.md new file mode 100644 index 0000000000..80f01d9235 --- /dev/null +++ b/spec-poc/epic-pi-harness/README.md @@ -0,0 +1,97 @@ +# POC — the pi companion channel + +Throwaway. Never merges. Built to falsify the epic's Kill line **before** the objective +gate, because the whole set rests on one unverified pi behaviour. + +## The question + +The epic's Proof and Kill line both assume: **a spawned `pi` run, loaded with a companion +extension via `-e`, can block on a question and get an answer back from the FSD host.** +If that does not hold, a pi harness is a *substitution* for Claude Code rather than an +improvement, and the epic should ship the console (PI-1..3) and stop. + +## What was built + +| File | What it is | +| --- | --- | +| `host.mjs` | Stand-in for the FSD host. Receives a request, waits 2s (an operator deciding), answers. | +| `companion.ts` | The companion extension: a `tool_call` handler that blocks `bash` on a remote verdict, and a `flow_ask` tool the run can call. | +| `probe.ts` | Mechanics probe that needs no LLM — checks tool registration and the blocking round trip directly. | + +**Transport is a file mailbox, not a socket.** The authoring sandbox forbids `listen(2)` +(`EPERM` on both TCP and a Unix socket). The transport is not what was under test — the +*blocking semantics* are — so the rendezvous was swapped and the question preserved. A real +implementation uses a socket or HTTP. + +## Run it + +```bash +node host.mjs & # the fake FSD host +pi --mode json -e ./probe.ts -p "hi" # the mechanics probe +cat probe-result.json +``` + +## What it showed + +```json +{ + "mode": "json", + "hasUI": false, + "toolRegistered": true, + "toolCount": 57, + "blockingRoundTrip": { "ok": true, "elapsedMs": 2136, + "answer": { "answer": "Use the staging database, never prod." } } +} +``` + +1. **A `-e` extension loads in a headless `--mode json` run and registers a tool.** `flow_ask` + was present among the run's 57 tools. +2. **An awaited extension callback stays pending across a slow cross-process round trip.** + 2136ms — the host's full 2s operator delay — and the answer arrived intact. + +### What it did NOT show — read this before citing it + +An earlier version of this file claimed the probe proved "blocking a run on a human is +mechanically fine." **It does not.** The gap is specific and worth stating plainly: + +`probe.ts` calls `callHost()` **directly from its `session_start` listener**. It never routes +through the registered `flow_ask` tool's `execute()` handler. So: + +- **No `tool_call` event is ever raised**, which means `companion.ts`'s `bash` approval + interceptor — half the channel — **was never exercised at all**. +- The ask tool was never shown to block a *real agent turn*. Tool **registration** is not tool + **execution**; `pi.getAllTools()` proves visibility only. +- The model-driven path failed entirely: the sandbox has no outbound network, so every LLM + call errored (`auto_retry_start` ×3, `errorMessage: "fetch failed"` — see `run-ask.jsonl`). + +What is genuinely established is narrower and still useful: **a pending promise inside a pi +extension can be settled by another process seconds later.** That is a real mechanism risk +removed. The file-mailbox transport does not weaken it, since `await` semantics do not depend +on whether the bytes arrive over a socket or a file. + +pi's own docs state independently that `tool_call` can block (`docs/extensions.md` 778–793) — +but that is documentation, not demonstration by this probe. + +Also untested, and owned by PI-6: authentication, run/attempt correlation, cancellation and +liveness, and what happens when either process dies. The probe deliberately has none of them. + +**To close the gap**, a follow-up needs network access and should drive `companion.ts` (not +`probe.ts`) with a live model: assert that a `bash` call is denied by the host verdict, and +that a model-invoked `flow_ask` suspends the turn until the host answers. + +## What changed because of it + +- **A mechanism risk under the Kill line is removed**, though no Kill-line condition is + discharged. The channel is not resting on an impossible premise; it is still unproven. +- **`ctx.hasUI` is `false` in `--mode json`.** The companion cannot prompt through pi's own UI + in a spawned run, so a question must travel out to the host. +- **The epic's real hole surfaced from that.** Asking *where* a live question goes exposed that + `announce` fires only **after** `board.awaitReview` — it is a post-park notification, while + `flow_ask` blocks mid-run. PI-3 as scoped cannot bridge that. The epic now carries it as a + blocking open question rather than an assumed dependency, which is the most valuable thing + this POC produced. + + > **Stale citation, kept for the record.** This probe cited + > `labs/conductor/src/manager.ts:1244`. That code has since been superseded by the published + > `@flow-state-dev/harness-manager`, where the same ordering is a *stated invariant* at + > `manager.ts:1498–1504`. The finding got stronger, not weaker — see the epic-spec's §5. diff --git a/spec-poc/epic-pi-harness/auth-findings.md b/spec-poc/epic-pi-harness/auth-findings.md new file mode 100644 index 0000000000..dde7f302c3 --- /dev/null +++ b/spec-poc/epic-pi-harness/auth-findings.md @@ -0,0 +1,45 @@ +# Probe — can pi's auth and usage be shared with FSD? + +Run: `pi --mode json -e ./auth-probe.ts -p "hi"` then read `auth-probe.json`. +The probe reports **shape and presence only**, never key material. + +## Result + +```json +{ + "hasModelRegistry": true, + "hasComplete": true, + "isUsingOAuth": { "anthropic": false }, + "anthropic": { "source": "OAuth", "authKeys": ["apiKey","headers"], "apiKey": "string(108)" }, + "openai-codex": { "source": "OAuth", "authKeys": ["apiKey"], "apiKey": "string(1702)" }, + "xai": { "error": "OAuth refresh failed for xai: fetch failed" } +} +``` + +## What this establishes + +1. **`ctx.modelRegistry.getProviderAuth(id)` resolves live credentials** — `{ auth: { apiKey, headers }, source }`. + `source: "OAuth"` for both logged-in providers. +2. **The credentials are actively managed, not read from a stale file.** `xai` failed + *because pi attempted an OAuth refresh* and the sandbox had no network. That error is + the evidence: pi owns token lifecycle, so anything borrowing a token inherits refresh + and expiry as a real concern. +3. **`modelRegistry.complete()` exists** — an extension can run inference through pi's + own resolved auth without ever handling a raw key. +4. **Usage has a defined route into pi's accounting**: a tool returning `usage` has it + persisted on the result and counted in the footer, `/session`, and RPC session totals + (`docs/extensions.md:2013`). + +`isUsingOAuth("anthropic")` returning `false` while `source` is `"OAuth"` is an +inconsistency worth understanding before relying on either as a branch condition. + +## What it does NOT establish + +- That handing a borrowed token to a **separate FSD host process** is acceptable. It is a + credential leaving the process that owns it, and pi's refresh cycle can invalidate it + mid-flow. This probe says it is *possible*, not that it is *right*. +- That `complete()` accepts the shape FSD generators need (tool loops, structured repair, + streaming). Unverified. +- Anything about a **spawned** harness run: a subprocess `pi` re-resolves its own auth from + `auth.json`, so the double-login problem does not arise there. This finding is about the + **extension** direction only. diff --git a/spec-poc/epic-pi-harness/auth-probe.ts b/spec-poc/epic-pi-harness/auth-probe.ts new file mode 100644 index 0000000000..9de3134919 --- /dev/null +++ b/spec-poc/epic-pi-harness/auth-probe.ts @@ -0,0 +1,60 @@ +/** + * Does a pi extension get resolved provider auth it could hand to FSD? + * Writes auth-probe.json. Reports SHAPE and PRESENCE only — never key material. + */ +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; + +const OUT = new URL("./auth-probe.json", import.meta.url).pathname; + +export default function (pi: ExtensionAPI) { + pi.on("session_start", async (_event, ctx) => { + const findings: Record = {}; + const anyCtx = ctx as any; + + findings.hasModelRegistry = Boolean(anyCtx.modelRegistry); + findings.hasComplete = typeof anyCtx.modelRegistry?.complete === "function"; + findings.isUsingOAuth = { + anthropic: anyCtx.modelRegistry?.isUsingOAuth?.("anthropic") ?? null, + }; + findings.registryMethods = anyCtx.modelRegistry + ? Object.getOwnPropertyNames( + Object.getPrototypeOf(anyCtx.modelRegistry), + ).filter((m) => m !== "constructor") + : []; + + for (const id of ["anthropic", "openai-codex", "xai"]) { + try { + const auth = await anyCtx.modelRegistry?.getProviderAuth?.(id); + findings[id] = auth + ? { + keys: Object.keys(auth), + source: auth.source ?? null, + authKeys: auth.auth ? Object.keys(auth.auth) : [], + authKinds: auth.auth + ? Object.fromEntries( + Object.entries(auth.auth).map(([k, v]) => [ + k, + typeof v === "string" ? `string(${v.length})` : typeof v, + ]), + ) + : {}, + // Presence and shape only. Never the secret itself. + apiKeyPresent: Boolean(auth.apiKey), + apiKeyPrefix: + typeof auth.apiKey === "string" + ? auth.apiKey.slice(0, 4) + : null, + headerNames: auth.headers ? Object.keys(auth.headers) : [], + baseUrl: auth.baseUrl ?? null, + envNames: auth.env ? Object.keys(auth.env) : [], + } + : { resolved: false }; + } catch (error) { + findings[id] = { error: String(error).slice(0, 200) }; + } + } + + const { writeFileSync } = await import("node:fs"); + writeFileSync(OUT, JSON.stringify(findings, null, 2)); + }); +} diff --git a/spec-poc/epic-pi-harness/companion.ts b/spec-poc/epic-pi-harness/companion.ts new file mode 100644 index 0000000000..16619538ff --- /dev/null +++ b/spec-poc/epic-pi-harness/companion.ts @@ -0,0 +1,68 @@ +/** + * The companion extension, loaded into a spawned pi run via `pi -e`. + * + * Proves two things the epic's Kill line rests on: + * 1. APPROVAL — a `tool_call` handler can block a tool on a REMOTE decision. + * 2. ASK — a registered tool can suspend the run on a remote answer. + * + * Throwaway. No auth, no correlation, no liveness handling — those are exactly + * the concerns the epic must own if this shape survives. + */ +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; +import { Type } from "typebox"; + +const DIR = new URL("./mailbox/", import.meta.url).pathname; + +async function callHost(kind: string, payload: unknown): Promise { + const { writeFileSync, existsSync, readFileSync, unlinkSync, mkdirSync } = + await import("node:fs"); + mkdirSync(DIR, { recursive: true }); + const id = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`; + writeFileSync(`${DIR}${id}.req`, JSON.stringify({ kind, payload })); + const started = Date.now(); + while (Date.now() - started < 30000) { + if (existsSync(`${DIR}${id}.res`)) { + const out = JSON.parse(readFileSync(`${DIR}${id}.res`, "utf8")); + unlinkSync(`${DIR}${id}.res`); + return out; + } + await new Promise((r) => setTimeout(r, 100)); + } + throw new Error("host did not answer within 30s"); +} + +export default function (pi: ExtensionAPI) { + // 1. Approval: block a tool call on a decision the host makes. + pi.on("tool_call", async (event) => { + if (event.toolName !== "bash") return; + const verdict = await callHost("approval", { + tool: event.toolName, + input: event.input, + }); + if (verdict.decision === "deny") { + return { block: true, reason: verdict.message }; + } + return undefined; + }); + + // 2. Spontaneous ask: a seam the run can reach for on its own. + pi.registerTool({ + name: "flow_ask", + label: "Ask the operator", + description: "Ask the human operator a question and wait for their answer.", + promptSnippet: + "Ask the operator a blocking question and wait for the answer", + parameters: Type.Object({ + question: Type.String({ + description: "The question to put to the operator", + }), + }), + async execute(_toolCallId, params) { + const result = await callHost("ask", { question: params.question }); + return { + content: [{ type: "text", text: String(result.answer) }], + details: {}, + }; + }, + }); +} diff --git a/spec-poc/epic-pi-harness/host.mjs b/spec-poc/epic-pi-harness/host.mjs new file mode 100644 index 0000000000..21827b068d --- /dev/null +++ b/spec-poc/epic-pi-harness/host.mjs @@ -0,0 +1,38 @@ +// Stand-in for the FSD host. A socket is the real transport; this POC uses a +// file rendezvous because the authoring sandbox forbids listen(2). What is +// under test is whether the spawned run BLOCKS, not how the bytes travel. +import { + readdirSync, + readFileSync, + writeFileSync, + unlinkSync, + mkdirSync, +} from "node:fs"; + +const DIR = new URL("./mailbox/", import.meta.url).pathname; +mkdirSync(DIR, { recursive: true }); +console.error("[host] watching mailbox"); + +setInterval(() => { + for (const f of readdirSync(DIR)) { + if (!f.endsWith(".req")) continue; + const id = f.slice(0, -4); + const msg = JSON.parse(readFileSync(DIR + f, "utf8")); + unlinkSync(DIR + f); + console.error( + `[host] <- ${msg.kind}: ${JSON.stringify(msg.payload).slice(0, 120)}`, + ); + // The operator "thinks" for 2s. The run must still be blocked after this. + setTimeout(() => { + const answer = + msg.kind === "approval" + ? { + decision: "deny", + message: "Denied by the operator via the FSD host.", + } + : { answer: "Use the staging database, never prod." }; + writeFileSync(DIR + id + ".res", JSON.stringify(answer)); + console.error(`[host] -> ${JSON.stringify(answer)}`); + }, 2000); + } +}, 100); diff --git a/spec-poc/epic-pi-harness/probe-result.json b/spec-poc/epic-pi-harness/probe-result.json new file mode 100644 index 0000000000..123f153d39 --- /dev/null +++ b/spec-poc/epic-pi-harness/probe-result.json @@ -0,0 +1,13 @@ +{ + "mode": "json", + "hasUI": false, + "toolRegistered": true, + "toolCount": 57, + "blockingRoundTrip": { + "ok": true, + "elapsedMs": 2136, + "answer": { + "answer": "Use the staging database, never prod." + } + } +} \ No newline at end of file diff --git a/spec-poc/epic-pi-harness/probe.ts b/spec-poc/epic-pi-harness/probe.ts new file mode 100644 index 0000000000..fcf0d5920d --- /dev/null +++ b/spec-poc/epic-pi-harness/probe.ts @@ -0,0 +1,85 @@ +/** + * Mechanics probe — no LLM required. + * + * Answers two questions the epic's Kill line rests on, without needing a model + * call (the authoring sandbox has no outbound network): + * 1. Does an extension loaded via `-e` in `--mode json` actually register a + * tool, so a spawned run could call it? + * 2. Can an extension handler BLOCK on a remote answer — i.e. does pi await an + * async handler across a multi-second round trip to the host? + * + * Writes findings to probe-result.json. + */ +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; +import { Type } from "typebox"; + +const DIR = new URL("./mailbox/", import.meta.url).pathname; +const OUT = new URL("./probe-result.json", import.meta.url).pathname; + +async function callHost(kind: string, payload: unknown): Promise { + const { writeFileSync, existsSync, readFileSync, unlinkSync, mkdirSync } = + await import("node:fs"); + mkdirSync(DIR, { recursive: true }); + const id = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`; + writeFileSync(`${DIR}${id}.req`, JSON.stringify({ kind, payload })); + const started = Date.now(); + while (Date.now() - started < 20000) { + if (existsSync(`${DIR}${id}.res`)) { + const raw = readFileSync(`${DIR}${id}.res`, "utf8"); + unlinkSync(`${DIR}${id}.res`); + try { + return JSON.parse(raw); + } catch { + throw new Error(`host wrote a malformed answer: ${raw.slice(0, 120)}`); + } + } + await new Promise((r) => setTimeout(r, 100)); + } + throw new Error("host did not answer within 20s"); +} + +export default function (pi: ExtensionAPI) { + pi.registerTool({ + name: "flow_ask", + label: "Ask the operator", + description: "Ask the human operator a question and wait for their answer.", + parameters: Type.Object({ question: Type.String() }), + async execute(_id, params) { + const r = await callHost("ask", { question: params.question }); + return { + content: [{ type: "text", text: String(r.answer) }], + details: {}, + }; + }, + }); + + pi.on("session_start", async (_event, ctx) => { + const { writeFileSync } = await import("node:fs"); + const findings: Record = { + mode: ctx.mode, + hasUI: ctx.hasUI, + }; + + // 1. Is the tool actually registered and visible to the run? + const all = pi.getAllTools().map((t) => t.name); + findings.toolRegistered = all.includes("flow_ask"); + findings.toolCount = all.length; + + // 2. Does pi await a handler across a slow remote round trip? + const t0 = Date.now(); + try { + const answer = await callHost("ask", { + question: "probe: blocking round trip", + }); + findings.blockingRoundTrip = { + ok: true, + elapsedMs: Date.now() - t0, + answer, + }; + } catch (error) { + findings.blockingRoundTrip = { ok: false, error: String(error) }; + } + + writeFileSync(OUT, JSON.stringify(findings, null, 2)); + }); +} diff --git a/spec-poc/epic-pi-harness/real-flow-findings.md b/spec-poc/epic-pi-harness/real-flow-findings.md new file mode 100644 index 0000000000..a665e8bd32 --- /dev/null +++ b/spec-poc/epic-pi-harness/real-flow-findings.md @@ -0,0 +1,70 @@ +# Probe — a REAL flow through the REAL engine + +The first probe in this directory tested pi's half against a **mock FSD host**, which left +the actual integration untested at both ends and let the spec invent FSD shapes that do not +exist. This runs a genuine flow through `runAction` — the same engine the server uses. + +Run (from `packages/testing`, which resolves the workspace deps; `spec-poc/` is not a +workspace member): + +```bash +cp real-flow.test.ts ../../packages/testing/test/tmp/ && cd ../../packages/testing +npx vitest run test/tmp/real-flow.test.ts +``` + +## Result — 2 passed + +```text +STATUS: completed +OUTPUT: {"verdict":"reviewed packages/pi","target":"packages/pi"} +ITEM COUNT: 1 +ITEM SHAPES: ["block_trace"] +REQUEST IDS: test_flow_req_...ea00df985007d test_flow_req_...2e5a4444de6c +``` + +## What this establishes + +1. **A real flow action dispatches and returns a real terminal status** (`completed`) and a + real typed output. This is the shape a pi extension renders. +2. **Two dispatches on one shared session produce distinct request ids** while sharing store + state — exactly the pairing PI-2 must keep straight when resuming a flow across pi + sessions and forks. Session continuity is not hypothetical; the substrate already has it. +3. **A pure `handler` flow needs no LLM and no network**, so the epic's transport and routing + claims can be tested in CI without keys. + +## What it corrected in the epic + +**Theme 8's item routing was invented.** The spec split items into "progress · status" versus +"outputs · gaps" — a four-way vocabulary that does not exist. The real `RuntimeItem` union in +`@flow-state-dev/contracts` has **24 types**: + +```text +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 +``` + +Two of these matter beyond routing: + +- **`suspension` / `suspension_resume`** — FSD *already has* a first-class suspend/resume item + pair, and `testFlow` already reports a `"suspended"` terminal status. The epic's §5 open + question ("where does a mid-run question live?") was written as if this had to be invented. + It may not: the durable mid-run question mechanism may already exist in the item vocabulary. + **This is the single most useful thing this probe found**, and it should be checked before + that question is answered. +- **`ping`** — a keepalive, which is a routing decision the spec never made (it must never + reach the LLM, and probably never the operator either). + +A simple `handler` emitted exactly one `block_trace` item. So the routing policy cannot be +stated as a two-bucket rule; it needs a default for 24 types, and the safe default is +*TUI-only unless explicitly promoted*, not the reverse. + +## What it does NOT establish + +- Nothing about **HTTP or SSE**. `testFlow` is in-process; the epic's transport choice + (theme 2) is still untested. A follow-up should boot `fsdev dev` and drive the real + `/api/flows/{kind}/actions/{action}` route. +- Nothing about a **generator** (LLM) flow, tool loops, or streaming deltas. +- Nothing about the **pi side**. This probe and the pi probe still do not touch each other; + no end-to-end path has run. diff --git a/spec-poc/epic-pi-harness/real-flow.test.ts b/spec-poc/epic-pi-harness/real-flow.test.ts new file mode 100644 index 0000000000..94e0317823 --- /dev/null +++ b/spec-poc/epic-pi-harness/real-flow.test.ts @@ -0,0 +1,118 @@ +/** + * Runs a REAL Flow State Dev flow through the REAL engine — no mock host. + * + * The earlier probe in this directory tested pi's side against a fake FSD host, + * which left the actual integration untested at both ends. This exercises the + * genuine `runAction` runtime (`testFlow` runs "the same runAction engine the + * server uses") so the epic's transport claims rest on the real item stream and + * the real terminal-status vocabulary rather than on a mock's invented shapes. + * + * Run: pnpm vitest run spec-poc/epic-pi-harness/real-flow.test.ts + */ +import { describe, expect, it } from "vitest"; +import { handler } from "@flow-state-dev/core"; +import type { FlowInstance } from "@flow-state-dev/core/types"; +import { testFlow } from "@flow-state-dev/testing"; + +// The engine validates input against the action's schema; this POC is about the +// runtime and the item stream, not schema plumbing. +const passthroughSchema = { + parse: (value: unknown) => value, + safeParse: (value: unknown) => ({ success: true as const, data: value }), +}; + +describe("a real FSD flow, driven the way a pi extension would drive it", () => { + it("dispatches an action and returns a real terminal status and item stream", async () => { + const flow: FlowInstance = { + id: "pi-poc", + kind: "pi-poc-flow", + requireUser: true, + actions: { + review: { + inputSchema: passthroughSchema as never, + block: handler< + { target: string }, + { verdict: string; target: string } + >({ + name: "review-handler", + execute: (input) => ({ + verdict: `reviewed ${input.target}`, + target: input.target, + }), + }), + }, + }, + } as FlowInstance; + + const result = await testFlow({ + flow, + action: "review", + input: { target: "packages/pi" }, + userId: "operator_1", + }); + + // What a pi extension would render and route (theme 8). + console.log("STATUS:", result.status); + console.log("OUTPUT:", JSON.stringify(result.output)); + console.log("ITEM COUNT:", result.items.length); + const itemType = (item: unknown): string => + typeof item === "object" && item !== null && "type" in item + ? String((item as { type: unknown }).type) + : ""; + console.log( + "ITEM SHAPES:", + JSON.stringify(result.items.map(itemType), null, 1), + ); + + expect(result.error).toBeUndefined(); + expect(result.status).toBe("completed"); + expect(result.output).toEqual({ + verdict: "reviewed packages/pi", + target: "packages/pi", + }); + }); + + it("shares state across two dispatches, which is what PI-2 continuity needs", async () => { + const { createInMemoryStores } = await import("@flow-state-dev/engine"); + const stores = createInMemoryStores(); + + const flow: FlowInstance = { + id: "pi-poc-2", + kind: "pi-poc-session", + requireUser: true, + actions: { + ping: { + inputSchema: passthroughSchema as never, + block: handler<{ n: number }, { seen: number }>({ + name: "ping-handler", + execute: (input) => ({ seen: input.n }), + }), + }, + }, + } as FlowInstance; + + const first = await testFlow({ + flow, + action: "ping", + input: { n: 1 }, + userId: "operator_1", + sessionId: "session_a", + stores, + }); + const second = await testFlow({ + flow, + action: "ping", + input: { n: 2 }, + userId: "operator_1", + sessionId: "session_a", + stores, + }); + + console.log("REQUEST IDS:", first.requestId, second.requestId); + expect(first.status).toBe("completed"); + expect(second.status).toBe("completed"); + // Distinct requests within one shared session — the pairing a pi extension + // must keep straight when it resumes a flow across pi sessions. + expect(first.requestId).not.toBe(second.requestId); + }); +}); diff --git a/spec-poc/epic-pi-harness/run-ask.jsonl b/spec-poc/epic-pi-harness/run-ask.jsonl new file mode 100644 index 0000000000..4375bea187 --- /dev/null +++ b/spec-poc/epic-pi-harness/run-ask.jsonl @@ -0,0 +1,44 @@ +{"type":"session","version":3,"id":"01a06e05-9362-7f68-b7d1-e00f119db7ad","timestamp":"2026-09-04T20:04:14.306Z","cwd":"/Users/jakehoffner/Projects/flow-state-dev/implementation/spec-poc/epic-pi-harness"} +{"type":"agent_start"} +{"type":"turn_start"} +{"type":"message_start","message":{"role":"user","content":[{"type":"text","text":"Use the flow_ask tool to ask the operator which database to use, then report their answer verbatim."}],"timestamp":1788552255773}} +{"type":"message_end","message":{"role":"user","content":[{"type":"text","text":"Use the flow_ask tool to ask the operator which database to use, then report their answer verbatim."}],"timestamp":1788552255773}} +{"type":"message_start","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552255778,"errorMessage":"fetch failed"}} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":11,"endedAt":1788552255785},"id":"f204107d","parentId":"00de145b","timestamp":"2026-09-04T20:04:15.786Z"}} +{"type":"message_end","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552255778,"errorMessage":"fetch failed"}} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":1,"endedAt":1788552255786},"id":"f3eec5f7","parentId":"c0304aae","timestamp":"2026-09-04T20:04:15.786Z"}} +{"type":"turn_end","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552255778,"errorMessage":"fetch failed"},"toolResults":[]} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":3,"endedAt":1788552255789},"id":"724d88c4","parentId":"f3eec5f7","timestamp":"2026-09-04T20:04:15.789Z"}} +{"type":"agent_end","messages":[{"role":"user","content":[{"type":"text","text":"Use the flow_ask tool to ask the operator which database to use, then report their answer verbatim."}],"timestamp":1788552255773},{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552255778,"errorMessage":"fetch failed"}],"willRetry":true} +{"type":"auto_retry_start","attempt":1,"maxAttempts":3,"delayMs":2000,"errorMessage":"fetch failed"} +{"type":"agent_start"} +{"type":"turn_start"} +{"type":"message_start","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552257793,"errorMessage":"fetch failed"}} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":9,"endedAt":1788552257800},"id":"c7b29895","parentId":"724d88c4","timestamp":"2026-09-04T20:04:17.801Z"}} +{"type":"message_end","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552257793,"errorMessage":"fetch failed"}} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":1,"endedAt":1788552257801},"id":"ae61ce47","parentId":"d9e902e8","timestamp":"2026-09-04T20:04:17.801Z"}} +{"type":"turn_end","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552257793,"errorMessage":"fetch failed"},"toolResults":[]} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":2,"endedAt":1788552257803},"id":"8ea0ab4a","parentId":"ae61ce47","timestamp":"2026-09-04T20:04:17.803Z"}} +{"type":"agent_end","messages":[{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552257793,"errorMessage":"fetch failed"}],"willRetry":true} +{"type":"auto_retry_start","attempt":2,"maxAttempts":3,"delayMs":4000,"errorMessage":"fetch failed"} +{"type":"agent_start"} +{"type":"turn_start"} +{"type":"message_start","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552261807,"errorMessage":"fetch failed"}} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":12,"endedAt":1788552261816},"id":"76344ece","parentId":"8ea0ab4a","timestamp":"2026-09-04T20:04:21.816Z"}} +{"type":"message_end","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552261807,"errorMessage":"fetch failed"}} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":1,"endedAt":1788552261817},"id":"a2ef5b3e","parentId":"9fd6c426","timestamp":"2026-09-04T20:04:21.817Z"}} +{"type":"turn_end","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552261807,"errorMessage":"fetch failed"},"toolResults":[]} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":1,"endedAt":1788552261818},"id":"bbae277c","parentId":"a2ef5b3e","timestamp":"2026-09-04T20:04:21.818Z"}} +{"type":"agent_end","messages":[{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552261807,"errorMessage":"fetch failed"}],"willRetry":true} +{"type":"auto_retry_start","attempt":3,"maxAttempts":3,"delayMs":8000,"errorMessage":"fetch failed"} +{"type":"agent_start"} +{"type":"turn_start"} +{"type":"message_start","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552269824,"errorMessage":"fetch failed"}} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":16,"endedAt":1788552269837},"id":"1d14b46b","parentId":"bbae277c","timestamp":"2026-09-04T20:04:29.837Z"}} +{"type":"message_end","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552269824,"errorMessage":"fetch failed"}} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":1,"endedAt":1788552269838},"id":"e66347c4","parentId":"d50cefbc","timestamp":"2026-09-04T20:04:29.838Z"}} +{"type":"turn_end","message":{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552269824,"errorMessage":"fetch failed"},"toolResults":[]} +{"type":"entry_appended","entry":{"type":"custom","customType":"om.agent.activity","data":{"version":1,"durationMs":2,"endedAt":1788552269840},"id":"8b9b4240","parentId":"e66347c4","timestamp":"2026-09-04T20:04:29.840Z"}} +{"type":"agent_end","messages":[{"role":"assistant","content":[],"api":"anthropic-messages","provider":"anthropic","model":"claude-haiku-4-5","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"error","timestamp":1788552269824,"errorMessage":"fetch failed"}],"willRetry":false} +{"type":"auto_retry_end","success":false,"attempt":3,"finalError":"fetch failed"} +{"type":"agent_settled"} diff --git a/spec-poc/epic-pi-harness/tsconfig.json b/spec-poc/epic-pi-harness/tsconfig.json new file mode 100644 index 0000000000..14d2b6bb8b --- /dev/null +++ b/spec-poc/epic-pi-harness/tsconfig.json @@ -0,0 +1,5 @@ +{ + "//": "POC scratch. These files are not part of the build: auth-probe.ts and probe.ts are pi EXTENSIONS, loaded by pi's own jiti runtime, which resolves @earendil-works/* at run time. They are excluded so the repo's type-checker does not chase a dependency the repo does not (and should not) have.", + "files": [], + "include": [] +} diff --git a/spec/_epics/pi-harness.md b/spec/_epics/pi-harness.md new file mode 100644 index 0000000000..ad8be45d58 --- /dev/null +++ b/spec/_epics/pi-harness.md @@ -0,0 +1,561 @@ +# Epic-spec — pi as a harness, and FSD from inside pi + +**In one line:** teach FSD to hand coding work to pi, and teach pi to run FSD flows — so a +board row can be dispatched to an agent that can *stop and ask you something*, and you can +watch and answer from the editor you already have open. + +## The 60-second version + +Today conductor dispatches coding work to Claude Code. That works, but the run is a black +box with a lid: it cannot ask you a question halfway through. Conductor's own `ask.ts` admits +it — the harness "offers no seam for a question, so this ask is forced rather than +spontaneous." The agent has to guess, finish, and be corrected afterwards. + +pi can do better, because pi extensions can intercept a tool call and *block on it*. That +turns a run from a black box into a conversation: + +```text + conductor board row ──dispatch──▶ spawned pi run + │ + "staging or prod DB?" │ (run blocks) + ▼ + you, in your own pi session ◀──── FSD host + │ + └─ "staging" ────────▶ run resumes, PR lands +``` + +**Two directions, one loop.** Direction A is *FSD inside pi*: a `/flow` command, streaming +items, questions surfacing where you already are. Direction B is *pi as harness*: conductor +spawning `pi --mode json` instead of Claude Code. A is the window; B is the engine. The Proof +needs both. + +**Five issues.** PI-1..3 build the operator console (no FSD changes needed at all). PI-5 makes +pi dispatchable *against a contract that already exists* — `@flow-state-dev/core`'s +`HarnessBlock`, drawn by the harness-manager epic from Claude Code and Codex and shipped on +`main`. PI-6 wires the question channel that makes the whole thing worth doing. **PI-4 is +dropped**: it proposed extracting the contract this epic now merely conforms to. See theme 6. + +**Biggest open risk:** a mid-run question has nowhere durable to live — `announce` fires only +*after* the row parks, and in the published `@flow-state-dev/harness-manager` that is a +**stated invariant** rather than an accident of a lab: "After the park, never before. What is +announced must already be answerable" (`manager.ts:1498–1504`). FSD does ship `suspension` / +`suspension_resume` items and a `"suspended"` status, so a bridge is buildable — but PI-6 now +has to argue against a deliberate decision in a shipped package, not fill a gap in a +prototype. §5, first question. Unowned, and worth more than ten minutes before anyone specs +PI-6. + +> **Filing note (delete once the epic issue exists).** This file was drafted on `poc/pi`. +> The convention is `spec/_epics/.md` on branch `epic/pi-harness`, with a never-merged +> epic PR and a Linear parent issue carrying the `Epic` label. Issue IDs below are +> placeholders (`PI-1` … `PI-6`) — replace them with the real Linear IDs when the sub-issues +> are filed, and the `§4` running index becomes live at that point. + +--- + +## How to review this + +*(Paste verbatim into the epic PR description's collapsed `
` block.)* + +This is an **epic-spec**: the shared objective and cross-cutting decisions for a *set* of +issues. It is not an implementation plan and it is not any one issue's design. + +**In scope to challenge:** + +- The objective — is this body of work worth doing, and is the outcome the right one? +- **Whether the set overbuilds.** Each issue can earn its place while the whole is too much. +- A cross-cutting decision in §2 — shared surface, naming, sequencing, contracts. +- A missing issue the objective implies, or one in the set that doesn't serve it. + +**Out of scope — owned by the individual issue specs:** + +- Any single issue's approach, architecture, file layout, or test plan. +- Anything that touches exactly one issue. It belongs on that issue's spec PR. +- **Any POC files on this branch, entirely.** + +Feedback in the second list is routed to the issue it concerns as an implementer note, +not folded in here. + +--- + +## Parts worth reviewing closely + +> **1. §1 — whether this is five issues or three.** The set spans two directions (pi as +> client, pi as harness) and the honest question is whether they are one epic or two. An +> earlier draft justified keeping them together by claiming a harness without the console is +> "a harness nobody can watch"; that was **wrong** — conductor already has run records, +> `status` and an inbox (`labs/conductor/src/manager.ts` 248–263). The set is kept together on +> a narrower claim: the objective is a *loop*, and the Proof requires both ends. If a reviewer +> rejects that, this splits into a console epic and a harness epic joined at PI-3/PI-6. +> +> **2. Theme 1 — two packages, not one.** The opening instinct was a single `packages/pi` +> carrying both halves. It is split on install-model grounds, and this is the decision most +> likely to be re-litigated by an implementer who only sees one half. +> +> **3. Theme 6 — PI-4 is dropped, because the contract already shipped.** Two earlier drafts +> argued about *when* to extract the harness contract and in what order. Both are moot: +> `@flow-state-dev/core`'s `HarnessBlock` / `HarnessRunHandle` landed on `main` out of the +> harness-manager epic, drawn from Claude Code **and Codex**, and `harnessManager` already +> takes a `harness` slot. pi is harness three against an existing contract. This is the +> largest change since the draft that was POC'd — **a reviewer who read the earlier version +> should re-read themes 3, 4 and 6 and §4 rather than skim them.** +> +> **Where I'm unsure:** whether PI-3 survives its own scope-down. It is the weakest issue and +> the POC promoted it from a sequencing preference to a hard dependency of PI-6 (see §3), +> which is the opposite of the direction a weak issue usually travels. + +--- + +## 1. Purpose & objective *(the gated sign-off surface)* + +**Objective.** Make pi a coding harness FSD can dispatch to, and make an FSD flow something +you can run and watch from inside pi. Today the harness slot is Claude Code and nothing else, +and a conductor run's questions are discovered by polling `status` rather than by being asked. +When this epic lands, a board row can be worked by a pi run, and the operator is *told* when +that run needs them. + +> **Package names.** Two artifacts, named here so no issue has to guess: **`packages/pi`** is +> the FSD-side harness (installed by the FSD host; PI-5), and **`packages/pi-extension`** is +> the operator console a developer installs onto their own machine via `pi install` (PI-1..3). +> Names are provisional — §5's single-source option may change how they are *published* — but +> the two-artifact split itself is theme 1's load-bearing decision and does not change. + +**Holistic necessity.** Five issues plus one unowned bridge (§5), and the honest question is +whether it is three. Direction +A (PI-1..3, FSD from inside pi) is independently useful and needs no changes to FSD. Direction +B (PI-5..6, pi as harness) is where the leverage is, and it is **observable without A** — +conductor already carries run records, `status` and a durable inbox. What A adds is that the +operator is *told* rather than having to look. The set is one epic because the objective is +the loop, and the Proof cannot be read off either half alone. The ask seam (PI-6) is what +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 +`announce` hook with no new inbox semantics; if it grows a durable store or a second question +shape, that is the signal it should have been deferred. + +**Proof.** PI-6's goal check, which that issue must produce as a runnable end-to-end check +rather than an assertion: a conductor board row dispatched to the pi harness raises a question +mid-run, the operator is prompted in their own pi session without polling, answers there, and +the run resumes and settles the row. + +**Lead measure.** The set's goal-proven issues, named each report. + +**Kill line.** Judged on four observable conditions, and **approval and spontaneous ask are +judged separately** — one can hold while the other does not, and that leads to a scoped cut +rather than an all-or-nothing verdict. For either seam to count: (a) a spawned run blocks on +it; (b) the block is durably correlated to its conductor issue/phase/attempt; (c) an operator +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. + +**None of the four is yet discharged.** §3's POC removes a *mechanism* risk underneath (a) and +(c) — an awaited pi extension callback can be settled by another process seconds later — but +it never exercised a tool call or an approval interception, so all four remain PI-6's to earn. +Condition (d) must name its bound, not merely assert safety: an unanswered request or a dead +host has to hit a stated deadline that ends the attempt through the existing run timeout and +settles or retries the row. + +**Not doing:** + +- **MCP as the transport.** See theme 2. +- **Embedding `@flow-state-dev/engine` in the pi process.** See theme 2. +- **Defining flows in the extension.** The extension dispatches and renders; it never + defines. The moment flow logic lives in the extension there are two runtimes. +- **A `source: "pi"` inbound transport adapter.** It buys provenance on `RequestRecord.source` + and a place to hang a principal resolver, and neither direction needs it to work. Deferred + deliberately, not forgotten. +- **Renegotiating the harness contract.** `@flow-state-dev/core` already carries it, drawn + from Claude Code and Codex. pi conforms to `HarnessRunInput` / `HarnessRunHandle` and is + installed through `harnessManager`'s existing `harness` slot. If conforming turns out to be + impossible, that is a finding to raise on this PR — not a licence for PI-5 to widen the + contract locally. + +## 2. Themes & long-horizon direction + +> **The themes below are the cross-cutting decisions — the things that would be expensive to +> change once issues start landing. Skim the bold sentence of each; read the body only for +> the ones you want to challenge.** +> +> 1. Two packages, not one · 2. HTTP, not MCP · 3. The event contract is *not* the type I first +> named · 4. Conductor's coupling is concrete *(now history)* · 5. The question channel · +> 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 + extension and the harness are separate packages because they have incompatible install + models: the extension is installed by a *developer onto their own machine* (`pi install`, + landing in `~/.pi/agent/npm/`, with pi's core packages as un-bundled `peerDependencies`), + while the harness is installed by the *FSD host* (`@flow-state-dev/core`, `workspace`, + `zod`). Merging them makes every extension user `npm install` a copy of `core` they never + execute — and pins their extension to a `core` version, which is precisely the coupling + theme 2 chose HTTP to avoid. What the halves genuinely share is the `HarnessEvent` + vocabulary, and that cannot live in a pi package because `claude-code` must satisfy it too + (see theme 3). The division mirrors one the repo already has: `packages/claude-code` is the + 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`.** + Not MCP: the MCP adapter is stateless-by-default with a single JSON result and no SSE, + which discards streaming *and* session continuity — the two properties that make embedding + FSD in an agent worth doing. Not the in-process engine SDK: a pi extension loads via jiti + into a long-running interactive process, and hosting the registry, stores, streaming and + model resolution there means model auth is resolved twice and a flow fault takes the + operator's session with it. (An earlier draft also asserted flow spend never reaches pi's + footer; that was never verified against pi's usage accounting and is dropped rather than + carried as decoration.) The extension owns an + out-of-process host (spawned in `session_start`, torn down in `session_shutdown`) or + attaches to a running one. **No issue in this epic imports `@flow-state-dev/engine` into + the pi process.** + +3. **One harness event vocabulary, derived from `TranslatedEvent` — but not by adopting it + wholesale, and not from `SdkMessageLike`.** + `SdkMessageLike` (`packages/claude-code/src/sdk/types.ts` ~70–160) is explicitly a + "structural subset of the SDK's `SDKMessage` union": Anthropic wire format, carrying + `session_id`, `parent_tool_use_id`, `thinking`/`tool_use` content blocks, and a + `SdkResultSubtype` of Claude's own vocabulary (`error_max_turns`, `error_max_budget_usd`). + It is **not** a neutral vocabulary and must not be lifted. The neutral candidate is the + package's *post-translation* `TranslatedEvent` union (~164–278) — `file_op_observed`, + `plan_item_observed`, `work_gap_observed`, `status`, `error`, normalized `result` — whose + own comment states the point: "by the time this exists the tool names are gone, which is + what keeps the vendor mapping to one site." Even that is not a contract as it stands, for + two reasons: its file-op and plan-item variants encode the Claude work-recorder's semantics, + and **its terminal result still carries `SdkResultSubtype`** (`types.ts:270`) whose values + are Claude's own — `error_max_turns`, `error_max_budget_usd` (`types.ts:13–19`). + + **Both decisions this theme posed have since been made on `main`, and not by this epic.** + The neutral home is `@flow-state-dev/core` (`packages/core/src/types/harness.ts`) — *not* + `contracts`, and the file states why: a block declares a **runtime** schema for its output, + which the zero-dependency layer cannot carry. The neutral terminal type is + `HarnessRunOutcome` — `"finished" | "stopped-at-limit" | "failed"` — with the vendor's + richer reason kept on the vendor's own extension, "so no framework code ever branches on a + vendor string." And work observation is **not** in the contract: `recordWork` stays a + Claude Code option the host passes inside its own slot closure + (`harness-manager/src/manager.ts:245`), so no harness owes it. + + **Translation from vendor messages stays inside each harness** is the one part of this + theme that survives unchanged, and it still binds PI-5. + +4. **The coupling this theme was written to break is already broken — read the rest as + history.** `@flow-state-dev/harness-manager` on `main` "imports no coding agent and reads + no vendor field: the host hands it a factory," and that factory is `HarnessSlot`: + `(feeds: HarnessFeeds) => HarnessBlock`, where the feeds are exactly `cwd`, `resume` and + `onSession`. What follows describes `labs/conductor` as it stood when this was drafted, and + is kept because PI-5's shape is easier to judge against what the coupling *was*. + + The board/checkout/attempt/verdict flow in `manager.ts` is genuinely harness-neutral and + should not be rewritten. But the coupling was concrete, not a type annotation: `manager.ts` + imported `claudeCodeAgent` directly (line 45) and invokes it as a sequencer step (1383–1396), + forcing `detached: true`, `recordWork: true`, and a `cwd` callback, with a result schema + expecting `sessionId`/`finalMessage`/`usage`/`costUsd` (1180–1200). `recordWork: true` means + the manager depends on the Claude integration's **work-observation behaviour**, not just its + terminal status — so the contract must cover normalized terminal result, cancellation, + resume-id semantics across retries, and work observation. An issue that finds itself + changing the manager's *control flow* has hit a cross-cutting question — comment up on this + PR rather than deciding it locally. **PI-5's real job is now much smaller than this theme + implies**: supply a `HarnessSlot` closure that returns a conforming pi block, and let the + published manager own everything else. + +5. **A spawned pi run's question and approval seam is a companion extension, not an in-band + callback — and the channel it speaks is a cross-cutting concern.** + + ```typescript + // The asset the harness ships and loads into the run via `pi -e`. + // Claude Code gets this from the SDK's canUseTool. pi has no in-band + // equivalent — blocking is an extension-side API, so it needs a companion. + pi.on("tool_call", async (event) => { + if (!risky(event.toolName)) return; + const verdict = await host.ask({ tool: event.toolName, input: event.input }); + if (verdict.denied) return { block: true, reason: verdict.why }; // ◀ run stops here + }); + ``` + + Claude Code's SDK exposes + `canUseTool`, which is why `claudeCodeAgent` has `onToolApproval`. pi has no equivalent: its + `tool_call` blocking hook is an *extension-side* API living inside the pi process. So the + harness ships a companion extension as an **asset** (a file loaded into the spawned run via + `pi -e`), which intercepts `tool_call` and registers an ask tool, and calls back to the + dispatching flow. Being an asset rather than a dependency is what keeps the harness package + free of a pi dependency. §3's POC shows an awaited extension callback can be settled by + another process, but did **not** exercise interception or tool execution. **The channel + itself is not a detail PI-6 may invent locally**: it needs an authentication posture that is + per-attempt rather than ambient, run/attempt correlation, cancellation and liveness, and + defined behaviour when either process dies. PI-6 owns it, but it is stated here because a + wrong answer strands paid runs rather than affecting one issue's design. + +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**: + + - `@flow-state-dev/core` (`packages/core/src/types/harness.ts`) owns `HarnessRunInput`, + `HarnessRunEnvelope`, `HarnessRunHandle`, `HarnessBlock`, `HarnessResolver` and + `HarnessSessionHook`. + - `@flow-state-dev/harness-manager` owns the `harness` slot — + `HarnessSlot = (feeds: HarnessFeeds) => HarnessBlock` — plus the run record and inbox. + - `@flow-state-dev/codex` is the proof the contract survives a second vendor. + + **So the sequencing constraints this theme used to impose are gone.** There is no private + seam in `labs/conductor` to keep unexported, no two-invocation-path window to close, and no + "PI-4 cannot be specced until PI-5 has a shape to generalise from." PI-5 writes a + `HarnessSlot` closure returning a pi block whose handle parses against + `harnessRunHandleSchema`, and names itself `pi/cli-json` under the contract's own + `/` convention. + + Three obligations the contract hands PI-5 directly, none of which it may renegotiate: + + - **The prompt is the only block input.** Working directory and resumed session arrive + through `HarnessResolver`s the host feeds, never on the input schema, because that schema + is model-facing through a capability tool preset (BP-031). The resolver is handed `ctx` + and *deliberately not* the input. + - **Abort is not a field.** A conforming harness forwards the block's `ctx.signal` into + whatever cancels the run, and a cancelled run surfaces as a **throw**, not a handle + status. This is load-bearing for Kill-line condition (d). + - **`onSession` fires the moment pi names a session**, during the run and not after it, or + a run that dies mid-flight leaves nothing to resume. + + Sequencing that remains: PI-1 lands first; PI-2 and PI-3 build on its transport. PI-6 + depends on PI-5 and on the §5 mid-run question bridge. PI-1..3 and PI-5 can all be specced + in parallel. + +7. **Trust is decided explicitly, never inherited.** `claude-code` carries `settingSources` + because a checkout the run did not come with can otherwise configure the agent working in + it. pi has the identical hazard with project trust and `.pi/extensions` discovery, and the + identical control (`project_trust`). Any issue that spawns a pi run states its trust + posture rather than defaulting to `defaultProjectTrust`. + +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 + any of the four names the spec used. + + So the policy is: **TUI-only by default, promoted to tool-result `content` by explicit + allowlist.** Defaulting the other way puts `ping` keepalives and `state_snapshot` dumps + into the operator's context window. PI-1 sets the allowlist and PI-2 extends it; no issue + invents a second rule. + + ```text + flow item ─┬─ default (most of 24) ─▶ appendEntry() → operator sees it, LLM does not + └─ allowlisted ─▶ tool result content → both + ``` + +9. **Borrowing pi's auth is possible and probably right for the extension; borrowing it for + the harness is neither.** A probe (`spec-poc/epic-pi-harness/auth-findings.md`) confirmed + `ctx.modelRegistry.getProviderAuth(id)` hands an extension live, actively-refreshed OAuth + credentials (`source: "OAuth"`), that `modelRegistry.complete()` can run inference through + pi's own auth, and that a tool returning `usage` lands in pi's footer and `/session` totals + (`docs/extensions.md:2013`). **The two directions have opposite answers:** + + | | Auth | Usage | + | --- | --- | --- | + | **Harness** (conductor spawns `pi`) | Non-problem. The subprocess resolves its own `auth.json`. | Belongs to conductor's cost record, not a footer. | + | **Extension** (flows run from your session) | Real choice: borrow pi's, or make the host log in separately. | Real opportunity: `usage` on the tool result. | + + So there is **no double-login problem in Direction B** — that intuition, though reasonable, + does not survive contact: a spawned `pi` is already logged in. + + For Direction A, prefer **`complete()` over token-passing**: it keeps the credential inside + the process that owns it. Handing a raw token to a separate host process means it can be + invalidated mid-flow by pi's own refresh, and it puts a secret somewhere its owner cannot + revoke. Whether FSD generators can run on `complete()` at all is unverified and is §5's + question, not a decision this document makes. + +## 3. Shape of the whole *(POC)* + +Three probes, each answering one question. All in `spec-poc/epic-pi-harness/` on this branch, +each with its own findings file. **None of them touch each other — no end-to-end path has +run.** + +| Probe | Question | Verdict | +| --- | --- | --- | +| `probe.ts` + `host.mjs` | Can a pi extension block on a remote answer? | Yes, narrowly — see below | +| `auth-probe.ts` | Can pi's auth and usage be shared with FSD? | Yes; `auth-findings.md` | +| `real-flow.test.ts` | What does a *real* flow actually return? | 2 tests pass; `real-flow-findings.md` | + +**Built:** a stand-in FSD host, a companion extension loaded into a spawned run via `-e`, a +no-LLM mechanics probe, an auth-surface probe, and a real flow driven through the real +`runAction` engine. + +**See it:** `node host.mjs &` then `pi --mode json -e ./probe.ts -p "hi"`; read +`probe-result.json`. The flow test runs from `packages/testing` (see its findings file for +why). + +**Showed — stated narrowly, because the first write-up of this POC over-claimed it.** Three +facts: a `-e` extension loads in a headless `--mode json` run; it registers a tool that is +visible to the run (`flow_ask` among 57); and an awaited extension callback stays pending +across a 2136ms cross-process round trip and resolves with the host's answer intact. The last +is the property that matters — a pending promise inside a pi extension can be settled by +another process seconds later — and the file-mailbox transport does not weaken it, since +`await` semantics do not depend on whether the bytes arrive over a socket or a file. + +**What it did NOT show, despite an earlier draft of this section claiming otherwise:** the +probe calls the host *directly from its `session_start` listener*, not through the `flow_ask` +`execute()` handler. No `tool_call` event is ever raised, so **`companion.ts`'s approval +interceptor was never exercised**, and the ask tool was never shown to block a real agent +turn. Tool *registration* is not tool *execution*. The model-driven path failed entirely (no +outbound network in the authoring sandbox). pi's docs independently state that `tool_call` +can block (`docs/extensions.md` 778–793), but that is documentation, not demonstration. + +It also showed `ctx.hasUI` is **false** in `--mode json`: the companion cannot prompt through +pi's own UI inside a spawned run. + +**The other two probes did more damage to the spec than the first one did good**, which is +the argument for having run them: + +- The **auth probe** killed a plausible assumption (that a pi harness would force a second + login) and opened a real design choice for the extension direction. Theme 9. +- The **real-flow probe** caught the spec inventing FSD's own vocabulary: theme 8's item + routing named four item types that do not exist, against a real union of 24. It also found + `suspension` / `suspension_resume` items and a `"suspended"` status, which may mean §5's + blocking question is already answered by the substrate. + +**Changed:** the Kill line became four observable conditions with approval and ask judged +separately — but *none* of the four is discharged by this POC; it removes a mechanism risk +underneath (a) and (c) rather than satisfying them. Theme 5 gained the channel's +cross-cutting obligations, which the probe made conspicuous by deliberately having none. And +the mid-run question bridge (§5) was found only because `hasUI: false` forced the question of +where a live question actually goes — which turned out to be the epic's real hole. + +## 4. Running index + +| 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 | +| PI-2 | SSE item streaming and flow-session continuity across pi sessions and forks | spec | — | — | Needs spec | +| PI-3 | `announce` → pi: questions surface in the operator's UI, answered from there | spec | — | — | Needs spec | +| PI-5 | `packages/pi`: `piAgent` conforming to core's `HarnessBlock`, over `pi --mode json`, installed through `harnessManager`'s `harness` slot | spec | — | — | Needs spec | +| PI-6 | Companion extension: approval interception, the ask seam, and the host channel | spec | — | — | Needs spec | +| ~~PI-4~~ | ~~Harness contract extracted from *two* implementations~~ — **dropped**, shipped by the harness-manager epic (`@flow-state-dev/core`, `@flow-state-dev/codex`) | — | — | — | Not filed | + +## 5. Open cross-cutting questions + +- **Does the operator extension need `@flow-state-dev/client` at all, or should it speak raw + `fetch` + SSE?** Raised while scoping PI-1. `client` is isomorphic and already implements + `Last-Event-ID` resume, which maps onto a pi restart for free — that is the argument for + taking the dependency. The argument against is that it is the extension's *only* FSD + dependency, and dropping it would make the extension version-independent of the whole + framework. Blocks nothing; PI-1 proceeds on "use `client`" and folds if resume turns out to + be the only thing it was carrying. + +- **Is the extension published to npm, or installed from git/local path?** Raised while + scoping PI-1. `pi install` accepts `npm:`, `git:` and local paths, so a v1 can ship without + answering it. Publishing brings the extension under the repo's changeset discipline and + makes it a supported surface; git/local keeps it internal while the shape settles. + Recommend deferring publication until PI-3 lands, since the console is not useful to anyone + else until it can carry a question. + +- **In-process pi SDK, or `pi --mode json` subprocess, for PI-5?** Raised while scoping the + harness. The subprocess is sequenced first (theme 6 names it) because it matches how + the manager already treats a run as something that happens in a checkout it owns, and because + isolation is worth more than latency for a paid coding run. The in-process route mirrors + `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, + and harder than the earlier draft thought.** The largest remaining hole, and re-cited: the + post-park announce is no longer a lab's accident but a **stated invariant of a published + package**. `@flow-state-dev/harness-manager` calls `board.awaitReview(...)` and only then + `announce({ question })` (`manager.ts:1498–1504`), with the reason written beside it: + "After the park, never before. What is announced must already be answerable: a subscriber + fast enough to act on an announcement sent earlier…". But `flow_ask` blocks **during** a + live run. PI-3 is scoped to the existing announce path with no new inbox semantics, so + **PI-3 as specced cannot carry a live question** — and PI-6 must now argue against a + deliberate decision in a shipped package rather than fill a prototype's gap. + + **Check this before designing anything.** The real item vocabulary contains `suspension` and + `suspension_resume`, and `testFlow` already reports a `"suspended"` terminal status + (`spec-poc/epic-pi-harness/real-flow-findings.md`). FSD may already have the durable + suspend/resume primitive this question assumes must be built. If it does, the answer is to + *use* it rather than invent a second question shape, and this stops being a design question + and becomes a wiring one. + + If it does not, someone must decide: does a mid-run ask create a durable conductor question + immediately (reusing the park/announce path, at the cost of parking a still-running + attempt), or stay live on the companion channel with separate notification (at the cost of a + second question shape and no durability if the host dies)? Plus who assigns + issue/phase/attempt correlation, and who owns cancellation. This decides PI-3's real scope + and PI-6's feasibility, so it should be resolved **before** the objective gate. + + **What the delivery half costs is now known, and it is cheap.** Whatever the durable answer + turns out to be, reaching the operator does not need a new pi mechanism. A pi extension can + hold a background poll or subscription started in `session_start` and injected with + `pi.sendMessage(..., { deliverAs })`, where `"steer"` delivers **after the current assistant + turn finishes its tool calls, before the next LLM call** — mid-run, without waiting for the + agent to settle — and `"followUp"` waits for it to settle. `triggerTurn: true` wakes an idle + session. `docs/extensions.md` (`pi.sendMessage`, and the `file-trigger.ts` example, which is + this shape end to end). So **the operator console is not limited to park-time delivery**, + and PI-3 does not have to solve durability to be useful. That does not close this question, + which is about where the question durably *lives* and who correlates it — only about how it + reaches a watching human once it exists. + +- **One source package with two publishable artifacts, instead of two packages?** Raised by + epic review. A single source location could emit a thin pi-package manifest for the extension + and a separate npm entry for the harness, sharing build tooling but not install dependencies + — preserving one ownership location while keeping the runtime split theme 1 requires. It may + collapse back to theme 1 in practice, since `pi install` resolves an npm package name and so + the extension needs its own manifest regardless. Blocks nothing; theme 1's *runtime/install* + split is the load-bearing part and holds either way. A simpler interim: run the extension as + a project-local `.pi/extensions` entry during validation and defer publishing entirely. + +- ~~**Where does the neutral harness contract live — `contracts`, or a new + `packages/harness`?**~~ **Answered on `main`, by the harness-manager epic, not by this + one.** It lives in `@flow-state-dev/core` (`packages/core/src/types/harness.ts`), and the + reason rules out the option this question favoured: a block declares a **runtime** schema + for its output, which the zero-dependency `contracts` layer cannot carry. PI-5 and PI-6 + import from `core`. + +--- + +## Epic evolution + +- **After reconciling against `main` (7 Sep)** — the spec was drafted blind to the + harness-manager epic, which shipped the thing PI-4 proposed to build. `packages/codex` and + `packages/harness-manager` are on `main`; the neutral contract is in `@flow-state-dev/core`, + drawn from Claude Code and Codex; `harnessManager` takes a `HarnessSlot`. **Dropped PI-4** + and rewrote theme 6 around conforming rather than extracting, with the three obligations the + contract imposes on PI-5 (prompt-only input, abort-as-throw, `onSession` during the run). + Closed theme 3's two open decisions and §5's neutral-home question — all three were answered + on `main`, none by this epic. Re-cited theme 4 as history and the mid-run question bridge to + `harness-manager/src/manager.ts:1498–1504`, where post-park announce is a **stated + invariant** rather than a prototype's gap, which makes PI-6 harder than the previous draft + assumed. Added the one piece of good news: `pi.sendMessage`'s `deliverAs: "steer"` delivers + between turns of a live run, so the console is not limited to park-time delivery. + +- **After two more probes** — ran an auth probe and a *real* flow through the real `runAction` + engine, having previously tested only against a mock host. Added theme 9 (auth/usage + borrowing: no double-login exists for the harness direction; `complete()` preferred over + token-passing for the extension). Rewrote theme 8 after the real item union turned out to + have 24 types, none of them the four the spec had invented — routing is now an allowlist + with a TUI-only default. Flagged in §5 that `suspension`/`suspension_resume` items and a + `"suspended"` status already exist, so the mid-run question may be wiring, not design. + Added an executive summary and diagrams after the spec was called unreadable. +- **After the POC was re-reviewed** — corrected §3, which over-claimed its own probe: the probe + calls the host from `session_start`, never through the tool's `execute()`, so no `tool_call` + fires and the approval interceptor was never exercised. Kill-line conditions (a) and (c) went + back to undischarged. Found that `TranslatedEvent`'s terminal result still carries + `SdkResultSubtype`, so theme 3 owes a neutral outcome type too. Added PI-5's private-seam and + single-invocation-path constraints. Opened the mid-run question bridge in §5 after finding + `announce` fires only *after* `board.awaitReview` (`manager.ts:1244`), so PI-3 as scoped + cannot carry a live question. +- **Epic drafted** — six issues across two directions under one outcome: pi is a harness FSD + can dispatch to, and an FSD run is something an operator can watch. Split the proposed single + `packages/pi` into two packages after the install models turned out to be incompatible, and + scoped PI-3 down to wiring the existing `announce` hook with no new inbox semantics. +- **After epic review** — corrected theme 3 (the neutral vocabulary is `TranslatedEvent`, not + `SdkMessageLike`, which is Anthropic wire format) and theme 4 (conductor's coupling is a + direct import and invocation forcing `recordWork`, not a type-level hardcode), because both + understated PI-4 as relocation when it is a design. Dropped a claim that + `PhaseRunContext.harnessPrincipal` exists — it does not. Reversed theme 6 to put PI-5 before + PI-4, because drawing a contract from one harness is the abstraction-for-a-set-of-one the + repo rejects. Narrowed §1's necessity claim after review showed conductor's runs are already + observable without the console. +- **After the §3 POC** — rewrote the Kill line as four observable conditions with approval and + ask judged separately, two of them now demonstrated; promoted PI-3 to a hard dependency of + PI-6 on the strength of `hasUI: false` in `--mode json`; and gave theme 5 the host channel's + cross-cutting obligations. From cbd346d369f12d4cf979f85b5043c1dfd3024c67 Mon Sep 17 00:00:00 2001 From: Jake Hoffner Date: Mon, 7 Sep 2026 21:53:24 -0400 Subject: [PATCH 2/7] docs: scope LAB-162 epic to OMP harness and durable human wait --- spec-poc/epic-pi-harness/README.md | 53 +- .../epic-pi-harness/runtime-check/bridge.mjs | 19 + .../omp-native-ask-evidence.json | 87 +++ .../runtime-check/roundtrip-evidence.json | 106 +++ spec/_epics/pi-harness.md | 719 +++++------------- 5 files changed, 427 insertions(+), 557 deletions(-) create mode 100644 spec-poc/epic-pi-harness/runtime-check/bridge.mjs create mode 100644 spec-poc/epic-pi-harness/runtime-check/omp-native-ask-evidence.json create mode 100644 spec-poc/epic-pi-harness/runtime-check/roundtrip-evidence.json diff --git a/spec-poc/epic-pi-harness/README.md b/spec-poc/epic-pi-harness/README.md index 80f01d9235..504283304e 100644 --- a/spec-poc/epic-pi-harness/README.md +++ b/spec-poc/epic-pi-harness/README.md @@ -1,14 +1,49 @@ -# POC — the pi companion channel +# POC evidence — OMP / pi runtime seams -Throwaway. Never merges. Built to falsify the epic's Kill line **before** the objective -gate, because the whole set rests on one unverified pi behaviour. +Throwaway, never merged. The [current epic](../../spec/_epics/pi-harness.md) is +OMP-only and harness-only. Its durable question/approval and same-session continuation +proof remains open. The earlier pi companion investigation below is historical, not +the current design or acceptance claim. -## The question +## Current model-free runtime checks -The epic's Proof and Kill line both assume: **a spawned `pi` run, loaded with a companion -extension via `-e`, can block on a question and get an answer back from the FSD host.** -If that does not hold, a pi harness is a *substitution* for Claude Code rather than an -improvement, and the epic should ship the console (PI-1..3) and stop. +`runtime-check/bridge.mjs` was run unchanged on installed pi 0.85.1 and OMP 18.1.14. +Both emitted `extension_ui_request` with `method: "confirm"`; replying with the same +ID and `confirmed: true` reached the extension callback. Evidence: +`runtime-check/roundtrip-evidence.json`. No model was invoked. + +Launch either executable with `--mode rpc`, a scratch `--session-dir`, and +`-e `. The captured runs disabled discovered +extensions, skills, tools, and project rules/context using each runtime's own flags; +they did not share a launcher configuration. Send newline-terminated JSON over stdin: + +```json +{"id":"ask","type":"prompt","message":"/fsd-probe"} +``` + +Read the emitted confirmation ID, then send `extension_ui_response` with that ID and +`confirmed: true`. After `FSD_PROBE_ANSWER:true`, send a prompt with +`message: "/fsd-probe-history"`; the callback reports `[{"answer":true}]`. +That history is in-memory evidence only. The probe commands did not persist session +files on either runtime; reported session IDs/paths are not a resume proof. + +A separate `omp --mode rpc-ui --tools ask --no-extensions --no-skills --no-rules +--no-lsp --no-title --session-dir ` run, with an isolated +`PI_CODING_AGENT_DIR`, returned `ask` in `get_state.data.dumpTools`. +`runtime-check/omp-native-ask-evidence.json` records the selected response fields. +This checks native tool registration, not an actual model-driven ask. + +These checks remove the need to assume a bespoke HTTP/file-mailbox live-answer +transport. They do **not** prove tool interception, authorization, safe stop, durable +parking, restart-resume, or the full FSD manager loop. Pinned source and the runtime +comparison are in the epic's §3; LAB-164 owns the remaining full-path proof. + +## Original question (superseded) + +The original pi proposal assumed a spawned `pi` run could block on a companion +question and receive an answer from FSD. Its console fallback and live-held worker +wait have since been removed. The retained files and findings below record that +earlier investigation; they do not establish the revised OMP objective. ## What was built @@ -21,7 +56,7 @@ improvement, and the epic should ship the console (PI-1..3) and stop. **Transport is a file mailbox, not a socket.** The authoring sandbox forbids `listen(2)` (`EPERM` on both TCP and a Unix socket). The transport is not what was under test — the *blocking semantics* are — so the rendezvous was swapped and the question preserved. A real -implementation uses a socket or HTTP. +implementation was then assumed to need socket/HTTP; the native RPC findings above supersede that assumption. ## Run it diff --git a/spec-poc/epic-pi-harness/runtime-check/bridge.mjs b/spec-poc/epic-pi-harness/runtime-check/bridge.mjs new file mode 100644 index 0000000000..523556289a --- /dev/null +++ b/spec-poc/epic-pi-harness/runtime-check/bridge.mjs @@ -0,0 +1,19 @@ +export default function (api) { + api.on("session_start", () => console.error("FSD_RPC_PROBE_READY")); + api.registerCommand("fsd-probe", { + description: "Exercise the native RPC UI round trip without a model call", + handler: async (_args, ctx) => { + const answer = await ctx.ui.confirm("FSD bridge probe", "Use staging?", { timeout: 30000 }); + api.appendEntry("fsd-probe-answer", { answer }); + ctx.ui.notify(`FSD_PROBE_ANSWER:${answer}`, "info"); + }, + }); + api.registerCommand("fsd-probe-history", { + description: "Read persisted probe data without a model call", + handler: async (_args, ctx) => { + const entries = ctx.sessionManager.getEntries(); + const found = entries.filter((entry) => entry.type === "custom" && entry.customType === "fsd-probe-answer"); + ctx.ui.notify(`FSD_PROBE_HISTORY:${JSON.stringify(found.map((entry) => entry.data))}`, "info"); + }, + }); +} diff --git a/spec-poc/epic-pi-harness/runtime-check/omp-native-ask-evidence.json b/spec-poc/epic-pi-harness/runtime-check/omp-native-ask-evidence.json new file mode 100644 index 0000000000..db1a1b6aa4 --- /dev/null +++ b/spec-poc/epic-pi-harness/runtime-check/omp-native-ask-evidence.json @@ -0,0 +1,87 @@ +{ + "runtime": "omp/18.1.14", + "mode": "rpc-ui", + "command": "get_state", + "evidenceType": "selected response fields; no model invocation", + "registeredTools": [ + { + "name": "ask", + "parameters": { + "type": "object", + "properties": { + "questions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "question id" + }, + "question": { + "type": "string", + "description": "question text" + }, + "options": { + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "display label" + }, + "description": { + "type": "string", + "description": "optional explanatory text displayed below the label" + }, + "preview": { + "type": "string", + "description": "optional rich preview content for interactive ask dialogs" + } + }, + "required": [ + "label" + ], + "additionalProperties": false + }, + "description": "available options" + }, + "header": { + "type": "string", + "description": "optional short display chip for rich ask dialogs" + }, + "multi": { + "type": "boolean", + "description": "allow multiple selections" + }, + "recommended": { + "type": "number", + "description": "recommended option index" + } + }, + "required": [ + "id", + "question", + "options" + ], + "additionalProperties": false + }, + "minItems": 1, + "description": "questions to ask" + } + }, + "required": [ + "questions" + ], + "additionalProperties": false + } + } + ], + "notProved": [ + "native ask execution", + "tool approval", + "durable park", + "restart and resume" + ] +} diff --git a/spec-poc/epic-pi-harness/runtime-check/roundtrip-evidence.json b/spec-poc/epic-pi-harness/runtime-check/roundtrip-evidence.json new file mode 100644 index 0000000000..ed9c3e301b --- /dev/null +++ b/spec-poc/epic-pi-harness/runtime-check/roundtrip-evidence.json @@ -0,0 +1,106 @@ +{ + "pi": { + "frames": [ + { + "type": "extension_ui_request", + "id": "e6564e70-56ca-4202-adf0-95b2d0ca0ccf", + "method": "confirm", + "title": "FSD bridge probe", + "message": "Use staging?", + "timeout": 30000 + }, + { + "type": "extension_ui_request", + "id": "8dda8796-324b-41df-bef0-e25b4248fdc6", + "method": "notify", + "message": "FSD_PROBE_HISTORY:[]", + "notifyType": "info" + }, + { + "type": "extension_ui_request", + "id": "029d6afa-a7a4-4c27-941b-57e43b22c964", + "method": "notify", + "message": "FSD_PROBE_ANSWER:true", + "notifyType": "info" + }, + { + "id": "ask", + "type": "response", + "command": "prompt", + "success": true + }, + { + "type": "extension_ui_request", + "id": "0f48bafa-5148-4048-b9ff-0c357efba807", + "method": "notify", + "message": "FSD_PROBE_HISTORY:[{\"answer\":true}]", + "notifyType": "info" + }, + { + "id": "history2", + "type": "response", + "command": "prompt", + "success": true + } + ], + "sessionId": "01a07e9e-7e25-7660-9a8d-de430f59257a", + "sessionFile": "/tmp/fsd-runtime-probe/pi-sessions/2026-09-08T01-25-11-333Z_01a07e9e-7e25-7660-9a8d-de430f59257a.jsonl" + }, + "omp": { + "frames": [ + { + "type": "extension_ui_request", + "id": "1576f51298739bdc", + "method": "confirm", + "title": "FSD bridge probe", + "message": "Use staging?", + "timeout": 30000 + }, + { + "id": "ask", + "type": "response", + "command": "prompt", + "success": true + }, + { + "type": "extension_ui_request", + "id": "1576f52991b39bdd", + "method": "notify", + "message": "FSD_PROBE_ANSWER:true", + "notifyType": "info" + }, + { + "type": "prompt_result", + "id": "ask", + "agentInvoked": false + }, + { + "type": "extension_ui_request", + "id": "1576f52991b39bde", + "method": "notify", + "message": "FSD_PROBE_HISTORY:[{\"answer\":true}]", + "notifyType": "info" + }, + { + "type": "extension_ui_request", + "id": "1576f54838b39bdf", + "method": "notify", + "message": "FSD_PROBE_HISTORY:[{\"answer\":true}]", + "notifyType": "info" + }, + { + "id": "history2", + "type": "response", + "command": "prompt", + "success": true + }, + { + "type": "prompt_result", + "id": "history2", + "agentInvoked": false + } + ], + "sessionId": "01a07e9e-7f56-7603-8321-a7804c657984", + "sessionFile": "/tmp/fsd-runtime-probe/omp-sessions/2026-09-08T01-25-11-638Z_01a07e9e-7f56-7603-8321-a7804c657984.jsonl" + } +} \ No newline at end of file diff --git a/spec/_epics/pi-harness.md b/spec/_epics/pi-harness.md index ad8be45d58..de30241aee 100644 --- a/spec/_epics/pi-harness.md +++ b/spec/_epics/pi-harness.md @@ -1,561 +1,184 @@ -# Epic-spec — pi as a harness, and FSD from inside pi - -**In one line:** teach FSD to hand coding work to pi, and teach pi to run FSD flows — so a -board row can be dispatched to an agent that can *stop and ask you something*, and you can -watch and answer from the editor you already have open. - -## The 60-second version - -Today conductor dispatches coding work to Claude Code. That works, but the run is a black -box with a lid: it cannot ask you a question halfway through. Conductor's own `ask.ts` admits -it — the harness "offers no seam for a question, so this ask is forced rather than -spontaneous." The agent has to guess, finish, and be corrected afterwards. - -pi can do better, because pi extensions can intercept a tool call and *block on it*. That -turns a run from a black box into a conversation: - -```text - conductor board row ──dispatch──▶ spawned pi run - │ - "staging or prod DB?" │ (run blocks) - ▼ - you, in your own pi session ◀──── FSD host - │ - └─ "staging" ────────▶ run resumes, PR lands -``` - -**Two directions, one loop.** Direction A is *FSD inside pi*: a `/flow` command, streaming -items, questions surfacing where you already are. Direction B is *pi as harness*: conductor -spawning `pi --mode json` instead of Claude Code. A is the window; B is the engine. The Proof -needs both. - -**Five issues.** PI-1..3 build the operator console (no FSD changes needed at all). PI-5 makes -pi dispatchable *against a contract that already exists* — `@flow-state-dev/core`'s -`HarnessBlock`, drawn by the harness-manager epic from Claude Code and Codex and shipped on -`main`. PI-6 wires the question channel that makes the whole thing worth doing. **PI-4 is -dropped**: it proposed extracting the contract this epic now merely conforms to. See theme 6. - -**Biggest open risk:** a mid-run question has nowhere durable to live — `announce` fires only -*after* the row parks, and in the published `@flow-state-dev/harness-manager` that is a -**stated invariant** rather than an accident of a lab: "After the park, never before. What is -announced must already be answerable" (`manager.ts:1498–1504`). FSD does ship `suspension` / -`suspension_resume` items and a `"suspended"` status, so a bridge is buildable — but PI-6 now -has to argue against a deliberate decision in a shipped package, not fill a gap in a -prototype. §5, first question. Unowned, and worth more than ten minutes before anyone specs -PI-6. - -> **Filing note (delete once the epic issue exists).** This file was drafted on `poc/pi`. -> The convention is `spec/_epics/.md` on branch `epic/pi-harness`, with a never-merged -> epic PR and a Linear parent issue carrying the `Epic` label. Issue IDs below are -> placeholders (`PI-1` … `PI-6`) — replace them with the real Linear IDs when the sub-issues -> are filed, and the `§4` running index becomes live at that point. - ---- - -## How to review this - -*(Paste verbatim into the epic PR description's collapsed `
` block.)* - -This is an **epic-spec**: the shared objective and cross-cutting decisions for a *set* of -issues. It is not an implementation plan and it is not any one issue's design. - -**In scope to challenge:** - -- The objective — is this body of work worth doing, and is the outcome the right one? -- **Whether the set overbuilds.** Each issue can earn its place while the whole is too much. -- A cross-cutting decision in §2 — shared surface, naming, sequencing, contracts. -- A missing issue the objective implies, or one in the set that doesn't serve it. - -**Out of scope — owned by the individual issue specs:** - -- Any single issue's approach, architecture, file layout, or test plan. -- Anything that touches exactly one issue. It belongs on that issue's spec PR. -- **Any POC files on this branch, entirely.** - -Feedback in the second list is routed to the issue it concerns as an implementer note, -not folded in here. - ---- - -## Parts worth reviewing closely - -> **1. §1 — whether this is five issues or three.** The set spans two directions (pi as -> client, pi as harness) and the honest question is whether they are one epic or two. An -> earlier draft justified keeping them together by claiming a harness without the console is -> "a harness nobody can watch"; that was **wrong** — conductor already has run records, -> `status` and an inbox (`labs/conductor/src/manager.ts` 248–263). The set is kept together on -> a narrower claim: the objective is a *loop*, and the Proof requires both ends. If a reviewer -> rejects that, this splits into a console epic and a harness epic joined at PI-3/PI-6. -> -> **2. Theme 1 — two packages, not one.** The opening instinct was a single `packages/pi` -> carrying both halves. It is split on install-model grounds, and this is the decision most -> likely to be re-litigated by an implementer who only sees one half. -> -> **3. Theme 6 — PI-4 is dropped, because the contract already shipped.** Two earlier drafts -> argued about *when* to extract the harness contract and in what order. Both are moot: -> `@flow-state-dev/core`'s `HarnessBlock` / `HarnessRunHandle` landed on `main` out of the -> harness-manager epic, drawn from Claude Code **and Codex**, and `harnessManager` already -> takes a `harness` slot. pi is harness three against an existing contract. This is the -> largest change since the draft that was POC'd — **a reviewer who read the earlier version -> should re-read themes 3, 4 and 6 and §4 rather than skim them.** -> -> **Where I'm unsure:** whether PI-3 survives its own scope-down. It is the weakest issue and -> the POC promoted it from a sequencing preference to a hard dependency of PI-6 (see §3), -> which is the opposite of the direction a weak issue usually travels. - ---- - -## 1. Purpose & objective *(the gated sign-off surface)* - -**Objective.** Make pi a coding harness FSD can dispatch to, and make an FSD flow something -you can run and watch from inside pi. Today the harness slot is Claude Code and nothing else, -and a conductor run's questions are discovered by polling `status` rather than by being asked. -When this epic lands, a board row can be worked by a pi run, and the operator is *told* when -that run needs them. - -> **Package names.** Two artifacts, named here so no issue has to guess: **`packages/pi`** is -> the FSD-side harness (installed by the FSD host; PI-5), and **`packages/pi-extension`** is -> the operator console a developer installs onto their own machine via `pi install` (PI-1..3). -> Names are provisional — §5's single-source option may change how they are *published* — but -> the two-artifact split itself is theme 1's load-bearing decision and does not change. - -**Holistic necessity.** Five issues plus one unowned bridge (§5), and the honest question is -whether it is three. Direction -A (PI-1..3, FSD from inside pi) is independently useful and needs no changes to FSD. Direction -B (PI-5..6, pi as harness) is where the leverage is, and it is **observable without A** — -conductor already carries run records, `status` and a durable inbox. What A adds is that the -operator is *told* rather than having to look. The set is one epic because the objective is -the loop, and the Proof cannot be read off either half alone. The ask seam (PI-6) is what -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 -`announce` hook with no new inbox semantics; if it grows a durable store or a second question -shape, that is the signal it should have been deferred. - -**Proof.** PI-6's goal check, which that issue must produce as a runnable end-to-end check -rather than an assertion: a conductor board row dispatched to the pi harness raises a question -mid-run, the operator is prompted in their own pi session without polling, answers there, and -the run resumes and settles the row. - -**Lead measure.** The set's goal-proven issues, named each report. - -**Kill line.** Judged on four observable conditions, and **approval and spontaneous ask are -judged separately** — one can hold while the other does not, and that leads to a scoped cut -rather than an all-or-nothing verdict. For either seam to count: (a) a spawned run blocks on -it; (b) the block is durably correlated to its conductor issue/phase/attempt; (c) an operator -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. - -**None of the four is yet discharged.** §3's POC removes a *mechanism* risk underneath (a) and -(c) — an awaited pi extension callback can be settled by another process seconds later — but -it never exercised a tool call or an approval interception, so all four remain PI-6's to earn. -Condition (d) must name its bound, not merely assert safety: an unanswered request or a dead -host has to hit a stated deadline that ends the attempt through the existing run timeout and -settles or retries the row. - -**Not doing:** - -- **MCP as the transport.** See theme 2. -- **Embedding `@flow-state-dev/engine` in the pi process.** See theme 2. -- **Defining flows in the extension.** The extension dispatches and renders; it never - defines. The moment flow logic lives in the extension there are two runtimes. -- **A `source: "pi"` inbound transport adapter.** It buys provenance on `RequestRecord.source` - and a place to hang a principal resolver, and neither direction needs it to work. Deferred - deliberately, not forgotten. -- **Renegotiating the harness contract.** `@flow-state-dev/core` already carries it, drawn - from Claude Code and Codex. pi conforms to `HarnessRunInput` / `HarnessRunHandle` and is - installed through `harnessManager`'s existing `harness` slot. If conforming turns out to be - impossible, that is a finding to raise on this PR — not a licence for PI-5 to widen the - contract locally. +# OMP coding runs ask, park, and continue + +OMP cannot yet run under FSD's harness manager. This epic adds it without another +manager or operator console, then connects spontaneous questions and tool approvals +to the existing durable human-wait path. + +**Epic:** [LAB-162](https://linear.app/fixpoint-labs/issue/LAB-162) · +**Review:** [#1612](https://github.com/fixpoint-labs/flow-state-dev/pull/1612), never merged. +The historical branch and file names are retained so existing review links keep working. + +## 1. Purpose & objective + +**Outcome.** A person dispatches an OMP coding run through the harness manager. +When it encounters a real question or needs permission for an action, it asks and +parks. The person answers through the existing operator surface, and a later attempt +continues the same coding conversation rather than starting over. + +The manager already supports multiple harnesses; Claude Code is not its only slot. +Its existing question-marker path already supports asking, parking, and answering. +The gain here is OMP support plus questions and approvals raised at the point the +runtime encounters them—not inventing human wait or claiming other harnesses must guess. + +**Proof.** Dispatch a real OMP run, capture a spontaneous question, durably park the +task and end its attempt, stop the runtime, answer through the existing surface, and +resume the exact saved session. A generated fact learned before the question must +survive without being included in the answer prompt. The run then settles. Separately +exercise a tool approval: no side effect before authorization; denial never authorizes +execution; a later approved action matches what the person authorized. Cancellation, +restart, and a missing resume file must not bypass these conditions. + +**Holistic necessity.** Two issues: [LAB-163](https://linear.app/fixpoint-labs/issue/LAB-163) +provides the OMP harness; [LAB-164](https://linear.app/fixpoint-labs/issue/LAB-164) connects +supervised interactions and owns the full proof. A third transport, console, or +contract-extraction issue adds no necessary capability. An adapter alone is independently +useful, but does not discharge this epic's question-and-resume objective. + +**Lead measure.** Report which parts of that full-path proof have run, against which +OMP version. Model-free RPC compatibility is not a completed outcome. + +**Not doing.** Upstream pi support; a console or FSD flow-running extension inside +pi/OMP; a second inbox or answer verb; a generalized permissions product; worker +`ctx.suspend`; holding a runtime or request open during human wait; a bespoke HTTP +answer channel; a shared pi/OMP abstraction; changes to unrelated harnesses' policy. + +**Kill line.** If OMP cannot safely capture a question/approval, stop and persist the +conversation, then continue it after an answer without executing an unapproved action, +return to the objective gate. Do not substitute live blocking, fresh-session replay, +or adapter-only delivery and call the epic complete. The full sequence is **unproven**. + +**Approval sought.** Approve this outcome and two-issue scope. The owner has selected +harness-only and **OMP first, pi deferred**; those choices do not approve this objective +or either issue's implementation design. OMP-first serves the current operator with +less compatibility work; it delays upstream-pi users. Reopen that choice if those +users become an immediate audience. No implementation starts at this gate. ## 2. Themes & long-horizon direction -> **The themes below are the cross-cutting decisions — the things that would be expensive to -> change once issues start landing. Skim the bold sentence of each; read the body only for -> the ones you want to challenge.** -> -> 1. Two packages, not one · 2. HTTP, not MCP · 3. The event contract is *not* the type I first -> named · 4. Conductor's coupling is concrete *(now history)* · 5. The question channel · -> 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 - extension and the harness are separate packages because they have incompatible install - models: the extension is installed by a *developer onto their own machine* (`pi install`, - landing in `~/.pi/agent/npm/`, with pi's core packages as un-bundled `peerDependencies`), - while the harness is installed by the *FSD host* (`@flow-state-dev/core`, `workspace`, - `zod`). Merging them makes every extension user `npm install` a copy of `core` they never - execute — and pins their extension to a `core` version, which is precisely the coupling - theme 2 chose HTTP to avoid. What the halves genuinely share is the `HarnessEvent` - vocabulary, and that cannot live in a pi package because `claude-code` must satisfy it too - (see theme 3). The division mirrors one the repo already has: `packages/claude-code` is the - 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`.** - Not MCP: the MCP adapter is stateless-by-default with a single JSON result and no SSE, - which discards streaming *and* session continuity — the two properties that make embedding - FSD in an agent worth doing. Not the in-process engine SDK: a pi extension loads via jiti - into a long-running interactive process, and hosting the registry, stores, streaming and - model resolution there means model auth is resolved twice and a flow fault takes the - operator's session with it. (An earlier draft also asserted flow spend never reaches pi's - footer; that was never verified against pi's usage accounting and is dropped rather than - carried as decoration.) The extension owns an - out-of-process host (spawned in `session_start`, torn down in `session_shutdown`) or - attaches to a running one. **No issue in this epic imports `@flow-state-dev/engine` into - the pi process.** - -3. **One harness event vocabulary, derived from `TranslatedEvent` — but not by adopting it - wholesale, and not from `SdkMessageLike`.** - `SdkMessageLike` (`packages/claude-code/src/sdk/types.ts` ~70–160) is explicitly a - "structural subset of the SDK's `SDKMessage` union": Anthropic wire format, carrying - `session_id`, `parent_tool_use_id`, `thinking`/`tool_use` content blocks, and a - `SdkResultSubtype` of Claude's own vocabulary (`error_max_turns`, `error_max_budget_usd`). - It is **not** a neutral vocabulary and must not be lifted. The neutral candidate is the - package's *post-translation* `TranslatedEvent` union (~164–278) — `file_op_observed`, - `plan_item_observed`, `work_gap_observed`, `status`, `error`, normalized `result` — whose - own comment states the point: "by the time this exists the tool names are gone, which is - what keeps the vendor mapping to one site." Even that is not a contract as it stands, for - two reasons: its file-op and plan-item variants encode the Claude work-recorder's semantics, - and **its terminal result still carries `SdkResultSubtype`** (`types.ts:270`) whose values - are Claude's own — `error_max_turns`, `error_max_budget_usd` (`types.ts:13–19`). - - **Both decisions this theme posed have since been made on `main`, and not by this epic.** - The neutral home is `@flow-state-dev/core` (`packages/core/src/types/harness.ts`) — *not* - `contracts`, and the file states why: a block declares a **runtime** schema for its output, - which the zero-dependency layer cannot carry. The neutral terminal type is - `HarnessRunOutcome` — `"finished" | "stopped-at-limit" | "failed"` — with the vendor's - richer reason kept on the vendor's own extension, "so no framework code ever branches on a - vendor string." And work observation is **not** in the contract: `recordWork` stays a - Claude Code option the host passes inside its own slot closure - (`harness-manager/src/manager.ts:245`), so no harness owes it. - - **Translation from vendor messages stays inside each harness** is the one part of this - theme that survives unchanged, and it still binds PI-5. - -4. **The coupling this theme was written to break is already broken — read the rest as - history.** `@flow-state-dev/harness-manager` on `main` "imports no coding agent and reads - no vendor field: the host hands it a factory," and that factory is `HarnessSlot`: - `(feeds: HarnessFeeds) => HarnessBlock`, where the feeds are exactly `cwd`, `resume` and - `onSession`. What follows describes `labs/conductor` as it stood when this was drafted, and - is kept because PI-5's shape is easier to judge against what the coupling *was*. - - The board/checkout/attempt/verdict flow in `manager.ts` is genuinely harness-neutral and - should not be rewritten. But the coupling was concrete, not a type annotation: `manager.ts` - imported `claudeCodeAgent` directly (line 45) and invokes it as a sequencer step (1383–1396), - forcing `detached: true`, `recordWork: true`, and a `cwd` callback, with a result schema - expecting `sessionId`/`finalMessage`/`usage`/`costUsd` (1180–1200). `recordWork: true` means - the manager depends on the Claude integration's **work-observation behaviour**, not just its - terminal status — so the contract must cover normalized terminal result, cancellation, - resume-id semantics across retries, and work observation. An issue that finds itself - changing the manager's *control flow* has hit a cross-cutting question — comment up on this - PR rather than deciding it locally. **PI-5's real job is now much smaller than this theme - implies**: supply a `HarnessSlot` closure that returns a conforming pi block, and let the - published manager own everything else. - -5. **A spawned pi run's question and approval seam is a companion extension, not an in-band - callback — and the channel it speaks is a cross-cutting concern.** - - ```typescript - // The asset the harness ships and loads into the run via `pi -e`. - // Claude Code gets this from the SDK's canUseTool. pi has no in-band - // equivalent — blocking is an extension-side API, so it needs a companion. - pi.on("tool_call", async (event) => { - if (!risky(event.toolName)) return; - const verdict = await host.ask({ tool: event.toolName, input: event.input }); - if (verdict.denied) return { block: true, reason: verdict.why }; // ◀ run stops here - }); - ``` - - Claude Code's SDK exposes - `canUseTool`, which is why `claudeCodeAgent` has `onToolApproval`. pi has no equivalent: its - `tool_call` blocking hook is an *extension-side* API living inside the pi process. So the - harness ships a companion extension as an **asset** (a file loaded into the spawned run via - `pi -e`), which intercepts `tool_call` and registers an ask tool, and calls back to the - dispatching flow. Being an asset rather than a dependency is what keeps the harness package - free of a pi dependency. §3's POC shows an awaited extension callback can be settled by - another process, but did **not** exercise interception or tool execution. **The channel - itself is not a detail PI-6 may invent locally**: it needs an authentication posture that is - per-attempt rather than ambient, run/attempt correlation, cancellation and liveness, and - defined behaviour when either process dies. PI-6 owns it, but it is stated here because a - wrong answer strands paid runs rather than affecting one issue's design. - -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**: - - - `@flow-state-dev/core` (`packages/core/src/types/harness.ts`) owns `HarnessRunInput`, - `HarnessRunEnvelope`, `HarnessRunHandle`, `HarnessBlock`, `HarnessResolver` and - `HarnessSessionHook`. - - `@flow-state-dev/harness-manager` owns the `harness` slot — - `HarnessSlot = (feeds: HarnessFeeds) => HarnessBlock` — plus the run record and inbox. - - `@flow-state-dev/codex` is the proof the contract survives a second vendor. - - **So the sequencing constraints this theme used to impose are gone.** There is no private - seam in `labs/conductor` to keep unexported, no two-invocation-path window to close, and no - "PI-4 cannot be specced until PI-5 has a shape to generalise from." PI-5 writes a - `HarnessSlot` closure returning a pi block whose handle parses against - `harnessRunHandleSchema`, and names itself `pi/cli-json` under the contract's own - `/` convention. - - Three obligations the contract hands PI-5 directly, none of which it may renegotiate: - - - **The prompt is the only block input.** Working directory and resumed session arrive - through `HarnessResolver`s the host feeds, never on the input schema, because that schema - is model-facing through a capability tool preset (BP-031). The resolver is handed `ctx` - and *deliberately not* the input. - - **Abort is not a field.** A conforming harness forwards the block's `ctx.signal` into - whatever cancels the run, and a cancelled run surfaces as a **throw**, not a handle - status. This is load-bearing for Kill-line condition (d). - - **`onSession` fires the moment pi names a session**, during the run and not after it, or - a run that dies mid-flight leaves nothing to resume. - - Sequencing that remains: PI-1 lands first; PI-2 and PI-3 build on its transport. PI-6 - depends on PI-5 and on the §5 mid-run question bridge. PI-1..3 and PI-5 can all be specced - in parallel. - -7. **Trust is decided explicitly, never inherited.** `claude-code` carries `settingSources` - because a checkout the run did not come with can otherwise configure the agent working in - it. pi has the identical hazard with project trust and `.pi/extensions` discovery, and the - identical control (`project_trust`). Any issue that spawns a pi run states its trust - posture rather than defaulting to `defaultProjectTrust`. - -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 - any of the four names the spec used. - - So the policy is: **TUI-only by default, promoted to tool-result `content` by explicit - allowlist.** Defaulting the other way puts `ping` keepalives and `state_snapshot` dumps - into the operator's context window. PI-1 sets the allowlist and PI-2 extends it; no issue - invents a second rule. - - ```text - flow item ─┬─ default (most of 24) ─▶ appendEntry() → operator sees it, LLM does not - └─ allowlisted ─▶ tool result content → both - ``` - -9. **Borrowing pi's auth is possible and probably right for the extension; borrowing it for - the harness is neither.** A probe (`spec-poc/epic-pi-harness/auth-findings.md`) confirmed - `ctx.modelRegistry.getProviderAuth(id)` hands an extension live, actively-refreshed OAuth - credentials (`source: "OAuth"`), that `modelRegistry.complete()` can run inference through - pi's own auth, and that a tool returning `usage` lands in pi's footer and `/session` totals - (`docs/extensions.md:2013`). **The two directions have opposite answers:** - - | | Auth | Usage | - | --- | --- | --- | - | **Harness** (conductor spawns `pi`) | Non-problem. The subprocess resolves its own `auth.json`. | Belongs to conductor's cost record, not a footer. | - | **Extension** (flows run from your session) | Real choice: borrow pi's, or make the host log in separately. | Real opportunity: `usage` on the tool result. | - - So there is **no double-login problem in Direction B** — that intuition, though reasonable, - does not survive contact: a spawned `pi` is already logged in. - - For Direction A, prefer **`complete()` over token-passing**: it keeps the credential inside - the process that owns it. Handing a raw token to a separate host process means it can be - invalidated mid-flow by pi's own refresh, and it puts a secret somewhere its owner cannot - revoke. Whether FSD generators can run on `complete()` at all is unverified and is §5's - question, not a decision this document makes. - -## 3. Shape of the whole *(POC)* - -Three probes, each answering one question. All in `spec-poc/epic-pi-harness/` on this branch, -each with its own findings file. **None of them touch each other — no end-to-end path has -run.** - -| Probe | Question | Verdict | -| --- | --- | --- | -| `probe.ts` + `host.mjs` | Can a pi extension block on a remote answer? | Yes, narrowly — see below | -| `auth-probe.ts` | Can pi's auth and usage be shared with FSD? | Yes; `auth-findings.md` | -| `real-flow.test.ts` | What does a *real* flow actually return? | 2 tests pass; `real-flow-findings.md` | - -**Built:** a stand-in FSD host, a companion extension loaded into a spawned run via `-e`, a -no-LLM mechanics probe, an auth-surface probe, and a real flow driven through the real -`runAction` engine. - -**See it:** `node host.mjs &` then `pi --mode json -e ./probe.ts -p "hi"`; read -`probe-result.json`. The flow test runs from `packages/testing` (see its findings file for -why). - -**Showed — stated narrowly, because the first write-up of this POC over-claimed it.** Three -facts: a `-e` extension loads in a headless `--mode json` run; it registers a tool that is -visible to the run (`flow_ask` among 57); and an awaited extension callback stays pending -across a 2136ms cross-process round trip and resolves with the host's answer intact. The last -is the property that matters — a pending promise inside a pi extension can be settled by -another process seconds later — and the file-mailbox transport does not weaken it, since -`await` semantics do not depend on whether the bytes arrive over a socket or a file. - -**What it did NOT show, despite an earlier draft of this section claiming otherwise:** the -probe calls the host *directly from its `session_start` listener*, not through the `flow_ask` -`execute()` handler. No `tool_call` event is ever raised, so **`companion.ts`'s approval -interceptor was never exercised**, and the ask tool was never shown to block a real agent -turn. Tool *registration* is not tool *execution*. The model-driven path failed entirely (no -outbound network in the authoring sandbox). pi's docs independently state that `tool_call` -can block (`docs/extensions.md` 778–793), but that is documentation, not demonstration. - -It also showed `ctx.hasUI` is **false** in `--mode json`: the companion cannot prompt through -pi's own UI inside a spawned run. - -**The other two probes did more damage to the spec than the first one did good**, which is -the argument for having run them: - -- The **auth probe** killed a plausible assumption (that a pi harness would force a second - login) and opened a real design choice for the extension direction. Theme 9. -- The **real-flow probe** caught the spec inventing FSD's own vocabulary: theme 8's item - routing named four item types that do not exist, against a real union of 24. It also found - `suspension` / `suspension_resume` items and a `"suspended"` status, which may mean §5's - blocking question is already answered by the substrate. - -**Changed:** the Kill line became four observable conditions with approval and ask judged -separately — but *none* of the four is discharged by this POC; it removes a mechanism risk -underneath (a) and (c) rather than satisfying them. Theme 5 gained the channel's -cross-cutting obligations, which the probe made conspicuous by deliberately having none. And -the mid-run question bridge (§5) was found only because `hasUI: false` forced the question of -where a live question actually goes — which turned out to be the epic's real hole. +1. **One human-wait model.** Preserve + [FIX-1241 / D-1](https://linear.app/fixpoint-labs/issue/FIX-1241) + ([decision record #1429](https://github.com/fixpoint-labs/flow-state-dev/issues/1429)): + a question becomes durable, the task parks, the worker request ends, and the existing + answer/unblock path starts a later attempt. `announce` follows parking. The runtime + adapter supplies evidence; the manager remains authoritative for task and inbox state. + A live RPC dialog is only a runtime seam, not durable human wait. + +2. **One operator surface.** Preserve + [FIX-1309 / D-9](https://linear.app/fixpoint-labs/issue/FIX-1309) + ([decision record #1562](https://github.com/fixpoint-labs/flow-state-dev/issues/1562)). + Consume the existing manager/Conductor surface and its notification path. The earlier + proposal's operator-console work is removed, not a fallback if the harness proof fails. + [LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) owns the related operator work; + this epic does not reopen that scope or require a second shell. + +3. **Conform to the shipped harness contract.** `packages/core/src/types/harness.ts` + owns the contract, and `packages/harness-manager` owns the slot and manager policy. + Keep model-visible input prompt-only; cwd, resume, and other run configuration use + the trusted channel. Report session identity through `onSession` during the run. + User cancellation throws; do not translate it into successful parking. Respect + `HarnessRunOutcome`, not process exit or RPC acknowledgement as a substitute. + Any contract change required by both issues must come back here before either assumes it. + +4. **OMP is a runtime, not a renamed pi executable.** Use OMP's native integration + seams rather than port the old file-mailbox companion. Source inspection identifies + `--mode rpc-ui` as the native-ask path; plain `rpc` supports extension dialogs but does + not enable the native ask tool. Installed OMP 18.1.14 registered `ask` in `rpc-ui` in + the local probe. Keep runtime translation inside the OMP harness. The public package + name and adapter API belong to LAB-163's spec, not to a speculative two-runtime layer. + +5. **Conversation identity survives; pending UI promises do not.** Both inspected + runtimes keep outstanding RPC UI requests in process memory. An old UI response ID + cannot be answered after restart. The manager's durable answer must continue the + recorded conversation in a new attempt. Resume lookup must fail closed on missing, + corrupt, or mismatched material, because the runtimes can otherwise create a new + session at an explicit missing path. Neither a reported path nor an in-memory ID + proves that resumable history has been persisted. + +6. **Questions and approvals share delivery, not meaning.** A selection dialog may + represent an ask, a tool approval, or an extension UI. Capture its real origin and + bind an approval to the action and attempt presented to the operator. No side effect + before consent, no blanket permission inferred from an answer, and no success inferred + from cancellation. Do not invent a second question service or weaken existing answer + correlation. LAB-164 owns the exact mapping and the pre-execution/restart proof. + +7. **Prove the risky boundary before committing the production design.** LAB-164's + bounded feasibility POC precedes finalizing either issue's affected interface. After + their own spec approvals, LAB-163 implements the adapter first and LAB-164 builds on + it. LAB-164 is blocked by LAB-163 for delivery, not forbidden from investigating the + shared premise first. A failed safe-stop/persistence proof reopens the epic rather + than creating an unplanned suspension or transport issue. + +## 3. Shape of the whole + +**Built:** the original throwaway pi probes, plus a model-free RPC dialog probe run on +installed pi 0.85.1 and OMP 18.1.14; a separate OMP `rpc-ui` registration check. +**See:** [POC record](../../spec-poc/epic-pi-harness/README.md) and its `runtime-check/` evidence. +**Showed:** both answered the same extension confirmation over stdio; OMP exposed native +`ask` in `rpc-ui`. No model/tool approval, durable park, restart-resume, or assembled manager +loop was proved. The model-free commands did not persist session files in either runtime. +**Changed:** choose OMP first; remove console work, the bespoke answer transport, and +live-held human wait. Keep the full-path proof as an explicit requirement, not a claimed result. + +
+Runtime comparison and evidence boundaries + +| Concern | OMP | Upstream pi | Evidence | +|---|---|---|---| +| Headless control | `rpc` and `rpc-ui` over stdio | `rpc` over stdio | Source; both launched locally | +| Spontaneous ask | Native `ask`, enabled in `rpc-ui` | No native ask; a registered question tool is needed | Source; OMP registration checked locally | +| Extension confirmation | `extension_ui_request` / response | Same round-trip shape | Executed locally on both | +| Saved-session continuation | Explicit file + later prompt | Explicit file + later prompt | Source only; no restart-resume proof here | +| Terminal completion and cancellation | OMP-specific events and lifecycle | Pi-specific events and lifecycle | Source; not interchangeable | +| Durable human wait | Manager must own it | Manager must own it | Pending RPC maps are process-local | + +Pinned source: OMP +[`daf07999`](https://github.com/can1357/oh-my-pi/tree/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e) +and pi +[`b2602be7`](https://github.com/earendil-works/pi/tree/b2602be77cb7b0de45dd616407fd210daa48aa75). +The inspected manifests report 18.1.14 and 0.85.1 respectively; matching version strings +are not proof that an installed release contains every inspected main-branch change. + +Primary references: [OMP RPC](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/docs/rpc.md), +[OMP CLI setup](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/main.ts), +[OMP ask](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/tools/ask.ts), +[OMP sessions](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/session/session-manager.ts), +[pi RPC](https://github.com/earendil-works/pi/blob/b2602be77cb7b0de45dd616407fd210daa48aa75/packages/coding-agent/docs/rpc.md), +and [pi sessions](https://github.com/earendil-works/pi/blob/b2602be77cb7b0de45dd616407fd210daa48aa75/packages/coding-agent/src/core/session-manager.ts). + +
## 4. Running index | 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 | -| PI-2 | SSE item streaming and flow-session continuity across pi sessions and forks | spec | — | — | Needs spec | -| PI-3 | `announce` → pi: questions surface in the operator's UI, answered from there | spec | — | — | Needs spec | -| PI-5 | `packages/pi`: `piAgent` conforming to core's `HarnessBlock`, over `pi --mode json`, installed through `harnessManager`'s `harness` slot | spec | — | — | Needs spec | -| PI-6 | Companion extension: approval interception, the ask seam, and the host channel | spec | — | — | Needs spec | -| ~~PI-4~~ | ~~Harness contract extracted from *two* implementations~~ — **dropped**, shipped by the harness-manager epic (`@flow-state-dev/core`, `@flow-state-dev/codex`) | — | — | — | Not filed | +|---|---|---|---|---|---| +| [LAB-163](https://linear.app/fixpoint-labs/issue/LAB-163) | Dispatch, observe, cancel, resume OMP through the existing contract | spec | — | — | Backlog; epic approval pending | +| [LAB-164](https://linear.app/fixpoint-labs/issue/LAB-164) | Spontaneous questions, tool approvals, durable wait, integrated proof | spec | — | — | Backlog; delivery blocked by LAB-163 | + +Related, not duplicated: [LAB-140](https://linear.app/fixpoint-labs/issue/LAB-140) +(harness manager), [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154) +(manager packaging and session continuation), and +[LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) (operator board). +No existing Linear epic for this pi/OMP proposal was found; LAB-162 and its two children +replace the draft's placeholder PI issue numbers. They share the Development Workflow +Orchestration project and the OMP question-and-resume proof milestone. ## 5. Open cross-cutting questions -- **Does the operator extension need `@flow-state-dev/client` at all, or should it speak raw - `fetch` + SSE?** Raised while scoping PI-1. `client` is isomorphic and already implements - `Last-Event-ID` resume, which maps onto a pi restart for free — that is the argument for - taking the dependency. The argument against is that it is the extension's *only* FSD - dependency, and dropping it would make the extension version-independent of the whole - framework. Blocks nothing; PI-1 proceeds on "use `client`" and folds if resume turns out to - be the only thing it was carrying. - -- **Is the extension published to npm, or installed from git/local path?** Raised while - scoping PI-1. `pi install` accepts `npm:`, `git:` and local paths, so a v1 can ship without - answering it. Publishing brings the extension under the repo's changeset discipline and - makes it a supported surface; git/local keeps it internal while the shape settles. - Recommend deferring publication until PI-3 lands, since the console is not useful to anyone - else until it can carry a question. - -- **In-process pi SDK, or `pi --mode json` subprocess, for PI-5?** Raised while scoping the - harness. The subprocess is sequenced first (theme 6 names it) because it matches how - the manager already treats a run as something that happens in a checkout it owns, and because - isolation is worth more than latency for a paid coding run. The in-process route mirrors - `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, - and harder than the earlier draft thought.** The largest remaining hole, and re-cited: the - post-park announce is no longer a lab's accident but a **stated invariant of a published - package**. `@flow-state-dev/harness-manager` calls `board.awaitReview(...)` and only then - `announce({ question })` (`manager.ts:1498–1504`), with the reason written beside it: - "After the park, never before. What is announced must already be answerable: a subscriber - fast enough to act on an announcement sent earlier…". But `flow_ask` blocks **during** a - live run. PI-3 is scoped to the existing announce path with no new inbox semantics, so - **PI-3 as specced cannot carry a live question** — and PI-6 must now argue against a - deliberate decision in a shipped package rather than fill a prototype's gap. - - **Check this before designing anything.** The real item vocabulary contains `suspension` and - `suspension_resume`, and `testFlow` already reports a `"suspended"` terminal status - (`spec-poc/epic-pi-harness/real-flow-findings.md`). FSD may already have the durable - suspend/resume primitive this question assumes must be built. If it does, the answer is to - *use* it rather than invent a second question shape, and this stops being a design question - and becomes a wiring one. - - If it does not, someone must decide: does a mid-run ask create a durable conductor question - immediately (reusing the park/announce path, at the cost of parking a still-running - attempt), or stay live on the companion channel with separate notification (at the cost of a - second question shape and no durability if the host dies)? Plus who assigns - issue/phase/attempt correlation, and who owns cancellation. This decides PI-3's real scope - and PI-6's feasibility, so it should be resolved **before** the objective gate. - - **What the delivery half costs is now known, and it is cheap.** Whatever the durable answer - turns out to be, reaching the operator does not need a new pi mechanism. A pi extension can - hold a background poll or subscription started in `session_start` and injected with - `pi.sendMessage(..., { deliverAs })`, where `"steer"` delivers **after the current assistant - turn finishes its tool calls, before the next LLM call** — mid-run, without waiting for the - agent to settle — and `"followUp"` waits for it to settle. `triggerTurn: true` wakes an idle - session. `docs/extensions.md` (`pi.sendMessage`, and the `file-trigger.ts` example, which is - this shape end to end). So **the operator console is not limited to park-time delivery**, - and PI-3 does not have to solve durability to be useful. That does not close this question, - which is about where the question durably *lives* and who correlates it — only about how it - reaches a watching human once it exists. - -- **One source package with two publishable artifacts, instead of two packages?** Raised by - epic review. A single source location could emit a thin pi-package manifest for the extension - and a separate npm entry for the harness, sharing build tooling but not install dependencies - — preserving one ownership location while keeping the runtime split theme 1 requires. It may - collapse back to theme 1 in practice, since `pi install` resolves an npm package name and so - the extension needs its own manifest regardless. Blocks nothing; theme 1's *runtime/install* - split is the load-bearing part and holds either way. A simpler interim: run the extension as - a project-local `.pi/extensions` entry during validation and defer publishing entirely. - -- ~~**Where does the neutral harness contract live — `contracts`, or a new - `packages/harness`?**~~ **Answered on `main`, by the harness-manager epic, not by this - one.** It lives in `@flow-state-dev/core` (`packages/core/src/types/harness.ts`), and the - reason rules out the option this question favoured: a block declares a **runtime** schema - for its output, which the zero-dependency `contracts` layer cannot carry. PI-5 and PI-6 - import from `core`. - ---- +- **Can safe capture → stop → persist → answer → same-session continuation satisfy both + questions and approvals?** Open empirical premise, owned by LAB-164's feasibility POC + with LAB-163. Blocks committing the affected production design. Test orderly parking + separately from user abort, including blocked-tool cancellation and process shutdown; + a working UI round trip does not settle it. +- **Runtime audience?** Resolved by owner: OMP first; upstream pi deferred. Reopen for an + immediate pi audience, not because the protocol names look alike. +- **Console and human-wait model?** Console removed by owner scope choice; existing + park/end-request/answer model retained under D-1 and D-9. No issue may reopen either locally. ## Epic evolution -- **After reconciling against `main` (7 Sep)** — the spec was drafted blind to the - harness-manager epic, which shipped the thing PI-4 proposed to build. `packages/codex` and - `packages/harness-manager` are on `main`; the neutral contract is in `@flow-state-dev/core`, - drawn from Claude Code and Codex; `harnessManager` takes a `HarnessSlot`. **Dropped PI-4** - and rewrote theme 6 around conforming rather than extracting, with the three obligations the - contract imposes on PI-5 (prompt-only input, abort-as-throw, `onSession` during the run). - Closed theme 3's two open decisions and §5's neutral-home question — all three were answered - on `main`, none by this epic. Re-cited theme 4 as history and the mid-run question bridge to - `harness-manager/src/manager.ts:1498–1504`, where post-park announce is a **stated - invariant** rather than a prototype's gap, which makes PI-6 harder than the previous draft - assumed. Added the one piece of good news: `pi.sendMessage`'s `deliverAs: "steer"` delivers - between turns of a live run, so the console is not limited to park-time delivery. - -- **After two more probes** — ran an auth probe and a *real* flow through the real `runAction` - engine, having previously tested only against a mock host. Added theme 9 (auth/usage - borrowing: no double-login exists for the harness direction; `complete()` preferred over - token-passing for the extension). Rewrote theme 8 after the real item union turned out to - have 24 types, none of them the four the spec had invented — routing is now an allowlist - with a TUI-only default. Flagged in §5 that `suspension`/`suspension_resume` items and a - `"suspended"` status already exist, so the mid-run question may be wiring, not design. - Added an executive summary and diagrams after the spec was called unreadable. -- **After the POC was re-reviewed** — corrected §3, which over-claimed its own probe: the probe - calls the host from `session_start`, never through the tool's `execute()`, so no `tool_call` - fires and the approval interceptor was never exercised. Kill-line conditions (a) and (c) went - back to undischarged. Found that `TranslatedEvent`'s terminal result still carries - `SdkResultSubtype`, so theme 3 owes a neutral outcome type too. Added PI-5's private-seam and - single-invocation-path constraints. Opened the mid-run question bridge in §5 after finding - `announce` fires only *after* `board.awaitReview` (`manager.ts:1244`), so PI-3 as scoped - cannot carry a live question. -- **Epic drafted** — six issues across two directions under one outcome: pi is a harness FSD - can dispatch to, and an FSD run is something an operator can watch. Split the proposed single - `packages/pi` into two packages after the install models turned out to be incompatible, and - scoped PI-3 down to wiring the existing `announce` hook with no new inbox semantics. -- **After epic review** — corrected theme 3 (the neutral vocabulary is `TranslatedEvent`, not - `SdkMessageLike`, which is Anthropic wire format) and theme 4 (conductor's coupling is a - direct import and invocation forcing `recordWork`, not a type-level hardcode), because both - understated PI-4 as relocation when it is a design. Dropped a claim that - `PhaseRunContext.harnessPrincipal` exists — it does not. Reversed theme 6 to put PI-5 before - PI-4, because drawing a contract from one harness is the abstraction-for-a-set-of-one the - repo rejects. Narrowed §1's necessity claim after review showed conductor's runs are already - observable without the console. -- **After the §3 POC** — rewrote the Kill line as four observable conditions with approval and - ask judged separately, two of them now demonstrated; promoted PI-3 to a hard dependency of - PI-6 on the strength of `hasUI: false` in `--mode json`; and gave theme 5 the host channel's - cross-cutting obligations. +- **Original draft** — pi harness plus an in-editor operator console and live question channel. +- **Four-lens review** — found conflicts with D-1/D-9, a stale Claude-only baseline, and + unsupported live-wait assumptions; synced the branch with the shipped harness substrate. +- **Owner scope choices and runtime research** — harness-only, OMP first, pi deferred; + replaced five placeholder work items with LAB-163 → LAB-164 under LAB-162 and made the + missing durable interaction proof explicit. Objective approval remains pending. From 361835bcee402a7c68f65224fef2904ade516d9d Mon Sep 17 00:00:00 2001 From: Jake Hoffner Date: Tue, 8 Sep 2026 07:48:58 -0400 Subject: [PATCH 3/7] docs: narrow LAB-162 to questions and name trusted handoff --- spec-poc/epic-pi-harness/README.md | 2 +- .../runtime-check/roundtrip-evidence.json | 4 + spec/_epics/pi-harness.md | 113 ++++++++++-------- 3 files changed, 71 insertions(+), 48 deletions(-) diff --git a/spec-poc/epic-pi-harness/README.md b/spec-poc/epic-pi-harness/README.md index 504283304e..c9b9747710 100644 --- a/spec-poc/epic-pi-harness/README.md +++ b/spec-poc/epic-pi-harness/README.md @@ -1,7 +1,7 @@ # POC evidence — OMP / pi runtime seams Throwaway, never merged. The [current epic](../../spec/_epics/pi-harness.md) is -OMP-only and harness-only. Its durable question/approval and same-session continuation +OMP-only and harness-only. Its durable question and same-session continuation proof remains open. The earlier pi companion investigation below is historical, not the current design or acceptance claim. diff --git a/spec-poc/epic-pi-harness/runtime-check/roundtrip-evidence.json b/spec-poc/epic-pi-harness/runtime-check/roundtrip-evidence.json index ed9c3e301b..ab6b249e79 100644 --- a/spec-poc/epic-pi-harness/runtime-check/roundtrip-evidence.json +++ b/spec-poc/epic-pi-harness/runtime-check/roundtrip-evidence.json @@ -44,6 +44,8 @@ } ], "sessionId": "01a07e9e-7e25-7660-9a8d-de430f59257a", + "sessionFilePresent": false, + "sessionFileCheck": "Post-stop filesystem stat returned ENOENT", "sessionFile": "/tmp/fsd-runtime-probe/pi-sessions/2026-09-08T01-25-11-333Z_01a07e9e-7e25-7660-9a8d-de430f59257a.jsonl" }, "omp": { @@ -101,6 +103,8 @@ } ], "sessionId": "01a07e9e-7f56-7603-8321-a7804c657984", + "sessionFilePresent": false, + "sessionFileCheck": "Post-stop filesystem stat returned ENOENT", "sessionFile": "/tmp/fsd-runtime-probe/omp-sessions/2026-09-08T01-25-11-638Z_01a07e9e-7f56-7603-8321-a7804c657984.jsonl" } } \ No newline at end of file diff --git a/spec/_epics/pi-harness.md b/spec/_epics/pi-harness.md index de30241aee..61c847693f 100644 --- a/spec/_epics/pi-harness.md +++ b/spec/_epics/pi-harness.md @@ -1,7 +1,7 @@ # OMP coding runs ask, park, and continue OMP cannot yet run under FSD's harness manager. This epic adds it without another -manager or operator console, then connects spontaneous questions and tool approvals +manager or operator console, then connects spontaneous questions to the existing durable human-wait path. **Epic:** [LAB-162](https://linear.app/fixpoint-labs/issue/LAB-162) · @@ -11,47 +11,47 @@ The historical branch and file names are retained so existing review links keep ## 1. Purpose & objective **Outcome.** A person dispatches an OMP coding run through the harness manager. -When it encounters a real question or needs permission for an action, it asks and -parks. The person answers through the existing operator surface, and a later attempt +When it encounters a real question, it asks and parks. The person answers through +the existing operator surface, and a later attempt continues the same coding conversation rather than starting over. The manager already supports multiple harnesses; Claude Code is not its only slot. -Its existing question-marker path already supports asking, parking, and answering. -The gain here is OMP support plus questions and approvals raised at the point the -runtime encounters them—not inventing human wait or claiming other harnesses must guess. +Its question-marker path already supports prompted asking, parking, and answering, +but has no trusted handoff for a runtime-captured question. This epic must supply that +handoff—not infer that spontaneous ask is already wired or invent another human-wait model. **Proof.** Dispatch a real OMP run, capture a spontaneous question, durably park the task and end its attempt, stop the runtime, answer through the existing surface, and resume the exact saved session. A generated fact learned before the question must -survive without being included in the answer prompt. The run then settles. Separately -exercise a tool approval: no side effect before authorization; denial never authorizes -execution; a later approved action matches what the person authorized. Cancellation, -restart, and a missing resume file must not bypass these conditions. +survive without being included in the answer prompt. The run then settles. +User cancellation must remain cancellation. Missing or mismatched resume data must +fail rather than silently start a fresh conversation. **Holistic necessity.** Two issues: [LAB-163](https://linear.app/fixpoint-labs/issue/LAB-163) provides the OMP harness; [LAB-164](https://linear.app/fixpoint-labs/issue/LAB-164) connects -supervised interactions and owns the full proof. A third transport, console, or -contract-extraction issue adds no necessary capability. An adapter alone is independently +questions and owns the shared handoff and full proof. Keep that work within the two +issues; no separate transport, console, or contract-extraction project. An adapter alone is independently useful, but does not discharge this epic's question-and-resume objective. **Lead measure.** Report which parts of that full-path proof have run, against which OMP version. Model-free RPC compatibility is not a completed outcome. **Not doing.** Upstream pi support; a console or FSD flow-running extension inside -pi/OMP; a second inbox or answer verb; a generalized permissions product; worker +pi/OMP; a second inbox or answer verb; operator-approved tool execution; worker `ctx.suspend`; holding a runtime or request open during human wait; a bespoke HTTP answer channel; a shared pi/OMP abstraction; changes to unrelated harnesses' policy. -**Kill line.** If OMP cannot safely capture a question/approval, stop and persist the -conversation, then continue it after an answer without executing an unapproved action, -return to the objective gate. Do not substitute live blocking, fresh-session replay, +**Kill line.** If OMP cannot do all of the following—safely capture a question, stop +and persist the conversation, and continue that exact session after an answer—return +to the objective gate. Do not substitute live blocking, fresh-session replay, or adapter-only delivery and call the epic complete. The full sequence is **unproven**. **Approval sought.** Approve this outcome and two-issue scope. The owner has selected -harness-only and **OMP first, pi deferred**; those choices do not approve this objective -or either issue's implementation design. OMP-first serves the current operator with -less compatibility work; it delays upstream-pi users. Reopen that choice if those -users become an immediate audience. No implementation starts at this gate. +harness-only, **OMP first, pi deferred**, and **questions first, tool approvals deferred**. +These choices do not approve this objective or either issue's implementation design. +The smaller scope delays pi users and operator-controlled tool execution; reconsider +when either is an immediate need. Tool permissions remain the host's configured policy. +No implementation starts at this gate. ## 2. Themes & long-horizon direction @@ -62,14 +62,23 @@ users become an immediate audience. No implementation starts at this gate. answer/unblock path starts a later attempt. `announce` follows parking. The runtime adapter supplies evidence; the manager remains authoritative for task and inbox state. A live RPC dialog is only a runtime seam, not durable human wait. - -2. **One operator surface.** Preserve - [FIX-1309 / D-9](https://linear.app/fixpoint-labs/issue/FIX-1309) - ([decision record #1562](https://github.com/fixpoint-labs/flow-state-dev/issues/1562)). - Consume the existing manager/Conductor surface and its notification path. The earlier - proposal's operator-console work is removed, not a fallback if the harness proof fails. - [LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) owns the related operator work; - this epic does not reopen that scope or require a second shell. + Classify dialog origin: tool approvals and extension UI are not operator questions. + Non-question permission prompts follow the host's configured allow/deny policy; + they do not enter this epic's parked-question path. + +2. **One trusted question handoff, currently missing.** The manager's existing intake + reads an attempt-keyed ask marker after the harness returns; it parks only when the + handle is `completed` and that attempt has a question. Throw, user cancellation, + deadline abort, or a non-completed handle does not take that park arm. A runtime + stop therefore cannot be relabeled as completion just to make parking happen. + LAB-164 owns the handoff from captured question to this intake and specifies it + jointly with LAB-163 before either affected interface is finalized. The manager + must provide the attempt-correlated destination through a trusted path or callback: + no prompt parsing, invented fixed filename, or question hidden in `finalMessage`. + The POC first tests preserving the single marker intake plus an orderly completed + harness step. If that is not honest or viable, a change to the harness contract + **or manager question intake** returns to this epic before either issue assumes it. + This is explicit integration work in the two-issue set, not a seam claimed to exist. 3. **Conform to the shipped harness contract.** `packages/core/src/types/harness.ts` owns the contract, and `packages/harness-manager` owns the slot and manager policy. @@ -77,13 +86,15 @@ users become an immediate audience. No implementation starts at this gate. the trusted channel. Report session identity through `onSession` during the run. User cancellation throws; do not translate it into successful parking. Respect `HarnessRunOutcome`, not process exit or RPC acknowledgement as a substitute. - Any contract change required by both issues must come back here before either assumes it. + The handoff in theme 2 is shared work; any other harness-contract or manager-intake + change must come back here before either issue assumes it. 4. **OMP is a runtime, not a renamed pi executable.** Use OMP's native integration seams rather than port the old file-mailbox companion. Source inspection identifies `--mode rpc-ui` as the native-ask path; plain `rpc` supports extension dialogs but does - not enable the native ask tool. Installed OMP 18.1.14 registered `ask` in `rpc-ui` in - the local probe. Keep runtime translation inside the OMP harness. The public package + not enable the native ask tool. Installed OMP 18.1.14 registered `ask` in a local + `rpc-ui --tools ask` probe; the mode distinction rests on source inspection, + not a local negative control. Keep runtime translation inside the OMP harness. The public package name and adapter API belong to LAB-163's spec, not to a speculative two-runtime layer. 5. **Conversation identity survives; pending UI promises do not.** Both inspected @@ -94,14 +105,7 @@ users become an immediate audience. No implementation starts at this gate. session at an explicit missing path. Neither a reported path nor an in-memory ID proves that resumable history has been persisted. -6. **Questions and approvals share delivery, not meaning.** A selection dialog may - represent an ask, a tool approval, or an extension UI. Capture its real origin and - bind an approval to the action and attempt presented to the operator. No side effect - before consent, no blanket permission inferred from an answer, and no success inferred - from cancellation. Do not invent a second question service or weaken existing answer - correlation. LAB-164 owns the exact mapping and the pre-execution/restart proof. - -7. **Prove the risky boundary before committing the production design.** LAB-164's +6. **Prove the risky boundary before committing the production design.** LAB-164's bounded feasibility POC precedes finalizing either issue's affected interface. After their own spec approvals, LAB-163 implements the adapter first and LAB-164 builds on it. LAB-164 is blocked by LAB-163 for delivery, not forbidden from investigating the @@ -152,27 +156,39 @@ and [pi sessions](https://github.com/earendil-works/pi/blob/b2602be77cb7b0de45dd | Issue | What it delivers | Route | Spec PR | Impl PR | State | |---|---|---|---|---|---| | [LAB-163](https://linear.app/fixpoint-labs/issue/LAB-163) | Dispatch, observe, cancel, resume OMP through the existing contract | spec | — | — | Backlog; epic approval pending | -| [LAB-164](https://linear.app/fixpoint-labs/issue/LAB-164) | Spontaneous questions, tool approvals, durable wait, integrated proof | spec | — | — | Backlog; delivery blocked by LAB-163 | +| [LAB-164](https://linear.app/fixpoint-labs/issue/LAB-164) | Spontaneous questions, trusted handoff, durable wait, integrated proof | spec | — | — | Backlog; delivery blocked by LAB-163 | Related, not duplicated: [LAB-140](https://linear.app/fixpoint-labs/issue/LAB-140) -(harness manager), [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154) -(manager packaging and session continuation), and -[LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) (operator board). +owns the manager program; [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154) +owns its packaging and manager-side session association. LAB-163 supplies OMP's side +of `resume`/`onSession`; it does not redo that manager work. +[LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) owns the operator board. +[FIX-1246](https://linear.app/fixpoint-labs/issue/FIX-1246) is the standing substrate +same-session POC. LAB-164 adds OMP-specific capture/stop evidence and must reuse its +continuity standard, not claim to close or supersede that broader issue. Restarting +a process is an adversarial condition here, **not** proof: the same session identity +and generated fact must survive. No fresh-session success satisfies D-1 or FIX-1246. + No existing Linear epic for this pi/OMP proposal was found; LAB-162 and its two children replace the draft's placeholder PI issue numbers. They share the Development Workflow Orchestration project and the OMP question-and-resume proof milestone. ## 5. Open cross-cutting questions -- **Can safe capture → stop → persist → answer → same-session continuation satisfy both - questions and approvals?** Open empirical premise, owned by LAB-164's feasibility POC - with LAB-163. Blocks committing the affected production design. Test orderly parking +- **Can the trusted handoff and safe capture → stop → persist → answer → same-session + continuation work?** Open empirical premise, owned by LAB-164's feasibility POC + with LAB-163 under theme 2. Blocks committing the affected production design. Test orderly parking separately from user abort, including blocked-tool cancellation and process shutdown; a working UI round trip does not settle it. - **Runtime audience?** Resolved by owner: OMP first; upstream pi deferred. Reopen for an immediate pi audience, not because the protocol names look alike. - **Console and human-wait model?** Console removed by owner scope choice; existing - park/end-request/answer model retained under D-1 and D-9. No issue may reopen either locally. + park/end-request/answer model retained under [D-1](https://linear.app/fixpoint-labs/issue/FIX-1241). + [D-9](https://linear.app/fixpoint-labs/issue/FIX-1309) + ([record #1562](https://github.com/fixpoint-labs/flow-state-dev/issues/1562)) retains + the existing operator surface. No issue may reopen either locally. +- **Tool authorization?** Resolved by owner after restraint review: questions first; + operator-approved tool execution deferred. It is a separate outcome, not free delivery plumbing. ## Epic evolution @@ -182,3 +198,6 @@ Orchestration project and the OMP question-and-resume proof milestone. - **Owner scope choices and runtime research** — harness-only, OMP first, pi deferred; replaced five placeholder work items with LAB-163 → LAB-164 under LAB-162 and made the missing durable interaction proof explicit. Objective approval remains pending. +- **Final review and owner cut** — removed tool approvals; named the missing trusted + question handoff and its completed-handle gate; reconciled FIX-1246. Deferred the + exact handoff design to the joint feasibility check rather than assuming it shipped. From e48498a55b186e174851ec32ebdcdb5af6411c6e Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 16 Sep 2026 21:48:02 +0000 Subject: [PATCH 4/7] docs: rewrite LAB-162 epic-spec as the four-document set MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_0125zR5sy7YdPsbrrtzQ1dKf --- spec-poc/epic-pi-harness/README.md | 9 +- spec/_epics/pi-harness.md | 203 ------------------- spec/_epics/pi-harness/BUSINESS-RULES.md | 53 +++++ spec/_epics/pi-harness/DECISIONS.md | 175 ++++++++++++++++ spec/_epics/pi-harness/PLAN.md | 79 ++++++++ spec/_epics/pi-harness/SPEC.md | 125 ++++++++++++ spec/_epics/pi-harness/figures/end-state.svg | 66 ++++++ spec/_epics/pi-harness/figures/ownership.svg | 118 +++++++++++ spec/_epics/pi-harness/figures/path.svg | 93 +++++++++ 9 files changed, 715 insertions(+), 206 deletions(-) delete mode 100644 spec/_epics/pi-harness.md create mode 100644 spec/_epics/pi-harness/BUSINESS-RULES.md create mode 100644 spec/_epics/pi-harness/DECISIONS.md create mode 100644 spec/_epics/pi-harness/PLAN.md create mode 100644 spec/_epics/pi-harness/SPEC.md create mode 100644 spec/_epics/pi-harness/figures/end-state.svg create mode 100644 spec/_epics/pi-harness/figures/ownership.svg create mode 100644 spec/_epics/pi-harness/figures/path.svg diff --git a/spec-poc/epic-pi-harness/README.md b/spec-poc/epic-pi-harness/README.md index c9b9747710..a285e94c36 100644 --- a/spec-poc/epic-pi-harness/README.md +++ b/spec-poc/epic-pi-harness/README.md @@ -1,6 +1,6 @@ # POC evidence — OMP / pi runtime seams -Throwaway, never merged. The [current epic](../../spec/_epics/pi-harness.md) is +Throwaway, never merged. The [current epic](../../spec/_epics/pi-harness/SPEC.md) is OMP-only and harness-only. Its durable question and same-session continuation proof remains open. The earlier pi companion investigation below is historical, not the current design or acceptance claim. @@ -36,7 +36,9 @@ This checks native tool registration, not an actual model-driven ask. These checks remove the need to assume a bespoke HTTP/file-mailbox live-answer transport. They do **not** prove tool interception, authorization, safe stop, durable parking, restart-resume, or the full FSD manager loop. Pinned source and the runtime -comparison are in the epic's §3; LAB-164 owns the remaining full-path proof. +comparison are in the epic's +[DECISIONS.md](../../spec/_epics/pi-harness/DECISIONS.md); LAB-164 owns the remaining +full-path proof. ## Original question (superseded) @@ -129,4 +131,5 @@ that a model-invoked `flow_ask` suspends the turn until the host answers. > **Stale citation, kept for the record.** This probe cited > `labs/conductor/src/manager.ts:1244`. That code has since been superseded by the published > `@flow-state-dev/harness-manager`, where the same ordering is a *stated invariant* at - > `manager.ts:1498–1504`. The finding got stronger, not weaker — see the epic-spec's §5. + > `manager.ts:1498–1504`. The finding got stronger, not weaker — see the epic-spec's + > [DECISIONS.md](../../spec/_epics/pi-harness/DECISIONS.md). diff --git a/spec/_epics/pi-harness.md b/spec/_epics/pi-harness.md deleted file mode 100644 index 61c847693f..0000000000 --- a/spec/_epics/pi-harness.md +++ /dev/null @@ -1,203 +0,0 @@ -# OMP coding runs ask, park, and continue - -OMP cannot yet run under FSD's harness manager. This epic adds it without another -manager or operator console, then connects spontaneous questions -to the existing durable human-wait path. - -**Epic:** [LAB-162](https://linear.app/fixpoint-labs/issue/LAB-162) · -**Review:** [#1612](https://github.com/fixpoint-labs/flow-state-dev/pull/1612), never merged. -The historical branch and file names are retained so existing review links keep working. - -## 1. Purpose & objective - -**Outcome.** A person dispatches an OMP coding run through the harness manager. -When it encounters a real question, it asks and parks. The person answers through -the existing operator surface, and a later attempt -continues the same coding conversation rather than starting over. - -The manager already supports multiple harnesses; Claude Code is not its only slot. -Its question-marker path already supports prompted asking, parking, and answering, -but has no trusted handoff for a runtime-captured question. This epic must supply that -handoff—not infer that spontaneous ask is already wired or invent another human-wait model. - -**Proof.** Dispatch a real OMP run, capture a spontaneous question, durably park the -task and end its attempt, stop the runtime, answer through the existing surface, and -resume the exact saved session. A generated fact learned before the question must -survive without being included in the answer prompt. The run then settles. -User cancellation must remain cancellation. Missing or mismatched resume data must -fail rather than silently start a fresh conversation. - -**Holistic necessity.** Two issues: [LAB-163](https://linear.app/fixpoint-labs/issue/LAB-163) -provides the OMP harness; [LAB-164](https://linear.app/fixpoint-labs/issue/LAB-164) connects -questions and owns the shared handoff and full proof. Keep that work within the two -issues; no separate transport, console, or contract-extraction project. An adapter alone is independently -useful, but does not discharge this epic's question-and-resume objective. - -**Lead measure.** Report which parts of that full-path proof have run, against which -OMP version. Model-free RPC compatibility is not a completed outcome. - -**Not doing.** Upstream pi support; a console or FSD flow-running extension inside -pi/OMP; a second inbox or answer verb; operator-approved tool execution; worker -`ctx.suspend`; holding a runtime or request open during human wait; a bespoke HTTP -answer channel; a shared pi/OMP abstraction; changes to unrelated harnesses' policy. - -**Kill line.** If OMP cannot do all of the following—safely capture a question, stop -and persist the conversation, and continue that exact session after an answer—return -to the objective gate. Do not substitute live blocking, fresh-session replay, -or adapter-only delivery and call the epic complete. The full sequence is **unproven**. - -**Approval sought.** Approve this outcome and two-issue scope. The owner has selected -harness-only, **OMP first, pi deferred**, and **questions first, tool approvals deferred**. -These choices do not approve this objective or either issue's implementation design. -The smaller scope delays pi users and operator-controlled tool execution; reconsider -when either is an immediate need. Tool permissions remain the host's configured policy. -No implementation starts at this gate. - -## 2. Themes & long-horizon direction - -1. **One human-wait model.** Preserve - [FIX-1241 / D-1](https://linear.app/fixpoint-labs/issue/FIX-1241) - ([decision record #1429](https://github.com/fixpoint-labs/flow-state-dev/issues/1429)): - a question becomes durable, the task parks, the worker request ends, and the existing - answer/unblock path starts a later attempt. `announce` follows parking. The runtime - adapter supplies evidence; the manager remains authoritative for task and inbox state. - A live RPC dialog is only a runtime seam, not durable human wait. - Classify dialog origin: tool approvals and extension UI are not operator questions. - Non-question permission prompts follow the host's configured allow/deny policy; - they do not enter this epic's parked-question path. - -2. **One trusted question handoff, currently missing.** The manager's existing intake - reads an attempt-keyed ask marker after the harness returns; it parks only when the - handle is `completed` and that attempt has a question. Throw, user cancellation, - deadline abort, or a non-completed handle does not take that park arm. A runtime - stop therefore cannot be relabeled as completion just to make parking happen. - LAB-164 owns the handoff from captured question to this intake and specifies it - jointly with LAB-163 before either affected interface is finalized. The manager - must provide the attempt-correlated destination through a trusted path or callback: - no prompt parsing, invented fixed filename, or question hidden in `finalMessage`. - The POC first tests preserving the single marker intake plus an orderly completed - harness step. If that is not honest or viable, a change to the harness contract - **or manager question intake** returns to this epic before either issue assumes it. - This is explicit integration work in the two-issue set, not a seam claimed to exist. - -3. **Conform to the shipped harness contract.** `packages/core/src/types/harness.ts` - owns the contract, and `packages/harness-manager` owns the slot and manager policy. - Keep model-visible input prompt-only; cwd, resume, and other run configuration use - the trusted channel. Report session identity through `onSession` during the run. - User cancellation throws; do not translate it into successful parking. Respect - `HarnessRunOutcome`, not process exit or RPC acknowledgement as a substitute. - The handoff in theme 2 is shared work; any other harness-contract or manager-intake - change must come back here before either issue assumes it. - -4. **OMP is a runtime, not a renamed pi executable.** Use OMP's native integration - seams rather than port the old file-mailbox companion. Source inspection identifies - `--mode rpc-ui` as the native-ask path; plain `rpc` supports extension dialogs but does - not enable the native ask tool. Installed OMP 18.1.14 registered `ask` in a local - `rpc-ui --tools ask` probe; the mode distinction rests on source inspection, - not a local negative control. Keep runtime translation inside the OMP harness. The public package - name and adapter API belong to LAB-163's spec, not to a speculative two-runtime layer. - -5. **Conversation identity survives; pending UI promises do not.** Both inspected - runtimes keep outstanding RPC UI requests in process memory. An old UI response ID - cannot be answered after restart. The manager's durable answer must continue the - recorded conversation in a new attempt. Resume lookup must fail closed on missing, - corrupt, or mismatched material, because the runtimes can otherwise create a new - session at an explicit missing path. Neither a reported path nor an in-memory ID - proves that resumable history has been persisted. - -6. **Prove the risky boundary before committing the production design.** LAB-164's - bounded feasibility POC precedes finalizing either issue's affected interface. After - their own spec approvals, LAB-163 implements the adapter first and LAB-164 builds on - it. LAB-164 is blocked by LAB-163 for delivery, not forbidden from investigating the - shared premise first. A failed safe-stop/persistence proof reopens the epic rather - than creating an unplanned suspension or transport issue. - -## 3. Shape of the whole - -**Built:** the original throwaway pi probes, plus a model-free RPC dialog probe run on -installed pi 0.85.1 and OMP 18.1.14; a separate OMP `rpc-ui` registration check. -**See:** [POC record](../../spec-poc/epic-pi-harness/README.md) and its `runtime-check/` evidence. -**Showed:** both answered the same extension confirmation over stdio; OMP exposed native -`ask` in `rpc-ui`. No model/tool approval, durable park, restart-resume, or assembled manager -loop was proved. The model-free commands did not persist session files in either runtime. -**Changed:** choose OMP first; remove console work, the bespoke answer transport, and -live-held human wait. Keep the full-path proof as an explicit requirement, not a claimed result. - -
-Runtime comparison and evidence boundaries - -| Concern | OMP | Upstream pi | Evidence | -|---|---|---|---| -| Headless control | `rpc` and `rpc-ui` over stdio | `rpc` over stdio | Source; both launched locally | -| Spontaneous ask | Native `ask`, enabled in `rpc-ui` | No native ask; a registered question tool is needed | Source; OMP registration checked locally | -| Extension confirmation | `extension_ui_request` / response | Same round-trip shape | Executed locally on both | -| Saved-session continuation | Explicit file + later prompt | Explicit file + later prompt | Source only; no restart-resume proof here | -| Terminal completion and cancellation | OMP-specific events and lifecycle | Pi-specific events and lifecycle | Source; not interchangeable | -| Durable human wait | Manager must own it | Manager must own it | Pending RPC maps are process-local | - -Pinned source: OMP -[`daf07999`](https://github.com/can1357/oh-my-pi/tree/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e) -and pi -[`b2602be7`](https://github.com/earendil-works/pi/tree/b2602be77cb7b0de45dd616407fd210daa48aa75). -The inspected manifests report 18.1.14 and 0.85.1 respectively; matching version strings -are not proof that an installed release contains every inspected main-branch change. - -Primary references: [OMP RPC](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/docs/rpc.md), -[OMP CLI setup](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/main.ts), -[OMP ask](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/tools/ask.ts), -[OMP sessions](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/session/session-manager.ts), -[pi RPC](https://github.com/earendil-works/pi/blob/b2602be77cb7b0de45dd616407fd210daa48aa75/packages/coding-agent/docs/rpc.md), -and [pi sessions](https://github.com/earendil-works/pi/blob/b2602be77cb7b0de45dd616407fd210daa48aa75/packages/coding-agent/src/core/session-manager.ts). - -
- -## 4. Running index - -| Issue | What it delivers | Route | Spec PR | Impl PR | State | -|---|---|---|---|---|---| -| [LAB-163](https://linear.app/fixpoint-labs/issue/LAB-163) | Dispatch, observe, cancel, resume OMP through the existing contract | spec | — | — | Backlog; epic approval pending | -| [LAB-164](https://linear.app/fixpoint-labs/issue/LAB-164) | Spontaneous questions, trusted handoff, durable wait, integrated proof | spec | — | — | Backlog; delivery blocked by LAB-163 | - -Related, not duplicated: [LAB-140](https://linear.app/fixpoint-labs/issue/LAB-140) -owns the manager program; [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154) -owns its packaging and manager-side session association. LAB-163 supplies OMP's side -of `resume`/`onSession`; it does not redo that manager work. -[LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) owns the operator board. -[FIX-1246](https://linear.app/fixpoint-labs/issue/FIX-1246) is the standing substrate -same-session POC. LAB-164 adds OMP-specific capture/stop evidence and must reuse its -continuity standard, not claim to close or supersede that broader issue. Restarting -a process is an adversarial condition here, **not** proof: the same session identity -and generated fact must survive. No fresh-session success satisfies D-1 or FIX-1246. - -No existing Linear epic for this pi/OMP proposal was found; LAB-162 and its two children -replace the draft's placeholder PI issue numbers. They share the Development Workflow -Orchestration project and the OMP question-and-resume proof milestone. - -## 5. Open cross-cutting questions - -- **Can the trusted handoff and safe capture → stop → persist → answer → same-session - continuation work?** Open empirical premise, owned by LAB-164's feasibility POC - with LAB-163 under theme 2. Blocks committing the affected production design. Test orderly parking - separately from user abort, including blocked-tool cancellation and process shutdown; - a working UI round trip does not settle it. -- **Runtime audience?** Resolved by owner: OMP first; upstream pi deferred. Reopen for an - immediate pi audience, not because the protocol names look alike. -- **Console and human-wait model?** Console removed by owner scope choice; existing - park/end-request/answer model retained under [D-1](https://linear.app/fixpoint-labs/issue/FIX-1241). - [D-9](https://linear.app/fixpoint-labs/issue/FIX-1309) - ([record #1562](https://github.com/fixpoint-labs/flow-state-dev/issues/1562)) retains - the existing operator surface. No issue may reopen either locally. -- **Tool authorization?** Resolved by owner after restraint review: questions first; - operator-approved tool execution deferred. It is a separate outcome, not free delivery plumbing. - -## Epic evolution - -- **Original draft** — pi harness plus an in-editor operator console and live question channel. -- **Four-lens review** — found conflicts with D-1/D-9, a stale Claude-only baseline, and - unsupported live-wait assumptions; synced the branch with the shipped harness substrate. -- **Owner scope choices and runtime research** — harness-only, OMP first, pi deferred; - replaced five placeholder work items with LAB-163 → LAB-164 under LAB-162 and made the - missing durable interaction proof explicit. Objective approval remains pending. -- **Final review and owner cut** — removed tool approvals; named the missing trusted - question handoff and its completed-handle gate; reconciled FIX-1246. Deferred the - exact handoff design to the joint feasibility check rather than assuming it shipped. diff --git a/spec/_epics/pi-harness/BUSINESS-RULES.md b/spec/_epics/pi-harness/BUSINESS-RULES.md new file mode 100644 index 0000000000..293e8619a5 --- /dev/null +++ b/spec/_epics/pi-harness/BUSINESS-RULES.md @@ -0,0 +1,53 @@ +# LAB-162 · Rules every issue in the set obeys + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) + +At epic altitude the rules aren't behaviours of one feature; they're the constraints both child +specs and both implementations must satisfy, and the place a cross-spec review checks. Each says +who owns it and where it's checked. ER-1 to ER-7 are the rows of the ownership matrix in +[DECISIONS.md](DECISIONS.md#who-owns-what). + +## What an operator gets, and what they don't + +| # | Rule | Owner | Checked at | +|---|---|---|---| +| ER-1 | A dispatched OMP run executes in the selected checkout, produces observable output, and settles through the existing manager | LAB-163 | LAB-163's tests · the full-path proof | +| ER-2 | Cancellation stops work and throws. A prompt acknowledgement, an intermediate event or a process exit is never read as completion, and a runtime stop is never relabelled as successful parking | LAB-163 ([D4](DECISIONS.md#d4)) | LAB-163's tests · the proof's negative cases | +| ER-3 | A later attempt reopens the same saved session and remembers a fact the run generated before the question, absent from the new prompt. Missing, corrupt or mismatched resume material fails rather than starting a fresh conversation | LAB-163 ([D6](DECISIONS.md#d6)) | LAB-163's tests · the full-path proof | +| ER-4 | A captured question reaches the manager's intake through one trusted, attempt-correlated path | LAB-164 decides · LAB-163 co-specifies ([D3](DECISIONS.md#d3)) | The joint feasibility check · both spec reviews | +| ER-5 | The attempt and the worker request end at the park. No runtime process and no worker request is retained during human wait | LAB-164 ([D2](DECISIONS.md#d2)) | The full-path proof | +| ER-6 | Only a real question enters the parked-question path. Tool-permission prompts and extension UI dialogs do not; they follow the host's configured allow/deny policy | LAB-164 ([D2](DECISIONS.md#d2)) | LAB-164's tests · the proof | + +## What no child may do + +| # | Rule | Because | +|---|---|---| +| ER-7 | No child changes the harness contract or the manager's question intake without returning to this epic first | [D4](DECISIONS.md#d4). Two authorities over one seam is what the manager was extracted to prevent | +| ER-8 | No child routes a question by parsing a prompt, duplicating a fixed filename, or hiding it in `finalMessage` | [D3](DECISIONS.md#d3). Each of those is an untrusted channel wearing the handoff's clothes | +| ER-9 | No child adds a second inbox, a new answer verb, a bespoke HTTP answer transport, worker `ctx.suspend`, or a wait that holds a runtime or request open | [D2](DECISIONS.md#d2), and D-1 before it. The existing park/answer path is the one model | +| ER-10 | No child adds operator-approved tool execution, or moves tool permissions off the host's configured policy | [D1](DECISIONS.md#d1). A separate outcome, deferred by the owner | +| ER-11 | No child adds upstream pi support, ports the file-mailbox companion, or builds a shared pi/OMP abstraction | [D1](DECISIONS.md#d1), [D5](DECISIONS.md#d5). One runtime is supported; a two-runtime layer is speculation | +| ER-12 | No child changes another harness's behaviour or policy | The set adds a slot; it does not renegotiate the ones already in it | +| ER-13 | No child closes, supersedes or re-parents [FIX-1246](https://linear.app/fixpoint-labs/issue/FIX-1246), [LAB-140](https://linear.app/fixpoint-labs/issue/LAB-140), [LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) or [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154) | Consumed, not owned. FIX-1246 keeps the broader same-session standard this epic reuses | + +## How the set is run + +| # | Rule | Because | +|---|---|---| +| ER-14 | The joint feasibility check runs before either affected interface is finalized, and before either issue's production design is committed | [D3](DECISIONS.md#d3). The handoff is the epic's one empirical premise; committing a design to it first is the expensive order | +| ER-15 | A cross-cutting question a child hits is commented **up** on the epic PR, not answered locally | [DECISIONS.md](DECISIONS.md) is the single place. A local answer is a second authority | +| ER-16 | Both issues route *spec*; neither starts implementation before the epic objective gate **and** its own spec approval | Fail-closed gating. Owner scope choices are not implementation approval | +| ER-17 | Every claim records what was executed against which pinned OMP version, and what was not | The lead measure. Source inspection and model-free RPC probes are available-seam evidence, never end-to-end proof | +| ER-18 | A child's Linear state is mirrored the moment it changes | The epic wake derives blocked-by from Linear; a stale child blocks its dependant whatever its PRs say | + +## The proof + +| # | The epic is done when | Proved by | +|---|---|---| +| ER-19 | A real OMP run reaches a real question; the operator sees it through the existing surface after durable parking; the runtime is stopped; an answer continues the exact saved session, with a pre-question generated fact intact and absent from the answer prompt; the task settles | LAB-164's full-path evidence, reproducible, against a pinned OMP version | +| ER-20 | User cancellation stays cancellation; late, duplicate and cross-attempt answers cannot affect another run; missing or corrupt resume material and runtime failure fail safely, without a silent fresh session | LAB-164's negative cases, run separately from the happy path | +| ER-21 | If safe capture, stop, persistence or same-session continuation cannot be shown, the epic returns to the objective gate | The kill line. No live wait, fresh-session replay or adapter-only delivery is substituted and called complete | + +**Restarting a process is an adversarial condition here, not the proof.** The same session identity +and the generated fact must survive it. No fresh-session success satisfies D-1 or FIX-1246 +([DECISIONS.md → decided in review](DECISIONS.md#decided-in-review-recorded-so-no-child-reopens-them)). diff --git a/spec/_epics/pi-harness/DECISIONS.md b/spec/_epics/pi-harness/DECISIONS.md new file mode 100644 index 0000000000..6a8d1e0797 --- /dev/null +++ b/spec/_epics/pi-harness/DECISIONS.md @@ -0,0 +1,175 @@ +# LAB-162 · Decisions + +[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) + +The calls that sit above either issue: what was chosen, what lost, why, and what each locks in for +LAB-163 and LAB-164. Three are the sign-off surface. The rest were settled in review and are +recorded here so no child reopens them. + +## The tree + +```mermaid +flowchart TD + E["LAB-162"] --> D1["D1 · two issues · harness-only · OMP first · questions first"] + D1 -.->|"rejected"| X1["five items: pi, an operator console, a live question channel"] + E --> D2["D2 · ask, park, end the request, answer later"] + D2 -.->|"rejected"| X2["hold the runtime and the worker request open"] + E --> D3["D3 · the trusted handoff is missing, and building it is in scope"] + D3 -.->|"rejected"| X3["assume spontaneous ask already reaches the intake"] + E --> D4["D4 · the shipped contract is the seam"] + E --> D5["D5 · OMP's native seams, not the pi companion"] + E --> D6["D6 · conversation identity survives; pending UI promises do not"] +``` + + +## D1 · Two issues, harness-only: OMP first, questions first + +| | | +|---|---| +| **Instead of** | Five work items — a pi harness, an in-editor operator console, a live question channel, notifications, tool approvals | +| **Because** | The console duplicates a surface [LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) owns and a decision [D-9](https://linear.app/fixpoint-labs/issue/FIX-1309) already made. Operator-approved tool execution is its own outcome, not free plumbing falling out of question delivery. There is no pi audience waiting; there is an OMP one | +| **Locks in** | Tool permissions stay host policy across the set. Pi is deferred, not refused. An adapter that ships alone does **not** discharge this epic — LAB-164 carries the outcome | + +**What would change my mind:** an immediate pi audience, or evidence that tool approvals — not +questions — are what stalls real runs. Then the set's shape changes, not one issue's design. + + +## D2 · One human-wait model: ask, park, the request ends, answer starts a later attempt + +| | | +|---|---| +| **Instead of** | Holding the runtime and the worker request open while a person thinks — `ctx.suspend`, a live RPC dialog awaited across the wait, a bespoke HTTP answer channel | +| **Because** | [FIX-1241 / D-1](https://linear.app/fixpoint-labs/issue/FIX-1241) ([record #1429](https://github.com/fixpoint-labs/flow-state-dev/issues/1429)) decided this already, and both inspected runtimes keep pending RPC UI requests in process memory — so a live dialog could not be a durable wait even if we wanted one. `announce` follows parking; it is a post-park notification, not a mid-run channel | +| **Locks in** | The manager stays authoritative for task and inbox state; the adapter only supplies evidence. A live RPC dialog is a runtime seam, never the wait. Tool approvals and extension UI are not operator questions and never enter the parked-question path — they follow the host's configured allow/deny policy | + + +## D3 · The trusted question handoff is missing today, and building it is in scope + +| | | +|---|---| +| **Instead of** | Assuming spontaneous ask already reaches the manager, or routing it through prompt parsing, an invented fixed filename, or a question hidden in `finalMessage` | +| **Because** | The existing intake reads an attempt-keyed ask marker *after* the harness returns, and parks only when the handle is `completed` and that attempt has a question. A throw, a cancellation, a deadline abort or a non-completed handle does not take that arm — so a runtime stop cannot be relabelled as completion to make parking happen. Nothing puts an OMP question in that marker today | +| **Locks in** | LAB-164 owns the handoff and specifies it **jointly with LAB-163 before either affected interface is finalized**. The manager supplies the attempt-correlated destination through a trusted path or callback. The feasibility check first tests preserving the single marker intake plus an orderly completed harness step; if that is not honest or viable, the change returns here under D4 | + + +## D4 · The shipped harness contract is the seam; a change to it returns here + +| | | +|---|---| +| **Instead of** | A private OMP-only seam beside the contract, or either issue widening it locally | +| **Because** | `packages/core/src/types/harness.ts` owns the contract; `packages/harness-manager` owns the slot and manager policy. Two authorities over one seam is what the manager was extracted to prevent | +| **Locks in** | Model-visible input stays prompt-only; cwd, resume and other run configuration travel the trusted channel. Session identity is reported through `onSession` during the run. `HarnessRunOutcome` is the terminal signal, not a process exit or an RPC acknowledgement. Any contract or intake change beyond D3's handoff returns here before either issue assumes it | + + +## D5 · OMP is a runtime, not a renamed pi executable + +| | | +|---|---| +| **Instead of** | Porting the old file-mailbox companion, or building a shared pi/OMP abstraction over two runtimes we support one of | +| **Because** | Source inspection identifies `--mode rpc-ui` as the native-ask path; plain `rpc` carries extension dialogs but does not enable the native ask tool. Installed OMP 18.1.14 registered `ask` in a local `rpc-ui --tools ask` probe. The mode distinction rests on source, not on a local negative control — a strong lead, not a settled fact | +| **Locks in** | Runtime translation stays inside the OMP harness. Completion and cancellation events are OMP-specific, not interchangeable with pi's. The package name and adapter API belong to LAB-163's spec, not a speculative two-runtime layer | + + +## D6 · Conversation identity survives a restart; pending UI promises do not + +| | | +|---|---| +| **Instead of** | Answering the original UI response id after a restart, or trusting a reported session path as proof that history was persisted | +| **Because** | Both runtimes hold outstanding RPC UI requests in process memory, so an old response id is unanswerable once the process is gone. Worse, a runtime can silently create a *new* session at an explicitly missing path — which looks like success and is the failure this epic exists to avoid | +| **Locks in** | The durable answer continues the recorded conversation in a **new attempt**. Resume lookup fails closed on missing, corrupt or mismatched material. Neither a reported path nor an in-memory id is evidence that resumable history exists | + +## Who owns what + +![Who owns what: seven cross-cutting rules by three columns, the epic LAB-162 and its two issues LAB-163 and LAB-164. LAB-163 builds dispatch and observation, cancellation, and same-session resume; LAB-164 consumes them. LAB-164 decides the trusted question handoff and LAB-163 co-specifies it, the one row with two authors. LAB-164 builds durable parking and decides what counts as a real question; LAB-163 consumes both. The epic itself decides that a harness-contract or question-intake change returns to it, and both issues consume that.](figures/ownership.svg) + +Every rule has one owner. **ER-4 is the one row with two authors, on purpose** — LAB-164 decides +it, LAB-163 co-specifies it, and that joint seam is the work this epic exists to do (D3). A cell +that reads *consumes* is a place that child must not re-decide. + +## Decided in review, recorded so no child reopens them + +- **Live-blocked human wait is out** (must fix). It conflicts with D-1. Preserved as ask → durable + park → the request ends → answer → same-session continuation. No worker suspension. +- **The in-editor console is out** (must fix). It conflicts with D-9 and with LAB-151's ownership. + The owner selected harness-only; the console and notification items were removed. +- **The runtime-captured question has no trusted route to the intake** (must fix). Named as + missing, with its owner, gates and escalation boundary. No child may claim the seam ships. +- **Tool authorization is a separate outcome** (should fix). Questions first; approvals removed + from the outcome and from acceptance. +- **[FIX-1246](https://linear.app/fixpoint-labs/issue/FIX-1246) is not closed or superseded here** + (should fix). It owns the broader substrate same-session POC; this epic adds OMP-specific + capture/stop evidence and reuses its continuity standard. **Restarting a process is an + adversarial condition, not proof** — the session identity and a generated fact must survive it, + and no fresh-session success satisfies D-1 or FIX-1246. +- **The Claude-only baseline was stale** (should fix). The shipped multi-harness substrate is + retained; the five placeholder work items became LAB-163 → LAB-164 under LAB-162, sharing the + Development Workflow Orchestration project and the OMP proof milestone. +- **The negative persistence claim needed an evidence field** (note). Post-stop `ENOENT` checks + were added; `rpc-ui --tools ask` is the local check, and source inspection the basis for the + mode distinction. +- **Runtime audience: OMP first, pi deferred.** Reopen for an immediate pi audience, not because + the protocol names look alike. + +Two rounds were spent, on independent coherence, restraint, correctness and completeness lenses +over frozen inputs. The second reviewed the revised proposal before the final owner scope cut, so +it is not a clean verdict on the current bytes. Completeness found the revised objective complete +*at epic altitude* — not implemented. **No third round and no full-runtime pass is claimed.** + +## What the end-state POC showed + +**Built:** the original throwaway pi probes, plus a model-free RPC dialog probe run unchanged on +installed pi 0.85.1 and OMP 18.1.14, and a separate OMP `rpc-ui` registration check. +**See it:** [`spec-poc/epic-pi-harness/`](../../../spec-poc/epic-pi-harness/README.md) on this +branch, with its `runtime-check/` evidence files. +**Showed:** both runtimes answered the same `extension_ui_request` confirmation over stdio, and +OMP exposed native `ask` under `rpc-ui`. Post-stop filesystem checks found neither reported probe +session file. No model-driven ask, tool authorization, durable park, restart-resume or assembled +manager loop was proved — those seams are available, not demonstrated. +**Changed:** OMP went first; the console, the bespoke answer transport and live-held human wait +were cut; and the full-path proof stayed an explicit requirement rather than becoming a claimed +result. + +
+Runtime comparison and evidence boundaries + +| Concern | OMP | Upstream pi | Evidence | +|---|---|---|---| +| Headless control | `rpc` and `rpc-ui` over stdio | `rpc` over stdio | Source; both launched locally | +| Spontaneous ask | Native `ask`, enabled in `rpc-ui` | No native ask; a registered question tool is needed | Source; OMP registration checked locally | +| Extension confirmation | `extension_ui_request` / response | Same round-trip shape | Executed locally on both | +| Saved-session continuation | Explicit file + later prompt | Explicit file + later prompt | Source only; no restart-resume proof here | +| Terminal completion and cancellation | OMP-specific events and lifecycle | Pi-specific events and lifecycle | Source; not interchangeable | +| Durable human wait | Manager must own it | Manager must own it | Pending RPC maps are process-local | + +Pinned source: OMP +[`daf07999`](https://github.com/can1357/oh-my-pi/tree/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e) +and pi +[`b2602be7`](https://github.com/earendil-works/pi/tree/b2602be77cb7b0de45dd616407fd210daa48aa75). +The inspected manifests report 18.1.14 and 0.85.1; matching version strings are not proof that an +installed release contains every inspected main-branch change. + +Primary references: [OMP RPC](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/docs/rpc.md), +[OMP CLI setup](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/main.ts), +[OMP ask](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/tools/ask.ts), +[OMP sessions](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/session/session-manager.ts), +[pi RPC](https://github.com/earendil-works/pi/blob/b2602be77cb7b0de45dd616407fd210daa48aa75/packages/coding-agent/docs/rpc.md), +and [pi sessions](https://github.com/earendil-works/pi/blob/b2602be77cb7b0de45dd616407fd210daa48aa75/packages/coding-agent/src/core/session-manager.ts). + +
+ +## How it got here + +- **Original draft** — a pi harness plus an in-editor operator console and a live question channel. +- **Four-lens review** — found the conflicts with D-1 and D-9, a stale Claude-only baseline and + unsupported live-wait assumptions; the branch was synced with the shipped harness substrate. +- **Owner scope choices and runtime research** — harness-only, OMP first, pi deferred; five + placeholder work items replaced by LAB-163 → LAB-164 under LAB-162; the missing durable + interaction proof made explicit. +- **Final review and owner cut** — tool approvals removed; the missing handoff and its + completed-handle gate named (D3); FIX-1246 reconciled. The handoff design was deferred to the + joint feasibility check rather than assumed to ship. +- **Rewritten as a four-document set (Sep 16)** — the same objective, scope and dispositions moved + into these four documents with three figures. **No decision changed**; the old §1–§5 map onto + them, and no review round was spent. + +**Open: none.** diff --git a/spec/_epics/pi-harness/PLAN.md b/spec/_epics/pi-harness/PLAN.md new file mode 100644 index 0000000000..7a7912654e --- /dev/null +++ b/spec/_epics/pi-harness/PLAN.md @@ -0,0 +1,79 @@ +# LAB-162 · Plan + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan** + +An epic plan sequences the work and says what each piece entails. It does not say how to build any +piece; that's each issue's own plan. IDs cross-reference [DECISIONS.md](DECISIONS.md) (D-n) and +[BUSINESS-RULES.md](BUSINESS-RULES.md) (ER-n). + +## The path + +![The path as of 2026-09-16: four lanes against time. The now line sits before the objective gate, so every bar in the set is still ahead of it and none has started. LAB-154, manager-side session association, is shipped and available throughout. LAB-162's objective gate comes first. LAB-163 is specced then implements the OMP harness. LAB-164 runs the joint feasibility check early, before either affected interface is finalized, is specced alongside, and implements plus proves the full path only after LAB-163 delivers.](figures/path.svg) + +A chain with one early fork. Nothing in the set has started: the now line sits **before** the gate, +and every bar is ahead of it. The one thing that runs early and out of delivery order is the joint +feasibility check — it belongs to LAB-164 but must land before either affected interface is +finalized (ER-14), which is why it sits beside LAB-163's spec rather than after LAB-163 delivers. +The dependency graph itself is in [the spec](SPEC.md#how-the-issues-flow-into-each-other); this +document adds time to it. + +## What each issue entails + +| Issue | Route | Consumes | Delivers | Releases | Size | +|---|---|---|---|---|---| +| **LAB-163** OMP harness | spec → impl PR | The shipped harness contract and the manager's slot and policy · LAB-154's manager-side session association · [D4](DECISIONS.md#d4), [D5](DECISIONS.md#d5), [D6](DECISIONS.md#d6) | An OMP harness taking prompt input and trusted run configuration; observable events; session identity through `onSession` during the run; resume of that exact saved conversation; terminal success, runtime failure and cancellation told apart; honest startup/model/auth failures; the tested OMP version recorded | LAB-164's delivery | Medium | +| **LAB-164** questions park and resume | spec → impl PR → the proof | LAB-163's adapter, resume and `onSession` · the existing manager intake, inbox, answer action and operator surface · [D2](DECISIONS.md#d2), [D3](DECISIONS.md#d3), [D6](DECISIONS.md#d6) | The trusted attempt-correlated handoff, co-specified with LAB-163; a captured question as durable evidence; the park where the attempt and the request end; the answer carried into a later attempt of the same session; real questions told apart from permission and extension dialogs; the negative cases; reproducible full-path evidence | The epic's wrap | Large | + +**The feasibility check is LAB-164's, and it is not a third issue.** It is the first thing LAB-164 +does, it precedes both issues' affected interfaces (ER-14), and it is bounded to one question: +whether an orderly completed harness step plus the existing single marker intake can carry a +captured question honestly. + +## Where it is + +Status lives in one place: [the set table in the spec](SPEC.md#the-set--as-of-2026-09-16). The +swimlanes above carry the same state as a picture of time and are redrawn when it moves. The one +input from outside the set, [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154), is **done**; +ER-13 consumes it without re-parenting it. + +## What unblocks what, from here + +1. **The objective gate is approved** → both issues can be specced, and LAB-164's joint feasibility + check can start. Nothing implements yet (ER-16). +2. **The feasibility check returns** → ER-4's handoff can be decided and both affected interfaces + finalized. If it needs a change to the harness contract or the manager's question intake, it + comes back here first (ER-7) — neither spec assumes it. +3. **LAB-163's own spec is approved** → LAB-163 implements. +4. **LAB-163 merges** → LAB-164's delivery is unblocked. LAB-164 was never blocked from + investigating the shared premise, only from delivering on it. +5. **LAB-164's full-path proof passes** (ER-19, ER-20) → the epic wraps. +6. **If safe capture, stop, persistence or continuation cannot be shown** → back to the objective + gate (ER-21). Not to an unplanned suspension issue, not to a transport issue. + +## Coordination seams to watch + +| Seam | Between | Rule | +|---|---|---| +| The attempt-correlated question destination | LAB-163 and LAB-164 | ER-4. LAB-164 decides it, LAB-163 co-specifies it, and both do so before either interface is final. A second route is exactly the failure the seam exists to prevent | +| `resume` and `onSession` | LAB-163 and LAB-154 (shipped) | LAB-154 owns manager-side association; LAB-163 supplies OMP's side. Neither redoes the other's half | +| The completed-handle park arm of the manager's intake | LAB-164 and the shipped manager | Preserve the single marker intake first (D3). Any change to the intake returns to this epic (ER-7) | +| The pinned OMP version | Both issues | ER-17. One pinned version across the set's evidence; two versions makes the proof unreadable | + +## Not children, deliberately + +| Issue | What it owns | Why it isn't in the set | +|---|---|---| +| [FIX-1246](https://linear.app/fixpoint-labs/issue/FIX-1246) | The broader substrate same-session POC | This epic adds OMP-specific capture and stop evidence and reuses its continuity standard. It does not close or supersede it (ER-13) | +| [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154) | Manager-side session association · **done** | Consumed. LAB-163 supplies OMP's side only | +| [LAB-140](https://linear.app/fixpoint-labs/issue/LAB-140) | The harness manager program · in progress | The set adds a slot to it; it does not rewrite it | +| [LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) | The operator board · in review | The surface this epic reuses. Building a second one is what D1 cut | +| [FIX-1241 / D-1](https://linear.app/fixpoint-labs/issue/FIX-1241) | The one-human-wait model | A standing decision D2 preserves. No child reopens it locally | +| [FIX-1309 / D-9](https://linear.app/fixpoint-labs/issue/FIX-1309) | The existing operator surface · **done** | Why the console is out. No child reopens it locally | + +## Wrap + +When ER-19 to ER-21 hold: record what ran against which pinned OMP version and what did not +(ER-17), run the lessons pass over the set's review rounds, dispatch the docs polish over whatever +the two issues each edited in isolation, refresh the set table and the path one last time, and +close the epic PR unmerged. If the kill line fires instead, the epic returns to the objective gate +rather than wrapping — that is a real outcome for this set, not a failure to finish. diff --git a/spec/_epics/pi-harness/SPEC.md b/spec/_epics/pi-harness/SPEC.md new file mode 100644 index 0000000000..d0a4de722e --- /dev/null +++ b/spec/_epics/pi-harness/SPEC.md @@ -0,0 +1,125 @@ +# LAB-162 · OMP coding runs ask, park, and continue + +**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) + +Epic · 2 issues · Development Workflow Orchestration · [LAB-162](https://linear.app/fixpoint-labs/issue/LAB-162) · [#1612](https://github.com/fixpoint-labs/flow-state-dev/pull/1612), never merged + +> `pi-harness` is a historical branch and directory name from when this epic was scoped to +> upstream pi. The epic is OMP-only now. The name stays so the review links on #1612 keep working. + +## Four teams, before and after + +| A team that… | Today | After this epic | +|---|---|---| +| **wants an OMP run supervised** | The manager offers other harnesses; OMP is not one of its slots | Dispatches OMP through the same contract, in the same checkout, settling the same way | +| **has a run reach a real question** | It guesses, or a person sits watching it | It asks, the task parks, and no worker request is held open while a person thinks | +| **answers a parked coding run** | The surface exists, but a question the runtime raised has no trusted route into it | The same surface carries the answer, with no second inbox and no new verb | +| **needs the run to remember** | A second attempt starts a fresh conversation | The later attempt continues the recorded one, or fails rather than starting fresh | + +**Outcome.** A person dispatches an OMP coding run through the harness manager. When it reaches a +real question, it asks and parks. The person answers through the existing operator surface, and a +later attempt continues the same coding conversation rather than starting over. + +**Proof.** Dispatch a real OMP run, capture a spontaneous question, durably park the task and end +its attempt, stop the runtime, answer through the existing surface, resume the exact saved session, +and settle. A fact the run generated before the question must survive without being fed back in the +answer prompt. Cancellation stays cancellation; missing or mismatched resume data fails rather than +silently starting fresh. + +**Lead measure.** Which parts of that proof have run, against which OMP version. Model-free RPC +compatibility is an available seam, not a completed outcome. + +**Not doing.** Upstream pi support; a console or FSD-flow-running extension inside pi/OMP; a +second inbox or answer verb; operator-approved tool execution; worker `ctx.suspend`; holding a +runtime or request open during human wait; a bespoke HTTP answer channel; a shared pi/OMP +abstraction; changes to unrelated harnesses' policy. + +**Kill line.** If OMP cannot safely capture a question, stop and persist the conversation, *and* +continue that exact session after an answer, return to the objective gate. Do not substitute live +blocking, fresh-session replay, or adapter-only delivery and call the epic complete. The full +sequence is **unproven**. + +**Why now.** The manager already supervises more than one harness, and its question-marker path +already parks and answers. What it has no route for is a question the *runtime* raised mid-run: +the intake reads an attempt-keyed marker after the harness returns, and nothing puts an OMP +question there. So a supervised run either guesses or needs someone watching it — the cost of +every long coding run we dispatch, not a rare edge. + +## What's in the box + +![What's in the box: a dispatched OMP run is observed and cancelled on the shipped contract, captures a real question as attempt-correlated durable evidence, parks while the attempt and worker request end, and continues the same saved session after an answer. A fence marks that the runtime holds nothing durable and the manager owns the task, the inbox and the answer. Host tool-permission policy is composed in unchanged. The manager, inbox, answer action and operator surface are reused as is. Not built: upstream pi, an operator console, a second inbox or answer verb, operator-approved tool execution, worker suspension or live-held wait, a bespoke HTTP answer channel, a shared pi and OMP layer.](figures/end-state.svg) + +The fence keeps this cheap: the runtime holds nothing durable, so there is no second authority over +a parked task and no live process to keep alive while a person thinks ([D2](DECISIONS.md#d2)). The +bottom strip is what the set refuses to build, most of it cut by the owner's scope choices rather +than by discovery. + +## The set · as of 2026-09-16 + +The live table, refreshed on the epic PR as the issues move. The plan and the figures point here +rather than repeating it. + +| Issue | What it delivers | Why the set needs it | Status | +|---|---|---|---| +| [LAB-163](https://linear.app/fixpoint-labs/issue/LAB-163) | Dispatch, observe, cancel and resume OMP through the shipped harness contract | Nothing can ask until something can run. Independently useful, and on its own it does not meet the outcome | Backlog · route *spec* · waits on the objective gate · no spec PR yet | +| [LAB-164](https://linear.app/fixpoint-labs/issue/LAB-164) | Captured questions as durable evidence, the park, the answer into the same session — and the full-path proof | The half that meets the outcome. It owns the missing handoff and the only proof that can clear the kill line | Backlog · route *spec* · delivery blocked by LAB-163 · no spec PR yet | + +0 done · 0 in flight · 2 filed, both waiting on the objective gate. + +**Is two really one?** No, and it is not three either. An adapter alone is genuinely useful and +genuinely insufficient — a supervised OMP run that still cannot ask. Questions without an adapter +have nothing to ask *from*. Splitting further was considered and cut: a transport issue, a +contract-extraction issue and a console were among the original five work items, and review found +them either duplicating shipped substrate or conflicting with decisions already made. No collapse +trigger was named. The **escalation** trigger is [ER-7](BUSINESS-RULES.md): a change to the harness +contract or the manager's question intake returns here before either issue assumes it. + +## How the issues flow into each other + +```mermaid +flowchart LR + M["LAB-154 · manager-side session association"] -.->|"where resume and onSession land"| A + A["LAB-163 · OMP harness"] -->|"the adapter · resume · onSession · cancellation"| B["LAB-164 · questions park and resume"] + A -.->|"co-specifies"| H["ER-4 · the trusted question handoff · missing today"] + B -.->|"owns"| H + classDef done stroke-width:2px + classDef proposed stroke-dasharray:4 3 + class M done + class H proposed +``` + +A solid edge is what one issue hands the next; a heavy border is done and outside the set. The +dashed node is **not an issue** — it is the seam that does not exist today, which LAB-164 owns and +LAB-163 co-specifies before either affected interface is finalized. Both issues are filed, so +neither is a placeholder. + +## What stays as it is + +- **The harness manager, the inbox, the answer action and the operator surface.** Reused, not + extended. [LAB-140](https://linear.app/fixpoint-labs/issue/LAB-140) owns the manager program, + [LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) the operator board. +- **Manager-side session association** — [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154), + done. LAB-163 supplies OMP's side of `resume`/`onSession` and does not redo that work. +- **Tool permissions**, which stay the host's configured allow/deny policy. +- **Upstream pi.** Deferred, not refused forever — reopened for a real pi audience, not because + the protocol names look alike. +- **Other harnesses' policy.** Nothing here changes how Claude Code or Codex behave. + +## Sign off + +1. **[D1](DECISIONS.md#d1) · Two issues, harness-only, OMP first, questions first, now.** If + wrong: a cycle spent on a runtime audience we don't have, or on plumbing for a tool-approval + feature nobody asked for. The smaller scope delays pi users and operator-controlled tool + execution; reconsider when either is an immediate need. +2. **[D2](DECISIONS.md#d2) · One human-wait model — ask, park, end the request, answer later.** + If wrong: the epic's *scope* changes rather than one issue's design, and + [FIX-1241 / D-1](https://linear.app/fixpoint-labs/issue/FIX-1241) changes with it. +3. **[D3](DECISIONS.md#d3) · The trusted question handoff is missing, and building it is in + scope.** If wrong optimistically, LAB-164 shrinks. If wrong the other way, the joint + feasibility check says so before either interface is committed, and the kill line fires. + +**What would change my mind on 1:** an immediate pi audience, or evidence that tool approvals — +not questions — are what blocks real runs. + +**Open: none.** Approving this signs off the outcome and the two-issue scope. It approves no +implementation design, and neither issue starts before its own spec gate. diff --git a/spec/_epics/pi-harness/figures/end-state.svg b/spec/_epics/pi-harness/figures/end-state.svg new file mode 100644 index 0000000000..c8a3b86e4b --- /dev/null +++ b/spec/_epics/pi-harness/figures/end-state.svg @@ -0,0 +1,66 @@ + + + + + + IN THE BOX · WHAT A DISPATCHED OMP RUN GETS + + Dispatched, observed, cancelled on the shipped contract + + A real question, captured as durable attempt evidence + + The task parks; the attempt and the request end + + An answer continues the same saved session, later + + The runtime holds nothing durable. The manager owns + the task, the inbox and the answer. + + + + + COMPOSED IN BY THE HOST + Tool permissions stay the host's + configured allow / deny policy. + + + + + REUSED AS IS, NOT REBUILT + The harness manager, the inbox, + the answer action and the + existing operator surface. + + + + + NOT BUILT — REFUSED BY THIS SET + Upstream pi support + An operator console or FSD-in-pi extension + A second inbox or answer verb + Operator-approved tool execution + Worker suspension or live-held human wait + A bespoke HTTP answer channel · a shared pi/OMP layer + + diff --git a/spec/_epics/pi-harness/figures/ownership.svg b/spec/_epics/pi-harness/figures/ownership.svg new file mode 100644 index 0000000000..ee763e046f --- /dev/null +++ b/spec/_epics/pi-harness/figures/ownership.svg @@ -0,0 +1,118 @@ + + + + + CROSS-CUTTING RULE + LAB-162 + LAB-163 + LAB-164 + + + + + + ER-1 + Dispatch, observe and cancel OMP on the shipped contract + + — + + builds + + consumes + + + + + ER-2 + Cancellation stays cancellation, never relabelled as parking + + — + + builds + + consumes + + + + + ER-3 + The same saved session continues; resume fails closed + + — + + builds + + consumes + + + + + ER-4 + One trusted, attempt-correlated question handoff + + — + + co-specs + + decides + + + + + ER-5 + Park is durable: the attempt and the request end, nothing is held + + — + + consumes + + builds + + + + + ER-6 + A real question, not a permission or extension dialog + + — + + consumes + + decides + + + + + ER-7 + A harness-contract or question-intake change returns to the epic + + decides + + consumes + + consumes + + diff --git a/spec/_epics/pi-harness/figures/path.svg b/spec/_epics/pi-harness/figures/path.svg new file mode 100644 index 0000000000..4bb2026357 --- /dev/null +++ b/spec/_epics/pi-harness/figures/path.svg @@ -0,0 +1,93 @@ + + + + + + + + + LAB-154 · input + session association + LAB-162 · the epic + LAB-163 · OMP harness + LAB-164 · questions + and the proof + + + + + shipped · available throughout + + + gate + + + spec + + implement the harness + + + feasibility check + + spec + + implement · full-path proof + + + + + + + + + + + + + + now · 2026-09-16 · nothing has started + + + + + + + + + + objective + gate + the joint check + and the two specs + LAB-163 + delivers + LAB-164 proves + the full path + wrap + + From 99746956c6b24e0b509589532ee9b9b59ba3c435 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 16 Sep 2026 21:56:36 +0000 Subject: [PATCH 5/7] Correct two false claims in the pi-harness POC findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `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 Claude-Session: https://claude.ai/code/session_0125zR5sy7YdPsbrrtzQ1dKf --- .../epic-pi-harness/real-flow-findings.md | 46 ++++++++++++++----- spec-poc/epic-pi-harness/real-flow.test.ts | 12 +++-- 2 files changed, 44 insertions(+), 14 deletions(-) diff --git a/spec-poc/epic-pi-harness/real-flow-findings.md b/spec-poc/epic-pi-harness/real-flow-findings.md index a665e8bd32..723f93846d 100644 --- a/spec-poc/epic-pi-harness/real-flow-findings.md +++ b/spec-poc/epic-pi-harness/real-flow-findings.md @@ -26,9 +26,15 @@ REQUEST IDS: test_flow_req_...ea00df985007d test_flow_req_...2e5a4444de6c 1. **A real flow action dispatches and returns a real terminal status** (`completed`) and a real typed output. This is the shape a pi extension renders. -2. **Two dispatches on one shared session produce distinct request ids** while sharing store - state — exactly the pairing PI-2 must keep straight when resuming a flow across pi - sessions and forks. Session continuity is not hypothetical; the substrate already has it. +2. **Two sequential dispatches against one in-process engine each reach terminal + `completed`, each with a distinct request id.** That is the whole of it. The handler under + test touches no state, and `testFlow` mints a fresh request id on every call + (`packages/testing/src/test-utilities/testFlow.ts:159` — `generateId("test_flow_req")`, + which is timestamp + random and reads neither `sessionId` nor `stores`), so the same + inequality would hold for two unrelated sessions, or if the shared session and stores were + ignored outright. **Same-session continuity across a runtime restart remains unproven** — + one process, in-memory stores, no teardown — which is the position the epic-spec already + holds. An earlier version of this file concluded the opposite from this test. 3. **A pure `handler` flow needs no LLM and no network**, so the epic's transport and routing claims can be tested in CI without keys. @@ -36,16 +42,30 @@ REQUEST IDS: test_flow_req_...ea00df985007d test_flow_req_...2e5a4444de6c **Theme 8's item routing was invented.** The spec split items into "progress · status" versus "outputs · gaps" — a four-way vocabulary that does not exist. The real `RuntimeItem` union in -`@flow-state-dev/contracts` has **24 types**: +`@flow-state-dev/contracts` has **17 types**: ```text -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 +block_trace · component · container · continuation · error · generator_step +message · reasoning · resource_change · router_decision · source state_change · state_snapshot · status · suspension · suspension_resume · tool_output ``` -Two of these matter beyond routing: +`RuntimeItem` is `OutputItem` — 13 members in `packages/contracts/src/items/types.ts` — plus +the four trace types `block_trace`, `router_decision`, `state_snapshot` and `generator_step` +(`packages/contracts/src/items/internal.ts`). 13 + 4 = 17, and `types.ts` carries exactly 17 +`type: "…"` discriminator literals. + +**An earlier version of this file said 24.** It reached that number by taking every type name +in the items tree, which sweeps in seven names that are not item discriminators at all: +`output_text`, `reasoning_text`, `refusal`, `file` and `output_audio` are ContentPart types +living *inside* an item, in a `message`'s `content` array or a `reasoning`'s `summary` +(`items/content.ts`); `debug` and `ping` are SSE event types on the transport envelope +(`items/events.ts`). That distinction is the finding worth keeping: **a renderer allowlist +built from "every type name in the items tree" over-counts by pulling in content parts and +transport events.** Route on an item's own `type`; a content part is reached by walking into +the item that holds it, and a transport event never reaches a renderer at all. + +One of these matters beyond routing: - **`suspension` / `suspension_resume`** — FSD *already has* a first-class suspend/resume item pair, and `testFlow` already reports a `"suspended"` terminal status. The epic's §5 open @@ -53,11 +73,13 @@ Two of these matter beyond routing: It may not: the durable mid-run question mechanism may already exist in the item vocabulary. **This is the single most useful thing this probe found**, and it should be checked before that question is answered. -- **`ping`** — a keepalive, which is a routing decision the spec never made (it must never - reach the LLM, and probably never the operator either). + +And one thing outside the item vocabulary still needs a decision the spec never made: the +`ping` **SSE event** is a keepalive that must never reach the LLM, and probably never the +operator either. It is a transport-layer filter, not an item-routing rule. A simple `handler` emitted exactly one `block_trace` item. So the routing policy cannot be -stated as a two-bucket rule; it needs a default for 24 types, and the safe default is +stated as a two-bucket rule; it needs a default for 17 types, and the safe default is *TUI-only unless explicitly promoted*, not the reverse. ## What it does NOT establish @@ -66,5 +88,7 @@ stated as a two-bucket rule; it needs a default for 24 types, and the safe defau (theme 2) is still untested. A follow-up should boot `fsdev dev` and drive the real `/api/flows/{kind}/actions/{action}` route. - Nothing about a **generator** (LLM) flow, tool loops, or streaming deltas. +- Nothing about **same-session continuity across a runtime restart**. Both dispatches run in + one process against in-memory stores that are never torn down. - Nothing about the **pi side**. This probe and the pi probe still do not touch each other; no end-to-end path has run. diff --git a/spec-poc/epic-pi-harness/real-flow.test.ts b/spec-poc/epic-pi-harness/real-flow.test.ts index 94e0317823..02bd34f956 100644 --- a/spec-poc/epic-pi-harness/real-flow.test.ts +++ b/spec-poc/epic-pi-harness/real-flow.test.ts @@ -72,7 +72,7 @@ describe("a real FSD flow, driven the way a pi extension would drive it", () => }); }); - it("shares state across two dispatches, which is what PI-2 continuity needs", async () => { + it("runs two sequential dispatches on one session, each reaching completed with its own request id", async () => { const { createInMemoryStores } = await import("@flow-state-dev/engine"); const stores = createInMemoryStores(); @@ -109,10 +109,16 @@ describe("a real FSD flow, driven the way a pi extension would drive it", () => }); console.log("REQUEST IDS:", first.requestId, second.requestId); + // What this does NOT establish: same-session continuity, across a runtime + // restart or otherwise. The handler touches no state, both dispatches run in + // one process against in-memory stores that are never torn down, and + // `testFlow` mints a fresh request id on every call (timestamp + random) + // without reading `sessionId` or `stores` — so the inequality below would + // hold just as well for two unrelated sessions. It says only that a second + // dispatch on a shared session still reaches a terminal status and is + // identified separately from the first. expect(first.status).toBe("completed"); expect(second.status).toBe("completed"); - // Distinct requests within one shared session — the pairing a pi extension - // must keep straight when it resumes a flow across pi sessions. expect(first.requestId).not.toBe(second.requestId); }); }); From 2f7b832ef858b8d0740cc13540fb33c4be07dee2 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 10 Oct 2026 22:04:24 +0000 Subject: [PATCH 6/7] Keep a failed OMP resume owed across retries in the pi-harness epic spec 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 Claude-Session: https://claude.ai/code/session_0125zR5sy7YdPsbrrtzQ1dKf --- spec/_epics/pi-harness/BUSINESS-RULES.md | 4 ++-- spec/_epics/pi-harness/DECISIONS.md | 5 +++++ spec/_epics/pi-harness/PLAN.md | 6 +++--- spec/_epics/pi-harness/SPEC.md | 8 ++++++-- 4 files changed, 16 insertions(+), 7 deletions(-) diff --git a/spec/_epics/pi-harness/BUSINESS-RULES.md b/spec/_epics/pi-harness/BUSINESS-RULES.md index 293e8619a5..a19117676e 100644 --- a/spec/_epics/pi-harness/BUSINESS-RULES.md +++ b/spec/_epics/pi-harness/BUSINESS-RULES.md @@ -13,7 +13,7 @@ who owns it and where it's checked. ER-1 to ER-7 are the rows of the ownership m |---|---|---|---| | ER-1 | A dispatched OMP run executes in the selected checkout, produces observable output, and settles through the existing manager | LAB-163 | LAB-163's tests · the full-path proof | | ER-2 | Cancellation stops work and throws. A prompt acknowledgement, an intermediate event or a process exit is never read as completion, and a runtime stop is never relabelled as successful parking | LAB-163 ([D4](DECISIONS.md#d4)) | LAB-163's tests · the proof's negative cases | -| ER-3 | A later attempt reopens the same saved session and remembers a fact the run generated before the question, absent from the new prompt. Missing, corrupt or mismatched resume material fails rather than starting a fresh conversation | LAB-163 ([D6](DECISIONS.md#d6)) | LAB-163's tests · the full-path proof | +| ER-3 | A later attempt reopens the same saved session and remembers a fact the run generated before the question, absent from the new prompt. Missing, corrupt or mismatched resume material fails rather than starting a fresh conversation — on that attempt **and every retry after it**: for a row continuing a parked session, the manager keeps the session it owes until a harness confirms it or the row settles failed, never handing a retry `null` | LAB-163 ([D6](DECISIONS.md#d6)) | LAB-163's tests · the full-path proof | | ER-4 | A captured question reaches the manager's intake through one trusted, attempt-correlated path | LAB-164 decides · LAB-163 co-specifies ([D3](DECISIONS.md#d3)) | The joint feasibility check · both spec reviews | | ER-5 | The attempt and the worker request end at the park. No runtime process and no worker request is retained during human wait | LAB-164 ([D2](DECISIONS.md#d2)) | The full-path proof | | ER-6 | Only a real question enters the parked-question path. Tool-permission prompts and extension UI dialogs do not; they follow the host's configured allow/deny policy | LAB-164 ([D2](DECISIONS.md#d2)) | LAB-164's tests · the proof | @@ -45,7 +45,7 @@ who owns it and where it's checked. ER-1 to ER-7 are the rows of the ownership m | # | The epic is done when | Proved by | |---|---|---| | ER-19 | A real OMP run reaches a real question; the operator sees it through the existing surface after durable parking; the runtime is stopped; an answer continues the exact saved session, with a pre-question generated fact intact and absent from the answer prompt; the task settles | LAB-164's full-path evidence, reproducible, against a pinned OMP version | -| ER-20 | User cancellation stays cancellation; late, duplicate and cross-attempt answers cannot affect another run; missing or corrupt resume material and runtime failure fail safely, without a silent fresh session | LAB-164's negative cases, run separately from the happy path | +| ER-20 | User cancellation stays cancellation; late, duplicate and cross-attempt answers cannot affect another run; missing or corrupt resume material and runtime failure fail safely, without a silent fresh session on that attempt or on any retry | LAB-164's negative cases, run separately from the happy path | | ER-21 | If safe capture, stop, persistence or same-session continuation cannot be shown, the epic returns to the objective gate | The kill line. No live wait, fresh-session replay or adapter-only delivery is substituted and called complete | **Restarting a process is an adversarial condition here, not the proof.** The same session identity diff --git a/spec/_epics/pi-harness/DECISIONS.md b/spec/_epics/pi-harness/DECISIONS.md index 6a8d1e0797..10b0626184 100644 --- a/spec/_epics/pi-harness/DECISIONS.md +++ b/spec/_epics/pi-harness/DECISIONS.md @@ -107,6 +107,11 @@ that reads *consumes* is a place that child must not re-decide. - **The negative persistence claim needed an evidence field** (note). Post-stop `ENOENT` checks were added; `rpc-ui --tools ask` is the local check, and source inspection the basis for the mode distinction. +- **A failed resume must not be retried fresh** (must fix). The shipped manager reads only the + previous attempt's confirmed session, and a resume that throws confirms none, so the retry is + handed `null` and quietly starts a new conversation — D6's fail-closed lookup undone one attempt + later. LAB-163 owns keeping the obligation across retries for a parked session (ER-3); the + ordinary-retry self-heal stays for other harnesses (ER-12). - **Runtime audience: OMP first, pi deferred.** Reopen for an immediate pi audience, not because the protocol names look alike. diff --git a/spec/_epics/pi-harness/PLAN.md b/spec/_epics/pi-harness/PLAN.md index 7a7912654e..ddaf3b6104 100644 --- a/spec/_epics/pi-harness/PLAN.md +++ b/spec/_epics/pi-harness/PLAN.md @@ -21,7 +21,7 @@ document adds time to it. | Issue | Route | Consumes | Delivers | Releases | Size | |---|---|---|---|---|---| -| **LAB-163** OMP harness | spec → impl PR | The shipped harness contract and the manager's slot and policy · LAB-154's manager-side session association · [D4](DECISIONS.md#d4), [D5](DECISIONS.md#d5), [D6](DECISIONS.md#d6) | An OMP harness taking prompt input and trusted run configuration; observable events; session identity through `onSession` during the run; resume of that exact saved conversation; terminal success, runtime failure and cancellation told apart; honest startup/model/auth failures; the tested OMP version recorded | LAB-164's delivery | Medium | +| **LAB-163** OMP harness | spec → impl PR | The shipped harness contract and the manager's slot and policy · LAB-154's manager-side session association · [D4](DECISIONS.md#d4), [D5](DECISIONS.md#d5), [D6](DECISIONS.md#d6) | An OMP harness taking prompt input and trusted run configuration; observable events; session identity through `onSession` during the run; resume of that exact saved conversation, with the manager keeping that resume owed across a failed attempt's retries (ER-3); terminal success, runtime failure and cancellation told apart; honest startup/model/auth failures; the tested OMP version recorded | LAB-164's delivery | Medium | | **LAB-164** questions park and resume | spec → impl PR → the proof | LAB-163's adapter, resume and `onSession` · the existing manager intake, inbox, answer action and operator surface · [D2](DECISIONS.md#d2), [D3](DECISIONS.md#d3), [D6](DECISIONS.md#d6) | The trusted attempt-correlated handoff, co-specified with LAB-163; a captured question as durable evidence; the park where the attempt and the request end; the answer carried into a later attempt of the same session; real questions told apart from permission and extension dialogs; the negative cases; reproducible full-path evidence | The epic's wrap | Large | **The feasibility check is LAB-164's, and it is not a third issue.** It is the first thing LAB-164 @@ -55,7 +55,7 @@ ER-13 consumes it without re-parenting it. | Seam | Between | Rule | |---|---|---| | The attempt-correlated question destination | LAB-163 and LAB-164 | ER-4. LAB-164 decides it, LAB-163 co-specifies it, and both do so before either interface is final. A second route is exactly the failure the seam exists to prevent | -| `resume` and `onSession` | LAB-163 and LAB-154 (shipped) | LAB-154 owns manager-side association; LAB-163 supplies OMP's side. Neither redoes the other's half | +| `resume` and `onSession` | LAB-163 and LAB-154 (shipped) | LAB-154 owns manager-side association; LAB-163 supplies OMP's side, plus the one addition ER-3 needs: a resume owed to a parked session survives a failed attempt instead of falling back to `null`. Neither redoes the other's half | | The completed-handle park arm of the manager's intake | LAB-164 and the shipped manager | Preserve the single marker intake first (D3). Any change to the intake returns to this epic (ER-7) | | The pinned OMP version | Both issues | ER-17. One pinned version across the set's evidence; two versions makes the proof unreadable | @@ -64,7 +64,7 @@ ER-13 consumes it without re-parenting it. | Issue | What it owns | Why it isn't in the set | |---|---|---| | [FIX-1246](https://linear.app/fixpoint-labs/issue/FIX-1246) | The broader substrate same-session POC | This epic adds OMP-specific capture and stop evidence and reuses its continuity standard. It does not close or supersede it (ER-13) | -| [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154) | Manager-side session association · **done** | Consumed. LAB-163 supplies OMP's side only | +| [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154) | Manager-side session association · **done** | Consumed. LAB-163 supplies OMP's side, and adds only the sticky resume obligation ER-3 needs | | [LAB-140](https://linear.app/fixpoint-labs/issue/LAB-140) | The harness manager program · in progress | The set adds a slot to it; it does not rewrite it | | [LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) | The operator board · in review | The surface this epic reuses. Building a second one is what D1 cut | | [FIX-1241 / D-1](https://linear.app/fixpoint-labs/issue/FIX-1241) | The one-human-wait model | A standing decision D2 preserves. No child reopens it locally | diff --git a/spec/_epics/pi-harness/SPEC.md b/spec/_epics/pi-harness/SPEC.md index d0a4de722e..8c07a3e1eb 100644 --- a/spec/_epics/pi-harness/SPEC.md +++ b/spec/_epics/pi-harness/SPEC.md @@ -96,10 +96,14 @@ neither is a placeholder. ## What stays as it is - **The harness manager, the inbox, the answer action and the operator surface.** Reused, not - extended. [LAB-140](https://linear.app/fixpoint-labs/issue/LAB-140) owns the manager program, + extended, with one exception below. [LAB-140](https://linear.app/fixpoint-labs/issue/LAB-140) owns the manager program, [LAB-151](https://linear.app/fixpoint-labs/issue/LAB-151) the operator board. - **Manager-side session association** — [LAB-154](https://linear.app/fixpoint-labs/issue/LAB-154), - done. LAB-163 supplies OMP's side of `resume`/`onSession` and does not redo that work. + done. LAB-163 supplies OMP's side of `resume`/`onSession` and does not redo that work. **The one + manager change in scope:** today a resumed attempt that throws loses the session it was owed — + the retry is handed `null` and starts fresh. LAB-163 makes that resume obligation stick across + retries for a row continuing a parked session (ER-3), leaving the ordinary-retry self-heal of + other harnesses as it is (ER-12). - **Tool permissions**, which stay the host's configured allow/deny policy. - **Upstream pi.** Deferred, not refused forever — reopened for a real pi audience, not because the protocol names look alike. From 2c6f7326f7d7394c80c416766f7932fa10943221 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 10 Oct 2026 22:08:16 +0000 Subject: [PATCH 7/7] Move the pi-harness epic spec to specs/epics/LAB-162 Main now retains epic specs at specs/epics// 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 Claude-Session: https://claude.ai/code/session_0125zR5sy7YdPsbrrtzQ1dKf --- .../epics/LAB-162}/BUSINESS-RULES.md | 2 +- .../epics/LAB-162}/DECISIONS.md | 4 +- specs/epics/LAB-162/DOCS.md | 51 +++++++++++++++++++ .../epics/LAB-162}/PLAN.md | 2 +- .../epics/LAB-162}/SPEC.md | 2 +- .../epics/LAB-162}/figures/end-state.svg | 0 .../epics/LAB-162}/figures/ownership.svg | 0 .../epics/LAB-162}/figures/path.svg | 0 .../LAB-162/poc/omp-runtime-seams}/README.md | 6 +-- .../poc/omp-runtime-seams}/auth-findings.md | 0 .../poc/omp-runtime-seams}/auth-probe.ts | 0 .../poc/omp-runtime-seams}/companion.ts | 0 .../LAB-162/poc/omp-runtime-seams}/host.mjs | 0 .../poc/omp-runtime-seams}/probe-result.json | 0 .../LAB-162/poc/omp-runtime-seams}/probe.ts | 0 .../omp-runtime-seams}/real-flow-findings.md | 4 +- .../poc/omp-runtime-seams}/real-flow.test.ts | 2 +- .../poc/omp-runtime-seams}/run-ask.jsonl | 0 .../runtime-check/bridge.mjs | 0 .../omp-native-ask-evidence.json | 0 .../runtime-check/roundtrip-evidence.json | 0 .../poc/omp-runtime-seams}/tsconfig.json | 0 22 files changed, 62 insertions(+), 11 deletions(-) rename {spec/_epics/pi-harness => specs/epics/LAB-162}/BUSINESS-RULES.md (99%) rename {spec/_epics/pi-harness => specs/epics/LAB-162}/DECISIONS.md (99%) create mode 100644 specs/epics/LAB-162/DOCS.md rename {spec/_epics/pi-harness => specs/epics/LAB-162}/PLAN.md (99%) rename {spec/_epics/pi-harness => specs/epics/LAB-162}/SPEC.md (99%) rename {spec/_epics/pi-harness => specs/epics/LAB-162}/figures/end-state.svg (100%) rename {spec/_epics/pi-harness => specs/epics/LAB-162}/figures/ownership.svg (100%) rename {spec/_epics/pi-harness => specs/epics/LAB-162}/figures/path.svg (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/README.md (96%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/auth-findings.md (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/auth-probe.ts (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/companion.ts (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/host.mjs (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/probe-result.json (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/probe.ts (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/real-flow-findings.md (97%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/real-flow.test.ts (98%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/run-ask.jsonl (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/runtime-check/bridge.mjs (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/runtime-check/omp-native-ask-evidence.json (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/runtime-check/roundtrip-evidence.json (100%) rename {spec-poc/epic-pi-harness => specs/epics/LAB-162/poc/omp-runtime-seams}/tsconfig.json (100%) diff --git a/spec/_epics/pi-harness/BUSINESS-RULES.md b/specs/epics/LAB-162/BUSINESS-RULES.md similarity index 99% rename from spec/_epics/pi-harness/BUSINESS-RULES.md rename to specs/epics/LAB-162/BUSINESS-RULES.md index a19117676e..d3b597d6ad 100644 --- a/spec/_epics/pi-harness/BUSINESS-RULES.md +++ b/specs/epics/LAB-162/BUSINESS-RULES.md @@ -1,6 +1,6 @@ # LAB-162 · Rules every issue in the set obeys -[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) At epic altitude the rules aren't behaviours of one feature; they're the constraints both child specs and both implementations must satisfy, and the place a cross-spec review checks. Each says diff --git a/spec/_epics/pi-harness/DECISIONS.md b/specs/epics/LAB-162/DECISIONS.md similarity index 99% rename from spec/_epics/pi-harness/DECISIONS.md rename to specs/epics/LAB-162/DECISIONS.md index 10b0626184..c955539b31 100644 --- a/spec/_epics/pi-harness/DECISIONS.md +++ b/specs/epics/LAB-162/DECISIONS.md @@ -1,6 +1,6 @@ # LAB-162 · Decisions -[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) +[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) The calls that sit above either issue: what was chosen, what lost, why, and what each locks in for LAB-163 and LAB-164. Three are the sign-off surface. The rest were settled in review and are @@ -124,7 +124,7 @@ it is not a clean verdict on the current bytes. Completeness found the revised o **Built:** the original throwaway pi probes, plus a model-free RPC dialog probe run unchanged on installed pi 0.85.1 and OMP 18.1.14, and a separate OMP `rpc-ui` registration check. -**See it:** [`spec-poc/epic-pi-harness/`](../../../spec-poc/epic-pi-harness/README.md) on this +**See it:** [`poc/omp-runtime-seams/`](poc/omp-runtime-seams/README.md) on this branch, with its `runtime-check/` evidence files. **Showed:** both runtimes answered the same `extension_ui_request` confirmation over stdio, and OMP exposed native `ask` under `rpc-ui`. Post-stop filesystem checks found neither reported probe diff --git a/specs/epics/LAB-162/DOCS.md b/specs/epics/LAB-162/DOCS.md new file mode 100644 index 0000000000..a7d02f01c9 --- /dev/null +++ b/specs/epics/LAB-162/DOCS.md @@ -0,0 +1,51 @@ +# LAB-162 · Documentation draft + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · **Docs** + +The shared story is one: an OMP run under the harness manager can ask, park and continue. The +OMP-specific detail belongs to the two issues. The shared addition promises only what the +[kill line](SPEC.md) lets the epic claim, so it is not published until LAB-164's full-path proof +passes (ER-19, ER-20). Each issue publishes its own material with its implementation. + +## UPDATE · `apps/docs/docs/orchestration/harness-manager.md` · "Asking and being answered" + +Add after the opening paragraph: + +> A question does not have to come from a file the prompt names. When the coding agent raises a +> question itself, partway through a run, the manager records it against that attempt and parks +> the row the same way. The attempt ends and nothing is held open while a person decides. The +> answer goes through the same surface as any other question; there is no second inbox and no +> new verb. A tool-permission prompt is not a question: it follows the allow/deny policy you +> configured on the harness and never parks the row. +> +> The next attempt reopens the saved conversation. For example, if the run worked out a fact +> before it asked, the continued run still has that fact, even though the answer prompt does not +> repeat it. + +Replace "A lost session heals rather than failing" for a row continuing a parked question: + +> **A parked run continues or fails; it does not start over.** When a row is continuing a session +> it parked in, the manager keeps that session owed across retries until a harness confirms it or +> the row fails. Missing or mismatched resume data fails the attempt rather than opening a fresh +> conversation. Other rows keep the self-healing behavior above. Cancelling a run stays a +> cancellation; it is never read as a park. + +## CREATE · an OMP page under `apps/docs/docs/tools/` · UPDATE `apps/docs/docs/tools/coding-agents.md` · the harness table + +The OMP harness: its package, options, emitted items, errors, and the tested OMP version (ER-17). +The package name and options are not decided yet. LAB-163's `DOCS.md` drafts this material. + +## UPDATE · `packages/harness-manager/README.md` · "Continuing a run" + +One paragraph with the parked-session rule above, linking the guide for the detail. + +## Ownership + +| Material | Publisher | Specific draft | +|---|---|---| +| Runtime-raised questions park and continue (first addition above) | LAB-164, after the full-path proof | This document | +| Parked-session resume rule (replacement above) and the README paragraph | LAB-163 | Its `DOCS.md`, reconciled with this one | +| OMP harness page and the coding-agents table row | LAB-163 | Its `DOCS.md` | + +If the kill line fires, the first addition is not published. No page about upstream pi, an +operator console or tool approvals is in scope ([D1](DECISIONS.md#d1), ER-9 to ER-11). diff --git a/spec/_epics/pi-harness/PLAN.md b/specs/epics/LAB-162/PLAN.md similarity index 99% rename from spec/_epics/pi-harness/PLAN.md rename to specs/epics/LAB-162/PLAN.md index ddaf3b6104..be6fe2ce92 100644 --- a/spec/_epics/pi-harness/PLAN.md +++ b/specs/epics/LAB-162/PLAN.md @@ -1,6 +1,6 @@ # LAB-162 · Plan -[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan** +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan** · [Docs](DOCS.md) An epic plan sequences the work and says what each piece entails. It does not say how to build any piece; that's each issue's own plan. IDs cross-reference [DECISIONS.md](DECISIONS.md) (D-n) and diff --git a/spec/_epics/pi-harness/SPEC.md b/specs/epics/LAB-162/SPEC.md similarity index 99% rename from spec/_epics/pi-harness/SPEC.md rename to specs/epics/LAB-162/SPEC.md index 8c07a3e1eb..3ef48d52a5 100644 --- a/spec/_epics/pi-harness/SPEC.md +++ b/specs/epics/LAB-162/SPEC.md @@ -1,6 +1,6 @@ # LAB-162 · OMP coding runs ask, park, and continue -**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) +**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) Epic · 2 issues · Development Workflow Orchestration · [LAB-162](https://linear.app/fixpoint-labs/issue/LAB-162) · [#1612](https://github.com/fixpoint-labs/flow-state-dev/pull/1612), never merged diff --git a/spec/_epics/pi-harness/figures/end-state.svg b/specs/epics/LAB-162/figures/end-state.svg similarity index 100% rename from spec/_epics/pi-harness/figures/end-state.svg rename to specs/epics/LAB-162/figures/end-state.svg diff --git a/spec/_epics/pi-harness/figures/ownership.svg b/specs/epics/LAB-162/figures/ownership.svg similarity index 100% rename from spec/_epics/pi-harness/figures/ownership.svg rename to specs/epics/LAB-162/figures/ownership.svg diff --git a/spec/_epics/pi-harness/figures/path.svg b/specs/epics/LAB-162/figures/path.svg similarity index 100% rename from spec/_epics/pi-harness/figures/path.svg rename to specs/epics/LAB-162/figures/path.svg diff --git a/spec-poc/epic-pi-harness/README.md b/specs/epics/LAB-162/poc/omp-runtime-seams/README.md similarity index 96% rename from spec-poc/epic-pi-harness/README.md rename to specs/epics/LAB-162/poc/omp-runtime-seams/README.md index a285e94c36..ecbf549b66 100644 --- a/spec-poc/epic-pi-harness/README.md +++ b/specs/epics/LAB-162/poc/omp-runtime-seams/README.md @@ -1,6 +1,6 @@ # POC evidence — OMP / pi runtime seams -Throwaway, never merged. The [current epic](../../spec/_epics/pi-harness/SPEC.md) is +Throwaway, never merged. The [current epic](../../SPEC.md) is OMP-only and harness-only. Its durable question and same-session continuation proof remains open. The earlier pi companion investigation below is historical, not the current design or acceptance claim. @@ -37,7 +37,7 @@ These checks remove the need to assume a bespoke HTTP/file-mailbox live-answer transport. They do **not** prove tool interception, authorization, safe stop, durable parking, restart-resume, or the full FSD manager loop. Pinned source and the runtime comparison are in the epic's -[DECISIONS.md](../../spec/_epics/pi-harness/DECISIONS.md); LAB-164 owns the remaining +[DECISIONS.md](../../DECISIONS.md); LAB-164 owns the remaining full-path proof. ## Original question (superseded) @@ -132,4 +132,4 @@ that a model-invoked `flow_ask` suspends the turn until the host answers. > `labs/conductor/src/manager.ts:1244`. That code has since been superseded by the published > `@flow-state-dev/harness-manager`, where the same ordering is a *stated invariant* at > `manager.ts:1498–1504`. The finding got stronger, not weaker — see the epic-spec's - > [DECISIONS.md](../../spec/_epics/pi-harness/DECISIONS.md). + > [DECISIONS.md](../../DECISIONS.md). diff --git a/spec-poc/epic-pi-harness/auth-findings.md b/specs/epics/LAB-162/poc/omp-runtime-seams/auth-findings.md similarity index 100% rename from spec-poc/epic-pi-harness/auth-findings.md rename to specs/epics/LAB-162/poc/omp-runtime-seams/auth-findings.md diff --git a/spec-poc/epic-pi-harness/auth-probe.ts b/specs/epics/LAB-162/poc/omp-runtime-seams/auth-probe.ts similarity index 100% rename from spec-poc/epic-pi-harness/auth-probe.ts rename to specs/epics/LAB-162/poc/omp-runtime-seams/auth-probe.ts diff --git a/spec-poc/epic-pi-harness/companion.ts b/specs/epics/LAB-162/poc/omp-runtime-seams/companion.ts similarity index 100% rename from spec-poc/epic-pi-harness/companion.ts rename to specs/epics/LAB-162/poc/omp-runtime-seams/companion.ts diff --git a/spec-poc/epic-pi-harness/host.mjs b/specs/epics/LAB-162/poc/omp-runtime-seams/host.mjs similarity index 100% rename from spec-poc/epic-pi-harness/host.mjs rename to specs/epics/LAB-162/poc/omp-runtime-seams/host.mjs diff --git a/spec-poc/epic-pi-harness/probe-result.json b/specs/epics/LAB-162/poc/omp-runtime-seams/probe-result.json similarity index 100% rename from spec-poc/epic-pi-harness/probe-result.json rename to specs/epics/LAB-162/poc/omp-runtime-seams/probe-result.json diff --git a/spec-poc/epic-pi-harness/probe.ts b/specs/epics/LAB-162/poc/omp-runtime-seams/probe.ts similarity index 100% rename from spec-poc/epic-pi-harness/probe.ts rename to specs/epics/LAB-162/poc/omp-runtime-seams/probe.ts diff --git a/spec-poc/epic-pi-harness/real-flow-findings.md b/specs/epics/LAB-162/poc/omp-runtime-seams/real-flow-findings.md similarity index 97% rename from spec-poc/epic-pi-harness/real-flow-findings.md rename to specs/epics/LAB-162/poc/omp-runtime-seams/real-flow-findings.md index 723f93846d..d52bb72631 100644 --- a/spec-poc/epic-pi-harness/real-flow-findings.md +++ b/specs/epics/LAB-162/poc/omp-runtime-seams/real-flow-findings.md @@ -4,11 +4,11 @@ The first probe in this directory tested pi's half against a **mock FSD host**, the actual integration untested at both ends and let the spec invent FSD shapes that do not exist. This runs a genuine flow through `runAction` — the same engine the server uses. -Run (from `packages/testing`, which resolves the workspace deps; `spec-poc/` is not a +Run (from `packages/testing`, which resolves the workspace deps; `specs/` is not a workspace member): ```bash -cp real-flow.test.ts ../../packages/testing/test/tmp/ && cd ../../packages/testing +cp real-flow.test.ts ../../../../../packages/testing/test/tmp/ && cd ../../../../../packages/testing npx vitest run test/tmp/real-flow.test.ts ``` diff --git a/spec-poc/epic-pi-harness/real-flow.test.ts b/specs/epics/LAB-162/poc/omp-runtime-seams/real-flow.test.ts similarity index 98% rename from spec-poc/epic-pi-harness/real-flow.test.ts rename to specs/epics/LAB-162/poc/omp-runtime-seams/real-flow.test.ts index 02bd34f956..a3a6cbc4f6 100644 --- a/spec-poc/epic-pi-harness/real-flow.test.ts +++ b/specs/epics/LAB-162/poc/omp-runtime-seams/real-flow.test.ts @@ -7,7 +7,7 @@ * server uses") so the epic's transport claims rest on the real item stream and * the real terminal-status vocabulary rather than on a mock's invented shapes. * - * Run: pnpm vitest run spec-poc/epic-pi-harness/real-flow.test.ts + * Run: pnpm vitest run specs/epics/LAB-162/poc/omp-runtime-seams/real-flow.test.ts */ import { describe, expect, it } from "vitest"; import { handler } from "@flow-state-dev/core"; diff --git a/spec-poc/epic-pi-harness/run-ask.jsonl b/specs/epics/LAB-162/poc/omp-runtime-seams/run-ask.jsonl similarity index 100% rename from spec-poc/epic-pi-harness/run-ask.jsonl rename to specs/epics/LAB-162/poc/omp-runtime-seams/run-ask.jsonl diff --git a/spec-poc/epic-pi-harness/runtime-check/bridge.mjs b/specs/epics/LAB-162/poc/omp-runtime-seams/runtime-check/bridge.mjs similarity index 100% rename from spec-poc/epic-pi-harness/runtime-check/bridge.mjs rename to specs/epics/LAB-162/poc/omp-runtime-seams/runtime-check/bridge.mjs diff --git a/spec-poc/epic-pi-harness/runtime-check/omp-native-ask-evidence.json b/specs/epics/LAB-162/poc/omp-runtime-seams/runtime-check/omp-native-ask-evidence.json similarity index 100% rename from spec-poc/epic-pi-harness/runtime-check/omp-native-ask-evidence.json rename to specs/epics/LAB-162/poc/omp-runtime-seams/runtime-check/omp-native-ask-evidence.json diff --git a/spec-poc/epic-pi-harness/runtime-check/roundtrip-evidence.json b/specs/epics/LAB-162/poc/omp-runtime-seams/runtime-check/roundtrip-evidence.json similarity index 100% rename from spec-poc/epic-pi-harness/runtime-check/roundtrip-evidence.json rename to specs/epics/LAB-162/poc/omp-runtime-seams/runtime-check/roundtrip-evidence.json diff --git a/spec-poc/epic-pi-harness/tsconfig.json b/specs/epics/LAB-162/poc/omp-runtime-seams/tsconfig.json similarity index 100% rename from spec-poc/epic-pi-harness/tsconfig.json rename to specs/epics/LAB-162/poc/omp-runtime-seams/tsconfig.json