Use Platform agent-runtime as Maestro's durable run ledger

[haasonsaas]

From the Maestro/platform integration review using gh on 2026-04-22.

Reviewed heads:

• ae6e88a
• evalops/platform@7b003938349939052f90ae41241599993a7c06c9

Problem

Maestro has rich local/session telemetry and hosted session state, while Platform has agentruntime.v1 durable runs with steps, checkpoints, waits, costs, leases, and run events. Platform tracks the generic primitive in evalops/platform#671, but Maestro does not yet have a concrete adoption issue for using that ledger.

Scope

• Add an optional Platform agent-runtime client/config path beside the existing Platform client helpers.
• When enabled, create or attach an AgentRun for each Maestro session/run using stable workspace/team/session identifiers.
• Record turn lifecycle as AgentRunStep and checkpoint records, including model/provider, tool calls, token/cost data, and failure state.
• Map approval pauses and human-in-the-loop decisions to WaitRun / ResumeRun without blocking local-only operation.
• Correlate AgentRun IDs onto emitted maestro.* CloudEvents, meter payloads, audit context, and headless protocol output where relevant.
• Preserve TUI/web/headless behavior when Platform agent-runtime is unavailable.

Acceptance Criteria

• A Platform-backed smoke path can start a Maestro session, record at least one turn step plus cost/checkpoint data, pause/resume on an approval wait, and complete or fail the AgentRun.
• Local/offline Maestro sessions continue to work with no Platform env vars.
• Docs/env examples explain the feature flag and identity/correlation fields.
• Tests cover the disabled path, mocked Platform success path, and Platform unavailable/fallback behavior.

Related: evalops/platform#671, evalops/platform#765, evalops/platform#762, evalops/platform#763.

---

Runtime Parity / Conformance Links

• Define Rust core runtime parity contract for hosted Maestro #84 — Rust core runtime parity decision for hosted Maestro.
• Add headless runtime conformance suite for Rust parity #85 — headless runtime conformance suite that should gate Rust-hosted runner parity.

Use #85 as the protocol-level acceptance bar: lifecycle, subscribe/events/messages/heartbeat/disconnect, viewer/controller roles, permission request/response, utility operations, workspace-root enforcement, cursor replay/reset, and drain/resume behavior should match across the current TypeScript web/headless bridge and the target Rust runtime.

[haasonsaas]

Cross-linking from the integration tracker:

• Platform runtime primitive: evalops/platform#671
• Platform-side Maestro worker adapter: evalops/platform#780
• Event contract/publisher/subscribers: evalops/platform#762, Publish Maestro telemetry as typed CloudEvents onto platform's event bus #49, evalops/platform#763
• Approval waits and policy decisions that should record into the runtime ledger: Route Maestro approvals, sandbox, and firewall decisions through Platform policy services #73
• Tool and prompt/skill metadata that should be attached to run steps: Consume Platform-governed MCP skill endpoints as Maestro tool sources #74, Close the Platform prompt and skill learning loop in Maestro #75

Implementation note: this issue is the Maestro-side client/ledger adoption. evalops/platform#780 is the reciprocal Platform-side worker adapter.

[haasonsaas]

Cross-linking from the hosted remote-server review:

• Tracking: harden Maestro remote servers for hosted runtimes #76 is now the Maestro-side tracker for hardening remote/headless servers before/alongside Platform runtime adoption.
• Bind headless remote sessions to explicit workspace sandboxes #77 should land before this issue records hosted runs broadly, so AgentRun linkage has a real workspace/sandbox boundary instead of process.cwd().
• Make headless runtime fleet-safe across Maestro web replicas #78 affects how Platform run leases map to Maestro runtime ownership when more than one web replica is active.
• Use verified principals for hosted remote session scope and authorization #79 affects the workspace_id / actor_id / subject fields this issue should attach to AgentRun records.
• Bring Maestro Helm and runtime image up to hosted remote-server requirements #80 covers the chart/runtime preconditions needed for a deployed ledger-backed remote server.

In short: this issue remains the durable-ledger adoption work; #76 is the remote-server safety envelope around it.