EPIC — OMP Native Chat migration to ACP with parity-first cutover

Program: #66

Goal

Migrate OMP Native Chat from the existing terminal/transcript implementation to native ACP, preserving at least full behavioral and reliability parity before ACP becomes the default.

Canonical design: #20

This epic is now OMP-only. Pi has been split into a separate cross-repo epic/program because Pi first needs an ACP bridge/adapter before Orca onboarding.

Foundation

The required generic structured-provider stack is merged into upstream Orca main as of October 6, 2026:

registered provider identity/capabilities;
open wire/storage agent vocabulary;
managed provider process lifecycle;
shared timeline assembler;
provider-event journal operations;
standalone ACP client;
ACP → timeline translation.

We therefore develop from current upstream main, not Brennan's former stack branch.

Migration rule

No existing OMP Native Chat guarantee may become weaker under ACP.

Parity is a release gate, not a best-effort target.

ACP extensions and new OMP capabilities are intentionally a later phase.

Execution plan

Phase 0 — define the migration contract

OMP-0 — Freeze the terminal/transcript Native Chat parity contract #52 — OMP-0: inventory/freeze terminal Native Chat parity guarantees

Phase 1 — establish native ACP

OMP-1 — Register OMP as a structured ACP provider and launch omp acp #53 — OMP-1: register OMP and launch omp acp through shared provider lifecycle — depends on OMP-0 — Freeze the terminal/transcript Native Chat parity contract #52
OMP-2 — Migrate OMP history, reasoning, tools, edits, usage, and timeline parity to ACP #54 — OMP-2: migrate history/timeline/rendering parity — depends on OMP-1 — Register OMP as a structured ACP provider and launch omp acp #53
OMP-3 — Migrate OMP composer input, options, commands, images, and interactions parity to ACP #55 — OMP-3: migrate input/options/commands/interactions parity — depends on OMP-1 — Register OMP as a structured ACP provider and launch omp acp #53

#54 and #55 may proceed in parallel once the basic ACP provider is live.

Phase 2 — reliability + cutover

OMP-4 — Prove ACP reliability parity for restart, cancel, process death, mobile, and runtime ownership #56 — OMP-4: restart/cancel/process/mobile/runtime parity — depends on OMP-2 — Migrate OMP history, reasoning, tools, edits, usage, and timeline parity to ACP #54 + OMP-3 — Migrate OMP composer input, options, commands, images, and interactions parity to ACP #55
OMP-5 — Make ACP the default OMP Chat path with safe legacy-session adoption and fallback #57 — OMP-5: make ACP the default and migrate/fallback legacy sessions — depends on OMP-4 — Prove ACP reliability parity for restart, cancel, process death, mobile, and runtime ownership #56

Phase 3 — extend beyond terminal parity

OMP-6 — Expose the full useful OMP ACP surface through extension/unknown ACP messages #58 — OMP-6: consume OMP ACP extensions / unknown ACP messages — depends on OMP-5 — Make ACP the default OMP Chat path with safe legacy-session adoption and fallback #57
OMP-7 — Clean up OMP Chat migration, retire obsolete structured-terminal glue, and prepare upstream contribution #59 — OMP-7: cleanup, hardening, upstream readiness — depends on OMP-6 — Expose the full useful OMP ACP surface through extension/unknown ACP messages #58

Dependency graph

#52 parity contract
  ↓
#53 basic native OMP ACP provider
  ├──────────────┐
  ↓              ↓
#54 timeline     #55 controls/interactions
  └───────┬──────┘
          ↓
#56 reliability / restart / runtime parity
          ↓
#57 ACP-default migration + safe fallback
          ↓
#58 full OMP ACP extension set
          ↓
#59 cleanup / upstream-ready

Required parity dimensions

At minimum the epic must account for:

existing conversation/session visibility;
transcript/history ordering;
reasoning;
tools and edit rendering;
model/provider/usage metadata;
compaction boundaries;
session options/model switching;
slash commands;
skills/autocomplete;
images;
questions/approvals;
local commands;
status/settlement;
resume/restart;
mobile projection;
current supported runtime/locality cases;
errors/failures;
no duplicate replay.

#52 owns the final authoritative matrix.

Cutover rule

Before #57:

terminal/transcript Native Chat remains available;
ACP can be experimental/provider-gated.

At #57:

ACP becomes default only for OMP versions/environments proven compatible;
unsupported cases continue using the old path;
existing stored chats either adopt the same OMP session safely or stay on fallback.

