estafeta 3.1.0: agent-relay for cross-provider work

.claude-plugin/marketplace.json

@@ -1,14 +1,14 @@
 {
   "name": "pashbel-estafeta",
-  "description": "Resumable multi-session projects: checkpoints, phased plans with recorded checks, handovers and safe parallel sessions.",
+  "description": "Resumable multi-session projects: checkpoints, phased plans with recorded checks, handovers, safe parallel sessions and cross-provider delegation.",
   "owner": {
     "name": "pashbel"
   },
   "plugins": [
     {
       "name": "estafeta",
       "source": "./packs/session-workflow",
-      "description": "Resumable multi-session projects: checkpoints, phased plans with recorded checks, handovers and safe parallel sessions."
+      "description": "Resumable multi-session projects: checkpoints, phased plans with recorded checks, handovers, safe parallel sessions and cross-provider delegation."
     }
   ]
 }

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.9", "3.13"]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Pack validation
+        run: python scripts/workflow.py check
+      - name: Runtime tests
+        run: python scripts/test_session.py
+      - name: Installer tests
+        run: python scripts/test_workflow.py
+      - name: Golden path integration tests (stub worker)
+        run: python scripts/test_relay.py

HANDOVER.md

@@ -2,26 +2,74 @@
 
 ## Current work
 
-The October 15, 2026 synchronization task preserves the existing favicon studies
-under assets/favicon and adds tracked project context and cross-computer resume
-instructions in docs/CONTINUING.md. Spark remains the recommended concept in
-assets/favicon/README.md; no product feature or new release is included.
+estafeta 3.1.0 adds cross-provider work (plan:
+docs/plans/multi-provider.md).
+
+- **Skill `agent-relay`.** Lets an orchestrator consult, cross-review with or
+  delegate a phase to another provider, and coordinate peer agents. It covers
+  T3 host tasks, Codex/Claude/Gemini CLIs and same-provider subagents.
+- **Runtime command `delegate`.** Keeps a ledger beside the state, so schema 2
+  is unchanged. CLI workers run as supervised processes with a timeout. The
+  runtime checks a writer's claims against recorded checks and the observed
+  workspace.
+- **Integrated.** Existing skills, docs and the 3.1.0 manifests know about
+  the skill. A CI workflow was added.
+- **Testing approach (user request).** Golden path tests check a short
+  sequence of agent interactions, with an expected result at each step:
+  - every change, in CI: a deterministic stub worker
+    (`scripts/test_relay.py`);
+  - before a release or a provider/model change: live runs checked with
+    `--live-verify`.
 
 ## Next action
 
-On another computer, update a clean checkout from origin/main using
-docs/CONTINUING.md, read PROJECT.md, and use session-start. Continue with the
-user's next project task. Do not infer that other computers have updated just
-because the source was pushed.
+Merge the 3.1.0 pull request after its CI run passes. Optional follow-ups:
+
+- a third Codex review round;
+- live `codex exec` and `gemini -p` runs where those CLIs are installed;
+- the benchmark follow-up in docs/BENCHMARK-ROADMAP.md.
 
 ## Validation
 
-On October 15, 2026, `python3 scripts/workflow.py check` passed for Estafeta
-3.0.0 and its five portable skills. All 57 session runtime tests and all 19
-installer tests passed. Favicon SVG/JSON files parsed, PNG/ICO headers and the
-font license link were checked. No new browser visual review was performed.
+On October 15, 2026, on macOS with Python 3.9.6:
+
+- runtime 70/70, installer 21/21, golden 5/5 scenarios (79 steps), pack check
+  and the Claude plugin validators passed;
+- four deliberate regressions were caught by golden steps;
+- live, all passing `--live-verify`:
+  - Codex gpt-6.1-sol through T3: a delegated write and two cross-review
+    rounds (12, then 5 findings, all fixed with tests);
+  - `claude -p` as a CLI worker: consult on Haiku 5.5, write on Sonnet 5.5
+    under the OS sandbox.
+
+Details are in packs/session-workflow/VALIDATION.md.
 
 ## Boundaries
 
