feat(paseo-omp): opt-in correlated-user terminal ownership for unkeyed OMP runtimes

[Trevor-Mengel]

What

An opt-in, off-by-default escape hatch for OMP runtimes that do not key agent_end with the originating request:

PASEO_OMP_LEGACY_TERMINAL_OWNERSHIP=correlated-user

Follow-up to #81. #81 remains the secure default; this PR covers the compatibility gap until a keyed OMP release is published.

Why

Published OMP releases through 18.2.5 emit unkeyed terminal events for ordinary prompts. On those runtimes, the strict ownership guard cannot authenticate a later-turn agent_end, so ordinary multi-prompt sessions fail closed after the ownership deadline and the runtime is invalidated. The upstream request-keying fix remains open as can1357/oh-my-pi#12331.

The mode gives operators an explicit availability-for-integrity trade while keeping the default unchanged.

How

When enabled, and only for a turn that already requires terminal ownership, the plugin accepts one additional evidence source: an exact-text user echo for the active prompt correlated to a branch entry ID that is new relative to a valid branch watermark.

The ordering is fenced at event observation time:

• correlation initiated by a matching user echo observed before agent_end may finish afterward and authorize that terminal;
• a user echo first observed after agent_end cannot authorize it retroactively;
• buffered evidence is promoted for legacy runtimes even when the prompt acknowledgement omits agentInvoked;
• a direct entryId with different prompt text cannot grant ownership.

Invalid watermarks, unavailable or ambiguous history, and uncorrelated users still fail closed. Keyed requestId handling, ownership deadlines, runtime invalidation, and branch-history bounds remain unchanged.

The switch is read once per session from the provider environment. Only the exact value correlated-user enables it. Automatic inheritance excludes it, and child env or inheritEnv configuration attempting to forward it is rejected.

The residual risk is explicit: after a matching user echo for the active prompt is observed, a later unkeyed terminal is attributed to that turn without cryptographic or protocol-level proof. Remove the escape hatch once OMP publishes keyed agent_end events.

Verification

• npm test -- tests/provider.test.ts tests/omp-rpc.test.ts: 370 passed.
• npm run typecheck: passed.
• npm run check: passed.
• npm run test:coverage: 693 passed, 6 skipped; thresholds passed.
• PASEO_OMP_REAL_E2E=1 PASEO_OMP_VERSION=18.2.0 npm test -- tests/provider.real.e2e.test.ts: 4 passed, including three sequential turns on one runtime with legacy mode enabled.

Thank you @Trevor-Mengel for isolating the published-runtime compatibility gap and providing the real-process evidence. The follow-up hardens the proposed fallback's ordering and prompt-correlation boundaries while preserving the design and default-off safety decision.

Release Please owns CHANGELOG.md and package versions, so neither is changed.

[omercnet]

Thank you @Trevor-Mengel for isolating this compatibility gap and supplying the real-process evidence. I pushed a maintainer follow-up that keeps your default-off design while fixing the buffered-event path, fencing asynchronous correlation by observed event order, requiring exact prompt text before direct IDs grant ownership, and preventing the provider-only switch from reaching the child. I also added focused race regressions and a real three-turn OMP test. The strict default remains unchanged.

[omercnet]

Thank you again for isolating the published-OMP compatibility gap and validating the multi-turn failure. Main now contains #89, which supersedes this PR with an always-available ordered fallback: keyed terminals remain authoritative, while unkeyed terminals require fresh user correlation, later current-turn assistant activity, confirmed idle state, and no permission, tool, steer, or child-session conflict. It also ignores active ambiguous candidates and fails only the Paseo turn for confirmed-idle ambiguity instead of invalidating the runtime. Rebasing #82 would reintroduce an obsolete parallel state machine and operator switch, so I am closing it as superseded rather than resolving mechanical conflicts. The diagnosis and real-process evidence here directly informed the replacement.