Do not delete fallback code simply to simplify the migration.

Extension rule

#58 may use unknown/extension ACP messages to expose OMP capabilities beyond the previous terminal path.

Provider-neutral concepts should be contributed to Orca's generic ACP layer.

OMP-specific concepts remain a narrow dialect.

Cross-repo provider fixes

Provider-side gaps belong in 44madfire/oh-my-pi, linked to this epic.

Do not expand this epic into Pi work.

Completion criteria

ACP OMP is at least feature-parity with current terminal Native Chat.
ACP OMP is at least reliability-parity with current terminal Native Chat.
Existing compatible OMP conversations can resume through ACP without duplication/loss.
Unsupported/legacy cases fall back explicitly.
ACP is the default structured Chat path for supported OMP.
Full useful OMP ACP extension set is mapped or explicitly classified.
Ordinary OMP terminal operation remains available.
Claude/Codex/other structured providers regressions remain green.
Provider-side fixes, if any, live in OMP rather than Orca workarounds.

Upstream dependency is now satisfied: can1357/oh-my-pi#12900 merged on 2026-09-23 at 6f2233877756b5553ce520756dd90315d2ff6ee3.

The shared Pi-family routing plan is therefore unblocked against canonical upstream OMP. No downstream OMP compatibility fork is required for the core history/tree/thinking RPC surface.

Implementation can proceed with #22 (durable Pi/OMP identity + routing) and #23 (shared Pi-family RPC transport) as the first workstreams, followed by the existing dependency chain #24–#30.

PIF epic implementation complete — all nine children merged into the epic integration branch

All child issues #22–#30 are implemented, independently reviewed, and merged into
44madfire/epic-native-pi-family-structured-sessions-over-p (head 7f7e9f785).
Nothing was merged to main.

Issue	PR	Review outcome
#22 PIF-1 durable pi/omp identity + routing	#42	BLOCK (fail-closed capability) → fixed → PASS
#23 PIF-2 shared Pi-family RPC transport	#43	BLOCK (Pi-only settle predicate exposed) → fixed → PASS
#24 PIF-3 acquisition, exact resume, proven close	#45	PASS
#25 PIF-4 dispatch admission + history settlement	#47	BLOCK ×2 (settlement race, fabricated identity) → fixed → PASS
#26 PIF-5 streaming journal + backpressure	#46	PASS (+ CI gate fix)
#27 PIF-6 cancellation + exactly-once prompt answers	#49	PASS
#28 PIF-7 options, command-discovery dialect, compaction	#44	PASS
#29 PIF-8 history reconciliation + structured↔TUI continuity	#48	PASS
#30 PIF-9 end-to-end hardening + superseded-path inventory	#50	BLOCK (OMP phantom-turn wedge) → fixed → PASS

Verification on the merged epic branch

tsc --noEmit -p config/tsconfig.node.json → exit 0.
vitest run src/main/pi → 597 passed, 6 skipped, 5 failed. All five failures are the
supportsCreate(LOCAL, ...) location-gate assertions and were verified to fail
identically on the pristine pre-epic commit f4273161e: the
@vscode/windows-process-tree native addon cannot be rebuilt in this environment, so
the Windows process start-time proof is unavailable and the gate fails closed by
design. They are environment artifacts, not regressions.
git diff f4273161e..HEAD -- src/main/claude src/main/codex src/main/claude-accounts src/main/codex-accounts
is empty: Claude/Codex are untouched.
The router-level integration suite exercises the real
router → single Pi-family adapter → production backend → scripted pi/omp children.

Epic invariants verified

Orca remains the only durable structured-session/lifecycle authority.
One Pi-family adapter owns both discriminants; no sibling OMP adapter exists and
neither provider routes through external, plugin IPC, or orca-pi.
The provider discriminant is part of root identity; equal sessionId across Pi and OMP
never compares as the same root.
Session files are opaque and same-provider only; cross-open is refused.
Final settlement is dialect-specific through the provider flavor (Pi agent_settled;
OMP terminal agent_end { isTerminal !== false }) and lives on the live session, not
the transport.
Delivery ambiguity stays unknown and is never auto-resent.

Notable findings from review

Three blockers were real production defects rather than review noise:

[SUPERSEDED] PIF-1 — Make Pi and OMP first-class durable structured providers in shared routing/identity #22 — widening the durable handle guard to accept omp also made capability gates
answer "structured launch supported" for omp while the RPC create/attach path still
refused it. That stranded a provisional chat as visibility-unknown with no terminal
fallback, and let an omp attach spawn a pi --mode rpc child before the durable
store rejected it. Fixed with an explicit creatability set separate from handle
validity; later widened by [SUPERSEDED] PIF-3 — Implement Pi-family acquisition, exact resume, process identity, and proven close #24 only once a genuine acquisition path existed.
[SUPERSEDED] PIF-4 — Implement Pi-family dispatch admission and history-backed submission settlement #25 — dispatch correlation was armed after the prompt ack, so a boundary frame
coalesced into the same stdout read was observed with nothing pending and never
retried (reproduced as a 5/15 flaky test; now 15/15 after arming before the write,
mirroring the existing Codex ordering). Separately, a failed pre-dispatch history read
was indistinguishable from a genuinely fresh session, so settlement could adopt an
unrelated entry id. Both re-verified closed by a second review.
[SUPERSEDED] PIF-9 — Remove superseded Pi/OMP bridge paths and harden end-to-end structured integration #30 — prompt_result { agentInvoked:false } (OMP local-only) never cleared the live
turn, so a second prompt was refused with already-streaming and readResumeHistory
threw PI_HISTORY_BUSY, permanently wedging the conversation and breaking the [SUPERSEDED] PIF-8 — Implement Pi-family provider-history reconciliation and structured↔TUI continuity #29
TUI→structured rebuild. The regression guard was confirmed by reverting only the driver
change and watching the strengthened test fail.

The changed-code quality gate caught real type-assertion violations on #25/#26 that
reviewers had graded non-blocking; because CI enforces that gate, both were fixed before
their PRs were submitted.

Retention decision on #30

Issue #30's inventory listed ten legacy paths for potential deletion. Review audited each
one independently and agreed with the implementer's retention of all ten: they are the
live direct-RPC implementation (transport, driver chain, translation), the adapter's own
dependency contract, the separately-gated SNC1.3 dev seam that packaged Orca never
installs, or ordinary TUI/status functionality still needed outside structured Native
Chat. No deletion was safe, so none was made — a verified finding rather than an omission.

Known follow-ups (recorded in PR bodies, not blocking)

A deterministic test pinning the arm-before-write ordering; stale-trigger fencing;
prompt_result id correlation; an end-to-end runtime late-settlement test; the double
image read on the dispatch path; payload bounding; and the fact that settlement remains
event-driven, so a single-turn session can retain a pending until the restart path
reconciles it. #30 additionally noted that its new suite is router-level, so #30's
"host-level" wording is satisfied by composing it with the existing restart-settlement and
handoff suites.

Not done

The optional real-binary smoke tests (pi --mode rpc / omp --mode rpc readiness and
clean close) were not run, since they require installed provider binaries and were
deliberately specified not to become a CI dependency.

Completion-report review — BLOCK before epic close / main merge

The report is well supported on the integration branch itself: all nine child PRs are merged into 44madfire/epic-native-pi-family-structured-sessions-over-p (current merge head 7f7e9f785), the branch is 27 commits ahead / 0 behind main, and the child PR review history matches the report.

I found two current-upstream OMP compatibility blockers plus one unmet #30 acceptance requirement.

1. BLOCK — current OMP local-only prompt completion is not handled

The merged Orca branch still models OMP local-only completion as a later:

prompt_result { agentInvoked:false }

and PiRpcSessionDriver.deliverPiRecord() clears activeOp only when that record arrives.

But canonical OMP has moved on. In current OMP 18.4.5:

an accepted prompt completes exactly once;
if it completes locally, the prompt response itself carries data.agentInvoked:false;
no later prompt_result is emitted for that prompt;
otherwise a later prompt_result is emitted and correlated by the prompt command id.

OMP documents this explicitly in docs/rpc.md, and its own RpcClient returns immediately when response data.agentInvoked === false.

Orca currently discards that information: PiRpcConnectionCommands.prompt() returns Promise<void> and ignores the response payload. Against current OMP, a locally handled command can therefore leave activeOp armed forever — the same user-visible wedge #50 fixed for the older scripted behavior (follow-up dispatch rejected as already-streaming; resume history remains busy).

Required repair: carry the prompt acknowledgement/result metadata (and request id) through the Pi-family connection/driver, retire a local-only op directly from data.agentInvoked:false, and update the OMP scripted fixture/test so local-only completion has no later prompt_result.

