Managed CLI Relay

Use this playbook when you want to adopt the current local relay control-plane surface quickly.

The relay surface records managed CLI sessions, read/write borrows, control requests, event cursors, and recovery classification in one local relay ledger. It may also serve those facts over a foreground HTTP plus server-sent events process with wap-flow relay serve. It does not start real provider subprocesses or pool live provider processes yet.

flow/state/relay/relay-state.json is the durable relay control-plane ledger. Writes to that ledger are serialized with the relay tmp lock under flow/tmp/relay/**. flow/tmp/relay/** otherwise remains rebuildable relay runtime scratch for future stream buffers, cursor files, and transport metadata.

Quick Start

Check whether relay artifacts exist:

wap-flow relay status
wap-flow relay status --json

Record local relay runtime metadata:

wap-flow relay bootstrap \
  --bind-mode loopback \
  --endpoint http://127.0.0.1:9876 \
  --json

Serve the same relay projection over loopback:

wap-flow relay serve \
  --bind-mode loopback \
  --host 127.0.0.1 \
  --port 9876

Create a fake managed session record:

wap-flow relay session create \
  --session-id session-a \
  --provider codex \
  --capability-tier resumable \
  --json

Borrow and return the session:

wap-flow relay borrow \
  --session-id session-a \
  --lease-id lease-r1 \
  --borrower-id user-a \
  --kind shared-read \
  --json

wap-flow relay release \
  --session-id session-a \
  --lease-id lease-r1 \
  --json

Record control and event facts for the relay session:

wap-flow relay control record \
  --request-id request-1 \
  --session-id session-a \
  --operation interrupt \
  --payload-fingerprint sha256:abc123 \
  --json

wap-flow relay event append \
  --session-id session-a \
  --kind control_progress \
  --summary "interrupt delivered" \
  --json

Classify recovery without mutating the ledger:

wap-flow relay recover --session-id session-a --json

Inspect the same relay projection through the read-only cockpit:

wap-flow inspect relay
wap-flow inspect relay --json

Confirm relay roots are covered by generated-state inventory:

wap-flow state inventory --json

The normal empty-state result is healthy when no relay artifacts have been created yet. Empty flow/state/relay/ and flow/tmp/relay/ roots are not a repair trigger. Inventory validates flow/state/relay/relay-state.json specifically as the relay ledger. Other descendants under flow/state/relay/** and flow/tmp/relay/** are arbitrary relay artifacts; they are reported as relay-owned artifacts but are not parsed with the ledger schema.

Read the Output

relay status --json and inspect relay --json expose the same relay projection. inspect relay --json wraps it under a top-level relay key.

status: pass when relay inspection found no warnings, or warn when relay-owned artifacts could not be read cleanly.
projection: the stable projection label, currently relay_generated_state_v1.
relay_mode: the recorded relay runtime mode when runtime metadata exists, otherwise null.
state_dir and tmp_dir: the relay-owned generated roots, flow/state/relay and flow/tmp/relay.
ledger_path: the durable relay ledger path, flow/state/relay/relay-state.json.
state_present and tmp_present: whether those roots exist in the current repo.
ledger_present: whether the durable relay ledger exists.
durable_artifacts: files found under flow/state/relay/**.
tmp_artifacts: files found under flow/tmp/relay/**.
durable_artifact_count, tmp_artifact_count, and warning_count: additive counts derived from the artifact and warning lists for compact status and cockpit summaries.
session_count, active_lease_count, control_request_count, and event_count: compact counts derived from the durable relay ledger when it is present and valid.
ledger_summary: optional detailed count projection for ready/borrowed sessions and read/write leases.
freshness: latest modified timestamps for durable and tmp artifacts when present.
warnings: read or metadata problems that should be inspected before trusting the projection.

Duplicate relay control record retries with the same request id are retry-safe only when the stable request fields match. A matching duplicate returns a duplicate admission and does not rewrite the ledger.

Borrow admission rules are conservative:

shared-read borrows may coexist with other active readers.
exclusive-write borrows are denied while any reader or writer is active.
New readers are denied once a writer is waiting, so a writer can retry after existing readers release.
Recovery reports blocked_by_mutable_lease while an exclusive writer is active, resume_session for resumable idle sessions, and start_replacement_session for non-resumable idle sessions.

Adoption Rules

Treat flow/state/relay/** as durable CLI-owned relay state.
Treat flow/tmp/relay/** as rebuildable relay scratch, stream, or cache material.
Do not manually edit relay durable state. Use relay commands for session, borrow, control, event, and recovery transitions.
Companion apps may consume --json output or the relay serve HTTP+SSE boundary as non-authoritative projections.
Companion apps must not write flow/state/** or treat relay tmp artifacts as authority.
Loopback relay serving is the default. Trusted-LAN serving must be explicit, must bind only to a private-network IP address, and must require a bearer token.

Troubleshooting

If relay status --json reports status: warn, inspect the listed warnings and artifact paths first.

For repository-level setup health, run:

wap-flow doctor --json

Use strict doctor only when you are validating the full repo guardrail state:

wap-flow doctor --json --strict

Strict doctor may fail on unrelated repository setup warnings, such as hooks not being installed or older generated-state schemas. Relay inspection stays focused on relay-owned roots.

Not Yet Implemented

This playbook does not describe a live managed session pool yet. The following FC-2026-029 capabilities remain future work:

real provider subprocess ownership
token rotation or revocation
automatic quarantine and recovery repair flows