-The local session runtime is ignored by Git. No remote-computer checkout or
-provider installation has been verified by this task.
+Not verified:
+
+- live `codex exec` and `gemini -p` CLI transports;
+- the Gemini/Antigravity route;
+- native Linux and Windows.
+
+The round 2 fixes were tested locally but not re-reviewed by Codex. The
+fixtures in /private/tmp/relay-live and /private/tmp/relay-cli are disposable.
+
+<!-- session-workflow:facts:start -->
+## Session facts (generated)
+
+State revision 109; HEAD 8559853e8949b0ef51d5ffb9c2351158fba23ff2.
+
+| Phase | State | Owner | Latest checks |
+| --- | --- | --- | --- |
+| P1 | DONE | - | unit-session: pass (executed, inputs match); golden-relay: pass (executed, inputs match); pack-check: pass (executed, inputs match) |
+| P2 | DONE | - | pack-check: pass (executed, inputs match); unit-workflow: pass (executed, inputs match) |
+| P3 | DONE | - | pack-check: pass (executed, inputs match); unit-workflow: pass (executed, inputs match); unit-session: pass (executed, inputs match); golden-relay: pass (executed, inputs match) |
+| P4 | DONE | - | live-relay: pass (executed, inputs match); unit-session: pass (executed, inputs match); golden-relay: pass (executed, inputs match) |
+| P5 | DONE | - | live-cli: pass (executed, inputs match); live-review-2: pass (executed, inputs match); golden-relay: pass (executed, inputs match); pack-check: pass (executed, inputs match) |
+
+Active sessions: none.
+Ended sessions: 5; latest s-xprov-1015 (next: Watch CI of the agent-relay-3.1.0 pull request and merge it when green. Optional: Codex review round 3, live codex exec / gemini -p runs where installed, benchmark follow-up.).
+
+Generated facts do not establish acceptance, explain intent or prove delivery.
+<!-- session-workflow:facts:end -->

PROJECT.md

@@ -8,16 +8,15 @@ Do not publish credentials, local runtime state, or personal logs.
 
 ## Documentation map
 
-- Plan: none for the current repository synchronization task.
+- Plan: docs/plans/multi-provider.md (multi-provider relay).
 - Handover: HANDOVER.md.
 - Installation: docs/INSTALL.md; usage: docs/USAGE.md.
 - Maintenance and checks: docs/MAINTAINING.md.
 - Workflow: estafeta; machine state in .agent-state/session-workflow is local and ignored by Git.
 
 ## Current focus
 
-- Preserve the favicon studies and make the current source and continuation context available through origin/main.
-- No new product feature is selected. Continue only with the next requested task.
+- Multi-provider relay (3.1.0): skill `agent-relay` and runtime `delegate`; see docs/plans/multi-provider.md.
 - On another computer, follow docs/CONTINUING.md, then use session-start.
 
 ## Run and verify
@@ -28,4 +27,5 @@ Python 3.9+ and Git are required.
 python3 scripts/workflow.py check
 python3 scripts/test_session.py
 python3 scripts/test_workflow.py
+python3 scripts/test_relay.py
 ```

README.md

@@ -63,6 +63,7 @@ Then ask any agent: "Use session-guide. Explain how this works."
 | --- | --- |
 | Use session-start | Opening a chat |
 | Use plan-and-orchestrate | Work longer than one step |
+| Use agent-relay | Ask, review with or delegate to another AI provider |
 | Use session-handover | At a milestone |
 | Use session-end | When you stop |
 

docs/BENCHMARK-ROADMAP.md

@@ -84,3 +84,18 @@ alone cannot establish it. The runtime earns its cost only if workflow beats lit
 on recovery, ownership safety or integration at equal passed requirements, or
 matches lite at lower cost. If lite matches workflow, the conventions rather than
 the runtime carry the value.
+
+## Cross-provider relay (follow-up)
+
+The golden path tests in `scripts/test_relay.py` catch regressions in the
+relay mechanics; they do not show that cross-provider work pays off. A later
+benchmark should compare, on the frozen scenarios above:
+
+- single-provider work with self-review;
+- the same work with an agent-relay cross-review by another provider;
+- a delegated write phase by another provider.
+
+Measure defects found by independent acceptance tests, review findings that
+were confirmed or rejected, extra tokens and wall time, and how often a
+writer's claims disagreed with recorded facts. Record provider and model for
+each arm, since a result for one pair does not carry over to another.

docs/INSTALL.md

@@ -42,8 +42,9 @@ language.
    same command once. Never edit host permissions or settings to get past the
    block. If it is blocked again, report the command for the user to run.
 6. **Verify.**
-   - `status` prints five MATCH lines per destination: session-start,
-     plan-and-orchestrate, session-handover, session-end and session-guide.
+   - `status` prints six MATCH lines per destination: session-start,
+     plan-and-orchestrate, session-handover, session-end, session-guide and
+     agent-relay.
    - There is no RETIRED-PRESENT line.
    - No other copy shadows these skills.
 7. **Finish.** Reload skills if that is possible without ending the chat. Do
@@ -57,7 +58,7 @@ language.
 
 ## Portable skills: any supported provider
 
-This route installs five standalone skills with the same runtime and instructions.
+This route installs six standalone skills with the same runtime and instructions.
 It also works from an extracted full source ZIP.
 
 ```sh
@@ -88,7 +89,7 @@ python3 scripts/workflow.py install --dest /path/to/custom/profile/skills
 | `agents` | `~/.agents/skills` |
 
 The installer respects configured provider homes and detects existing Claude
-and Hermes profiles. It changes only these five skills. A changed directory is
+and Hermes profiles. It changes only these six skills. A changed directory is
 backed up intact outside the discovery root before its replacement. Updates are
 atomic per skill; rerunning the installer converges after a partial failure.
 `status` compares complete directory hashes. Reload skills or start a new host
@@ -130,7 +131,7 @@ codex plugin list --marketplace pashbel-estafeta --json
 If Git access is configured differently for the host, add the authenticated local
 clone with `codex plugin marketplace add .` instead. Open the desktop plugin
 browser to install from that marketplace when the installed client uses the UI
-for installation. Start a new session and verify the five skills are available.
+for installation. Start a new session and verify the six skills are available.
 See [OpenAI packaging documentation](https://developers.openai.com/plugins/build/plugins).
 
 ## Claude Code plugin

docs/MAINTAINING.md

@@ -13,8 +13,31 @@ python3 scripts/workflow.py sync-contract
 python3 scripts/workflow.py check
 python3 scripts/test_session.py
 python3 scripts/test_workflow.py
+python3 scripts/test_relay.py
 ```
 
+CI (`.github/workflows/ci.yml`) runs the same checks on Linux and macOS for
+every push and pull request.
+
+## Golden paths
+
+`scripts/test_relay.py` plays the scenarios in
+`scripts/golden/relay-scenarios.json`. Each scenario is a sequence of
+orchestrator and worker interactions with an expected result at every step,
+and the first failed step fails the scenario. Keep the set small and
+representative. Add a scenario only for a new interaction pattern, and add a
+failing step when you fix a delegation bug.
+
+- **Every change and CI:** a deterministic stub worker
+  (`scripts/golden/stub_worker.py`) stands in for the LLM. It also plays a
+  hung worker, a garbled reply and a writer that claims checks it never ran.
+- **Before a release, or when a provider, model or adapter changes:** run a
+  scenario live with agent-relay against a disposable fixture. Then run
+  `python3 scripts/test_relay.py --live-verify SCENARIO --root FIXTURE --map
+  orch=<session> --map write-1=<delegation>`, which checks the recorded state
+  read-only. Record the provider, model, date and result in VALIDATION.md.
+  Live runs cost money and need the provider's login, so CI does not run them.
+
 Change `VERSION`, every skill's metadata version, the common contract and the
 three plugin manifests together. Validation rejects version drift. Provider
 marketplaces point to the same `packs/session-workflow` directory. Native plugin
@@ -42,7 +65,7 @@ python3 scripts/workflow.py bundle --plugin-only --output /path/to/estafeta-plug
 ```
 
 The full archive contains sources, docs, catalogs and the installer. The plugin
-archive contains the manifests, README, cover and five self-contained skills. Both get SHA-256
+archive contains the manifests, README, cover and six self-contained skills. Both get SHA-256
 sidecars. Credentials, project runtime state and Git history are excluded.
 The repository is public. Before publishing new benchmark evidence or logs,
 replace local paths (for example with `$HOME` or `$OUTPUTS`) and remove personal

docs/USAGE.md

@@ -28,6 +28,7 @@ A small isolated edit does not need it.
 | Plan only | Use plan-and-orchestrate. Plan this change without implementing it yet. |
 | Execute | Use plan-and-orchestrate. Complete the agreed phases and verify acceptance. |
 | Economize | Use plan-and-orchestrate with minimal reads and output. |
+| Another provider | Use agent-relay. Have Codex review this diff. |
 | Handover | Use session-handover. Update the handover from actual changes and checks. |
 | End | Use session-end. Save the next action for another device. |
 
@@ -86,6 +87,33 @@ transfer it together with its evidence.
 
 Claims depend on cooperation: they do not stop direct edits that bypass the runtime.
 
+## Several AI providers
+
+`agent-relay` lets one chat, the orchestrator, work with agents of other
+providers. Ask for them by name; each run of another provider costs money, and
+the agent needs your request before it starts one.
+
+| Mode | Example | What comes back |
+| --- | --- | --- |
+| Consult | Use agent-relay. Ask Gemini which caching option fits here. | An answer, marked as coming from that model |
+| Review | Use agent-relay. Have Codex review the diff of P2. | APPROVE or CHANGES_REQUIRED with findings |
+| Write | Use agent-relay. Delegate P3 to Claude in its own worktree. | A tested change on a `relay/P3` branch |
+| Peers | Open Codex and Claude on the same project, both "in parallel". | Each claims its own phases |
+
+- **Transports.** The agent prefers the host's own child tasks (for example
+  T3 Code) and otherwise runs the provider's CLI as a supervised process with a
+  timeout. It never uses flags that switch off the worker's sandbox.
+- **Records.** Each delegation is kept under
+  `.agent-state/session-workflow/delegations/`: provider, model, packet and
+  result. `session-start` shows open ones; a later chat collects or cancels
+  them.
+- **Trust.** A worker's report is a claim. For a write, the orchestrator
+  compares it with the runtime's records, reads the diff, commits and merges it
+  itself, and reruns the required checks before DONE.
+- **Models differ.** A provider and model pair that worked once is not
+  validated forever. Start a new pair with a consult or review before giving
+  it a write.
+
 ## Deterministic runtime
 
 Skills call their bundled `scripts/session.py`; its source never needs to enter