This is also the right place to close the existing “prompt_result id correlation” follow-up: current upstream explicitly requires correlation on id.

2. BLOCK — OMP final-settlement predicate is stale

The epic currently treats:

OMP final settle = agent_end { isTerminal !== false }

Current OMP now explicitly separates:

terminal agent_end = one agent run yielded;
session_settled = the entire session is quiescent (no live/admitted run, queued message, or background work that can wake it again).

Current OMP also puts a sessionSettled boolean on correlated prompt_result.

That distinction matters to Orca: using terminal agent_end as whole-session settlement can clear activity/prompts, run history settlement, or allow handoff/new work while agent-owned background work can still wake OMP again.

Required repair: revise the OMP flavor/lifecycle contract to use current upstream session-quiescence semantics. Treat agent_end as a run/yield boundary, use correlated prompt_result for the prompt's outcome, and use session_settled (or equivalent proven state) for whole-session idle/finality. Update #20/#21's dialect table and the #24/#25/#26/#30 fixtures accordingly.

The original baseline at OMP PR stablyai#12900 was valid when designed, but #21 says OMP is supported at or after that baseline. The completed branch needs to match canonical OMP today, not only the older fixture.

3. MAJOR — #30's required host-level integration suite is still missing

#30 explicitly requires:

at least one host-level scripted integration suite that exercises the real Orca structured host/router/adapter stack

and says not to bypass the host by testing only the adapter.

The new pi-family-router-integration.test.ts starts at:

StructuredAgentSessionAdapterRouter
  → PiStructuredSessionAdapter
  → production backend
  → scripted child

It does not instantiate StructuredAgentSessionHost, the durable record store, lease/fence lifecycle, or real journal host path.

The completion report acknowledges this and argues that the router suite plus separate restart/handoff/record tests “compose” to satisfy the requirement. I checked those suites: pi-family-restart-settlement.test.ts and pi-family-tui-handoff.test.ts also do not instantiate StructuredAgentSessionHost.

That is useful layered coverage, but it is not the explicit host-level integration gate we wrote into #30.

Required repair: add one scripted Pi/OMP integration test that actually enters through StructuredAgentSessionHost and reaches the shared adapter/production backend/scripted child. It need not duplicate every #30 scenario, but it should prove the primary happy-path ownership/journal lifecycle through the host boundary.

Validation caveat (not a code blocker by itself)

There are no GitHub workflow runs on integration head 7f7e9f785. The reported 5 src/main/pi failures were reproduced on the pre-epic base and are credibly environment-specific, and Claude/Codex source directories are unchanged. Still, before merging the epic branch to main, the final integration PR should run the normal CI on a supported environment so the epic criterion “Claude/Codex regressions remain green” is demonstrated rather than inferred.

What looks good

I do not see a reason to reopen the earlier child-PR blockers that were fixed:

durable Pi/OMP identity + same-adapter routing;
fail-closed OMP creatability transition;
transport-only shared RPC layer;
arm-before-write dispatch correlation;
fail-closed pre-dispatch history proof;
exactly-once prompt-answer ownership;
command-discovery dialect;
structural Pi/OMP history normalization;
exact same-provider session-file handoff;
proven-exit discipline;
[SUPERSEDED] PIF-9 — Remove superseded Pi/OMP bridge paths and harden end-to-end structured integration #30's retention inventory.

The remaining items in the report such as double image reads, stale-trigger attempts (where settlement proof itself is generation-fenced), dead-code hygiene, and optional real-binary smoke tests can remain follow-ups once the three items above are resolved.

Review outcome: implementation is close, but I would not mark #21 complete or open the final main-merge PR as ready until the current OMP prompt/session-settlement contract is updated and the required host-level integration test exists.

Re-review status — blockers still open

I re-checked the implementation after the previous completion-report review.

There is currently no new code delta on the epic integration branch:

branch: 44madfire/epic-native-pi-family-structured-sessions-over-p
head remains: 7f7e9f7851939f89ebebfdf1970d9c742e6e42b2
comparison against the previously reviewed head: identical (0 commits / 0 files changed)
no newer PR targeting the epic branch was found after PIF-9: Pi-family end-to-end hardening and superseded-path inventory #50

I also re-checked canonical OMP upstream. Current OMP remains on the newer prompt/session lifecycle contract described in the prior review:

local-only prompts may complete in the immediate prompt response with data.agentInvoked:false and no later prompt_result;
later prompt_result frames are correlated by prompt request id;
terminal agent_end is a run/yield boundary, while session_settled represents whole-session quiescence.

