Sentinel↔Forge delegated verification via A2A relay

[Christiantyemele]

Summary

Give Sentinel the ability to verify acceptance criteria that require executing code, without granting it access to Forge's workspace. Sentinel sends a typed verify task over A2A; Forge (as executor) runs it in its own workspace and returns structured results. A central A2A relay hosted by nexus mediates all traffic.

This also fixes the "Sentinel wakes up blind" incident by making Sentinel hard-fail (never approve) when required artifacts are missing.

Full design and task breakdown: .kilo/plans/1785948146715-sentinel-forge-a2a-verify.md

Locked design decisions

1. Delegated verification — Sentinel never SSHes into Forge, never mounts its filesystem. Executor = Forge (v1). Dedicated verifier worker role is a v2 extension point.
2. Transport — A2A (JSON-RPC + SSE) over a central relay hosted by nexus. Workspaces are outbound-only clients. No peer-to-peer, no Coder tunnels, no A2A-over-Redis.
3. Source-of-truth split — Redis SharedStore remains authoritative for durable artifacts (pair:{id}:plan, pair:{id}:contract, pair:{id}:handoff, new pair:{id}:verification). A2A relay carries only live task exchange; every terminal result is mirrored to Redis before ack.
4. Agent-facing surface stays openflows-harness — new verify request / verify serve / verify list subcommands wrap A2A. Harness remains the sole A2A/Redis client in worker workspaces.
5. AuthN reuses the existing workspace token; AuthZ enforced in nexus against the pair's role map (pair-scoped routing).
6. Sentinel gate policy — hard-fail (never approve) when pair:{id}:plan is missing or unreadable; return blocked: missing_artifacts.

Non-goals

• Ephemeral per-review verifier workspaces (deferred).
• Arbitrary shell for Sentinel — only the typed verify task shape is exposed.
• Replacing Redis SharedStore or the harness typed-write contract.

Task checklist

0. Create tracking issue

• Open this issue

1. Schema + shared types

• Add crate crates/a2a-protocol with serde types + JSON schemas for verify request / result / progress events
• Add Redis key constants: pair:{id}:verification, audit:a2a:{task_id}, audit:a2a:rejected

2. Nexus A2A relay

• A2A server module in crates/agent-nexus (message/send, message/stream, tasks/get, tasks/cancel, tasks/resubscribe)
• Pair-scoped routing table (pair_id, role) → session
• Command allowlist + cwd validation middleware; log rejections to audit:a2a:rejected
• Idempotency dedup (pair_id, sha256(body)) with TTL
• Result mirror to pair:{id}:verification + audit:a2a:{task_id}:* before ack
• Publish nexus Agent Card at /.well-known/agent-card.json

3. Harness client + executor subcommands

• A2A client in crates/openflows-harness (reuses workspace token)
• openflows-harness verify request (Sentinel-side)
• openflows-harness verify serve (Forge-side, sandboxed execution + timeout)
• openflows-harness verify list [--pair PAIR_ID]
• CI grep guard: no other crate opens A2A sockets

4. Sentinel gate refusal policy

• crates/agent-sentinel: block gate approve when pair:{id}:plan missing/unparseable → emit blocked: missing_artifacts
• Update orchestration/plugin/skills/sentinel-review/SKILL.md with refusal rule + verify request usage
• Update orchestration/agent/agents/sentinel.agent.md

5. Forge executor role

• crates/agent-forge bootstrap spawns verify serve alongside heartbeat
• Update orchestration/agent/agents/forge.agent.md

6. Worker template wiring

• Sentinel template: verify request on PATH
• Forge template: verify serve in session start / systemd-user unit

7. Documentation (required)

• New docs/architecture/a2a-verification.md (topology, schema, allowlist, failure modes)
• Update docs/architecture/agent-orchestration-protocol.md (new "Live verification tasks (A2A)" section + key table)
• Update docs/architecture/OpenFlows_Coder_Integrated_Architecture.md (~line 719)
• Update docs/ORCHESTRATOR.md (nexus relay responsibility, harness command inventory)
• Update docs/AGENT_BOOTSTRAP.md (verify serve, verify request)
• Update docs/governance.md (A2A allowlist + audit trail row)
• Update README.md (one-line mention of delegated verification)
• Update orchestration/plugin/skills/sentinel-review/SKILL.md and orchestration/plugin/commands/plan.md for gate refusal rule

8. Tests

• Unit: A2A serde round-trip
• Unit: nexus allowlist + cwd escape rejection; idempotency dedup
• Integration: end-to-end verify request → serve → Redis mirror
• Integration: timeout_secs kills runaway command
• Integration: Sentinel disconnect + tasks/resubscribe recovers artifact
• Integration: Sentinel refuses gate approve when plan missing
• E2E: extend docs/phase8-e2e-validation.md with a cargo test verify before approval

Rollout

1. Ship behind feature flag a2a_verification (default off)
2. Enable on a staging pair; run E2E
3. Enable by default; keep flag one release
4. Remove flag

Definition of Done

• Sentinel cannot approve a gate when pair:{id}:plan is missing (integration test)
• Sentinel can trigger cargo test in Forge's workspace and receive structured result (integration test)
• Every accepted A2A request in audit:a2a:{task_id}; every rejected one in audit:a2a:rejected
• Forge does not accept A2A connections directly; only nexus does
• openflows-harness remains sole A2A client (CI grep guard passes)
• All docs in task 7 merged

References

• Plan file: .kilo/plans/1785948146715-sentinel-forge-a2a-verify.md
• Related: docs/architecture/OpenFlows_Coder_Integrated_Architecture.md (line 719 — "no shared filesystem across workspaces")
• Related: orchestration/agent/agents/sentinel.agent.md (current gate approval flow)