Relay orchestration

Coordinate multi-agent work through durable, signed artifacts instead of chat — briefs, handoffs, handbacks, and a notification plane that survives the context window.

Multi-agent work dies in chat. Chat is per-session, per-tool, invisible to the other agents, unsigned, and gone the moment a context window rolls. An orchestrator that says "I'll watch for results" but has no mechanism to observe them is hoping, not coordinating.

SEIF replaces hope with mechanism. Coordination state lives in durable, git-tracked artifacts; a lightweight notification plane wakes the agents that care; and chat carries only short pointers. The human stays sovereign and informed at every step.

The artifact plane

Coordination state lives on the host-tier board ~/.seif/relay/<workspace_id>/ (shared by every checkout of the workspace). Do not write peer notes under <ws>/.seif/relay/ — that twin is not the canonical board. There is no seif relay outbox and no .seif/ipc.sock for peer chat.

Artifact	Path	Role
brief	`brief/<slug>.md`	scope, definition-of-done, sources, constraints, reporting protocol. Steered mid-flight by appended `AMENDMENT` sections.
handoff manifest	`handoff/<slug>/HANDOFF.md`	per-wave tracking: worktree, branch, repos. Emitted by the orchestrator alongside the brief.
handback	`handback/<slug>.md`	the executor's report: what shipped, real evidence, deviations with technical analysis, commit SHAs. Closed by an appended loop-closure section.
peer note	`inbox/PEER-NOTE-*.md`	peer↔peer durable messages (`seif relay inbox send` / `notify`). Front-matter: `from`/`to`/`ref`.

The rule that holds it together: files are state, the bus is a notifier, chat is an echo. Anything that must be seen goes to a file.

seif start --client antigravity --executor-id agy-orch-1   # unique SEIF_EXECUTOR_ID
seif relay peers                     # live roster — address these ids only
seif relay brief my-feature
seif relay handoff init my-feature --worktree … --executor-id …
seif relay pointer my-feature
seif relay handback my-feature
seif relay notify <peer-id> --note note.md --ref my-feature
seif relay inbox mine                # read notes addressed to you

The notification plane

The relay-watch daemon capability puts a filesystem watcher on the relay kinds and emits metadata-only events ({kind, action, slug, path, ts}) on the bus topic relay. Artifact content never leaves the file plane.

seif daemon enable relay-watch
seif daemon subscribe relay        # optional — wake hint for terminals that subscribe

Honest caveat: seif daemon status often shows Bus: 0 subscriber(s). That does not mean notify failed — the PEER-NOTE is already on disk. Peers discover it via seif relay inbox mine, relay poll, or session_orient (unread_peer_notes). Idle IDE tabs still need a human turn or an armed in-session watcher; the bus does not inject a Cursor/agy turn by itself.

This is what lets an orchestrator stand by instrumented — woken by a real signal — instead of polling blindly when a subscriber is present.

The roles

Owner (human, sovereign). Sets tempo, ratifies decisions, merges or explicitly delegates merge, eyeballs user-facing UI. Never bypassed: every relay act echoes a short pointer into the relevant chat, so the human is never lost or left guessing mid-process.
Orchestrator (single writer). Owns push / PR / merge / pull across all repos and the workspace .seif/ mutations. Independently re-verifies every executor claim — re-runs tests, replicates live proofs, diffs docs against the CLI ground truth — before pushing. Appends a loop-closure to each handback.
Executors (one per dedicated workspace). One wave = one brief = one dedicated worktree. Commit locally only. Hand back honestly: mark anything unverified, surface deviations with analysis rather than hiding them.

The wave lifecycle

brief (file) → handoff manifest → pointer (chat echo) →
  executor: worktree → implement → commit local → handback (file) →
    orchestrator: wake (bus/watcher) → independent verify →
      fixups on the executor branch (surfaced, co-authored) →
        push → PR → merge (owner or delegated) → pull mains →
          live production proof → loop closure appended → prune worktree

Mid-flight steering is an appended AMENDMENT to the brief plus a chat pointer. Version races — an executor read v1 while the orchestrator amended to v2 — are expected; they surface at verification and resolve through correction rounds, never blame.

Standby is instrumented, never hopeful

An orchestrator waiting on results states which mechanism is armed (bus subscriber, or a targeted watcher on the expected handback path) and debounces briefly so it wakes to a filled artifact, not a skeleton. "I'll keep an eye on it" with no watcher armed is the anti-pattern this protocol exists to kill.

Accountability board

For longer-running fleets, the relay board tracks active assignments, claims, and TTLs so nothing silently stalls:

seif relay board                   # the accountability board
seif relay assignments             # active handoff assignments
seif relay claim <slug> --executor-id <id>
seif relay heartbeat <slug>        # renew the claim TTL
seif relay release <slug>          # return it to the queue
seif relay close <slug>            # terminally close (or sweep stale claims)

Boundaries

Metadata only on the wire. Bus events carry kind, slug, and timestamp; artifact content stays in the file plane, gated by its classification.
Files are the source of truth. The bus notifies and chat echoes; neither holds state.
Destructive reproductions run only in isolated test workspaces, never the live workspace.
Honest handbacks. Unverified claims are labeled; deviations are surfaced with technical analysis. A self-reported deviation is the gold standard, not a failure.

Honest caveat

Chat in a sibling agent's session is invisible to the orchestrator by design — anything that must be seen goes to a file. Humans will sometimes forget to relay a pointer; the protocol survives it, but latency rises. Engine-side enforcement of relay-act roles is on the roadmap; today the role matrix is convention.