The epic branch still:

discards prompt response data in PiRpcConnectionCommands.prompt(): Promise<void>;
clears OMP local-only activity from an uncorrelated later prompt_result;
treats terminal OMP agent_end as final settlement;
lacks the explicit StructuredAgentSessionHost → router → adapter → production backend → scripted child integration test required by [SUPERSEDED] PIF-9 — Remove superseded Pi/OMP bridge paths and harden end-to-end structured integration #30.

So the previous review outcome remains unchanged: BLOCK before epic close / merge to main.

Once a repair branch/PR is pushed, the next review should focus narrowly on:

prompt response metadata + request-id correlation;
OMP prompt_result / session_settled handling;
the host-level integration test;
final CI on the resulting epic head.

feat(pi-family): resolve #21 completion-review blockers for OMP contr…

Architecture pivot recorded: this epic now targets ACP for both OMP and Pi on top of Brennan's active registered-provider/ACP stack.

New path:

OMP-0 — Freeze the terminal/transcript Native Chat parity contract #52 downstream branch on Brennan's composed stack
OMP-1 — Register OMP as a structured ACP provider and launch omp acp #53 ACP contract/parity audit
OMP-2 — Migrate OMP history, reasoning, tools, edits, usage, and timeline parity to ACP #54 OMP via native omp acp
OMP-3 — Migrate OMP composer input, options, commands, images, and interactions parity to ACP #55 Pi via community pi-acp proof
OMP-4 — Prove ACP reliability parity for restart, cancel, process death, mobile, and runtime ownership #56 direct Pi SDK→ACP temporary adapter
OMP-5 — Make ACP the default OMP Chat path with safe legacy-session adoption and fallback #57 parity
OMP-6 — Expose the full useful OMP ACP surface through extension/unknown ACP messages #58 production hardening
OMP-7 — Clean up OMP Chat migration, retire obsolete structured-terminal glue, and prepare upstream contribution #59 eventual native Pi ACP migration / shim retirement

Direct Pi/OMP RPC remains reference/fallback research only unless the ACP parity work finds a concrete blocker.

Superseded by the v2 plan in #67 (project https://github.com/users/44madfire/projects/3).

Navigation Menu

Repository navigation

EPIC — OMP Native Chat migration to ACP with parity-first cutover #21

Goal

Foundation

Migration rule

Execution plan

Phase 0 — define the migration contract

Phase 1 — establish native ACP

Phase 2 — reliability + cutover

Phase 3 — extend beyond terminal parity

Dependency graph

Required parity dimensions

Cutover rule

Extension rule

Cross-repo provider fixes

Completion criteria

PIF epic implementation complete — all nine children merged into the epic integration branch

Verification on the merged epic branch

Epic invariants verified

Notable findings from review

Retention decision on #30

Known follow-ups (recorded in PR bodies, not blocking)

Not done

Completion-report review — BLOCK before epic close / main merge

1. BLOCK — current OMP local-only prompt completion is not handled

2. BLOCK — OMP final-settlement predicate is stale

3. MAJOR — #30's required host-level integration suite is still missing

Validation caveat (not a code blocker by itself)

What looks good

Re-review status — blockers still open

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

EPIC — OMP Native Chat migration to ACP with parity-first cutover #21

Description

Goal

Foundation

Migration rule

Execution plan

Phase 0 — define the migration contract

Phase 1 — establish native ACP

Phase 2 — reliability + cutover

Phase 3 — extend beyond terminal parity

Dependency graph

Required parity dimensions

Cutover rule

Extension rule

Cross-repo provider fixes

Completion criteria

Activity

44madfire commented on Sep 23, 2026

44madfire commented on Sep 26, 2026

PIF epic implementation complete — all nine children merged into the epic integration branch

Verification on the merged epic branch

Epic invariants verified

Notable findings from review

Retention decision on #30

Known follow-ups (recorded in PR bodies, not blocking)

Not done

44madfire commented on Sep 30, 2026

Completion-report review — BLOCK before epic close / main merge

1. BLOCK — current OMP local-only prompt completion is not handled

2. BLOCK — OMP final-settlement predicate is stale

3. MAJOR — #30's required host-level integration suite is still missing

Validation caveat (not a code blocker by itself)

What looks good

44madfire commented on Oct 1, 2026

Re-review status — blockers still open

44madfire commented on Oct 5, 2026

44madfire commented on Oct 7, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions