[Feature] Automation-safe session lifecycle contract for external orchestrators

Problem or use case

External orchestrators need to create, monitor, stop, and reconcile long-running Omnigent sessions across process crashes and network retries. The current public session API does not provide a complete at-least-once-safe contract:

• POST /v1/sessions has no caller idempotency key, so a response-loss retry can create a duplicate session and duplicate work.
• GET /v1/sessions/{id}/stream is explicitly live-tail only, with no durable cursor or Last-Event-ID replay. Subscribe-then-snapshot is appropriate for interactive UI state, but an orchestrator cannot prove it processed every lifecycle/evidence edge after a crash.
• POST /v1/sessions/{id}/events already implements non-destructive interrupt and stop_session behavior, but the route is include_in_schema=false, so generated clients and capability discovery cannot rely on it as a supported public operation.
• Headless authentication is tracked separately in omnigent-ai/omnigent#3976.

This blocks safe use of Omnigent as an execution provider behind durable workflow systems: they must never duplicate launch, silently skip evidence, or substitute destructive DELETE for cancellation.

Proposed solution

Define a versioned public automation contract while preserving current UI behavior:

1. Accept a bounded Idempotency-Key header on POST /v1/sessions for both JSON and multipart create. Persist the authenticated principal, request fingerprint, resulting session id, and response. Exact replays return the original response; key reuse with a different request returns 409. Concurrent identical requests converge on one session.
2. Publish a durable, session-scoped event journal with a monotonically increasing cursor and bounded GET pagination or SSE Last-Event-ID replay. The journal should include the lifecycle and evidence-bearing events needed for crash recovery; cursors must remain valid across server restarts and replicas.
3. Make the existing non-destructive interrupt/stop_session operation a documented public endpoint with typed request/response and idempotent semantics. DELETE remains teardown and must not be the orchestration cancel primitive.
4. Document snapshot plus journal reconciliation, retention/compaction behavior, authorization binding, retry/error codes, and terminal-event guarantees.
5. Add concurrency, response-loss replay, restart, pagination, authorization, and non-destructive-stop tests plus an OpenAPI/client contract test.

A practical delivery sequence would be: idempotent create and public stop first, then the durable event journal/replay. This issue is intentionally separate from machine-principal issuance in omnigent-ai/omnigent#3976.

Alternatives considered

• Polling only GET snapshot/items: durable for current state and transcript items, but it cannot prove every lifecycle/event edge was processed and has no explicit coordinator checkpoint.
• Using DELETE as cancel: destructive; it removes the conversation and evidence needed for reconciliation.
• Calling the hidden event route: works against implementation details but is not a supported or discoverable public contract.
• Relying only on subscribe-then-snapshot: appropriate for the web UI, but insufficient for durable external workflow recovery after an ambiguous create or long disconnect.

Scope

Harness: Not applicable (server API contract across harnesses)
Platform: Not platform-specific
Harness mode: Not applicable
Expected reach: Some users
Authentication: Local, Multi-user, OIDC, OAuth, Databricks