opencode-agora 0.1.0__tar.gz

opencode_agora-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guangbin79
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opencode_agora-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# F31 sdist 清单：与 pyproject 数据面同源（源码分发可离线重装）
+include install.sh
+include agora
+recursive-include agora-plugin *.ts
+exclude agora-plugin/*.test.ts
+prune agora-plugin/tests
+recursive-include skills *

opencode_agora-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: opencode-agora
+Version: 0.1.0
+Summary: opencode 会话间任务派发与凭据治理：agorad 服务＋opencode 插件＋agora CLI
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# opencode-agora
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab.svg)](https://www.python.org)
+[![made for opencode v2](https://img.shields.io/badge/made%20for-opencode%20v2-6e7bff.svg)](https://opencode.ai)
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Multi-agent delegation for [opencode](https://opencode.ai) v2. Installing it upgrades your main session into an **orchestration agent** — **the LLM plans, the machine verifies**. Each task runs in its own git worktree; only verified work gets merged.
+
+```text
+You:    "Fix the login bug in repoB. Run pytest -q, merge when green."
+agora:   └─ spawns a worker in an isolated git worktree
+             worker fixes → service runs pytest itself → review green → ff-only merge
+You:    "How's it going?"   →   board: ✅ merged
+```
+
+The difference in one line: **the LLM holds the steering wheel; the machine holds the brakes.** Orchestration — what to run, in what order, when to replan — stays in your conversation, so mid-flight intent (*"now apply the same fix to repoB and repoC"*) becomes a new schedule on the spot. And agents don't grade their own homework here: the verify command runs under the service, not the worker — green means the tests actually passed on the exact commit being merged.
+
+## Quick Start
+
+Prerequisites: [opencode](https://opencode.ai) v2 (`curl -fsSL https://opencode.ai/v2/install | bash`), [bun](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`), `git`, `python3` ≥ 3.10 (stdlib only — zero pip dependencies).
+
+```bash
+git clone https://github.com/guangbin79/opencode-agora.git
+cd opencode-agora && ./install.sh
+```
+
+From PyPI instead — equivalent install, no clone needed (the git route above stays as the source-code form):
+
+```bash
+pipx install opencode-agora
+agora-install
+```
+
+That's it. The installer is idempotent (safe to re-run); it registers the MCP server, copies the plugin + skills, and leaves a root credential at `$AGORA_HOME/.agora/root.token` (0600).
+
+Now just talk to your opencode session as usual:
+
+| You say | What happens |
+|---|---|
+| *"Have an agent fix X in repoY, verify with `pytest -q`"* | Task created, worker dispatched into its own worktree |
+| *"How's it going?"* | Live board: five buckets, dependency chains, escalation feed |
+| *"Stop that task"* | Cascade-cancel with confirmation |
+| *"Bump the dependency in repoA, then apply the same fix in repoB and repoC"* | `after:` dependency chain — B and C wait for A, unrelated repos run in parallel |
+
+Standalone dashboard: `agora-board` (vi-motion TUI). Update path: `git pull && ./install.sh`.
+
+## Where It Sits
+
+| | LLM-led orchestration | Machine-run quality gate |
+|---|:---:|:---:|
+| Task-graph orchestrators (plan once, execute a static graph) | ✗ | ✓ |
+| Agent-swarm frameworks | ✓ | ✗ (agents self-report) |
+| **opencode-agora** | ✓ | ✓ |
+
+Orchestration needs the model's flexibility — real intent surfaces mid-conversation, not in an upfront plan. Merge quality must not trust the agent — it has to run where the agent can't fake it. Most projects take one side; agora is built on the bet that you need both.
+
+Making your session an orchestrator isn't unique — subagent trees do that too. The unique part, on an open-source and model-neutral stack, is the **control plane that keeps the orchestrator honest**: verify gate, role-separated credentials, and append-only audit running as an independent service the agent cannot rewrite. Native tools may absorb this tomorrow; today the gap is real.
+
+Two capabilities this control plane buys in practice:
+
+- **Single repo: enforced worktree writes.** Every agent edit is forced into the task's own worktree by the plugin gate + session tokens — your main checkout is never touched. Convention becomes mechanism.
+- **Multiple repos: one root agent, sibling repos.** A single session at the parent directory orchestrates cross-repo chains with `after:` — the downstream task sees the upstream repo's merged result through the `../` sibling layout, while unrelated repos run in parallel.
+
+**Honest trade-offs** (the same reasons you might not want this):
+
+- A wrong `verify_cmd` at creation can stall a task — it fails safe: workers can't edit verify, so the worst case is a stuck task, never a bad merge
+- Your main session's context is the orchestration bottleneck — that's why `agora-board` exists: five-bucket state at a glance without spending conversation window
+- Every scheduling decision is a model call — if your work pre-decomposes into a clean static graph, a zero-token orchestrator is cheaper and more reproducible
+
+## How It Works
+
+```text
+Human ──▶ Main session (skills: agora-dispatch / agora-ops)
+              │  MCP (13 tools)
+              ▼
+         agorad — Python stdlib service on localhost
+         state authority · verify gate · auto-merge · message routing
+         crash recovery · audit ledger
+              │
+         Per-task git worktrees (enforced isolation)
+```
+
+Task lifecycle: `create → dispatch → worker codes → verify (service-run) → auto-merge (ff-only) → closed`
+
+After install, your session gains two skills (agora-dispatch / agora-ops) and 13 MCP tools. There is no background planner: the model you talk to **is** the orchestrator — task creation, `after:` chains, cancels, escalation replies are all model decisions from conversation context. agorad stays the state authority: verify executor, merge gate, message router, audit ledger.
+
+## Two Quality Gates
+
+**Verify gate** — the non-negotiable one. The verify command is registered at task creation (`task_create(verify_cmd="pytest -q")`, or `verify_pending: true` to defer). The **service runs it in the task worktree**, then trial-merges into a detached integration worktree and runs it again. Only two green runs advance the target branch; integration failures and test side effects never touch your main checkout. One hard requirement: your main checkout must be clean (no uncommitted or untracked changes) before the final push, otherwise the task reopens with a cleanup hint. Each run has a timeout (300 seconds by default). Red = the worker gets the output and retries. Three consecutive failures = blocked + escalation ping. The worker cannot skip it, fake it, or report results itself.
+
+**Review gate** — an open standard, bring your own reviewer. The contract is one anchor file:
+
+- If `.review-loop/` exists in the task worktree, the last-reviewed anchor is checked at `done` and **re-checked immediately before merge** (closes the "reviewed, then sneaked a commit" window).
+- Anchor green + verify green = automatic ff-only merge.
+- No `.review-loop/` directory? Everything still works — tasks complete at `done` and **you merge manually**. Autonomy is earned by both gates, not assumed.
+
+Any reviewer fits — OpenCodeReview, CodeRabbit, a human checklist — agora only reads the anchor. A minimal reviewer is ~10 lines:
+
+```bash
+#!/usr/bin/env bash
+# review-loop.sh <worktree> <target_branch> — run after each commit; exit non-zero if not green
+set -euo pipefail
+cd "$1"
+base=$(git merge-base HEAD "${2:?}"); sha=$(git rev-parse HEAD)
+findings=$(your_reviewer "$(git diff "$base"..HEAD)")   # OCR / CodeRabbit / human list
+printf '%s\n' "$findings" | grep -qiE 'blocker|high' && { printf '%s\n' "$findings"; exit 1; }
+mkdir -p .review-loop && printf '%s\n' "$sha" > .review-loop/.last-reviewed
+```
+
+Full spec — contract details, worker protocol, threat model, idle auto-trigger design notes: [docs/review-loop.md](docs/review-loop.md) (Chinese).
+
+## Highlights
+
+- **Verified autonomy** — auto-merge only after service-run tests pass and the review anchor is green, with the anchor re-verified at merge time
+- **Enforced isolation** — plugin-level gate blocks git-repo writes without task credentials; workers can't touch your main checkout. Accepted risk: nested dispatch lets a worker create subtasks on any local repo path with a self-chosen verify — worker-created task targets are not path-clamped
+- **Cross-repo and nested orchestration** — `after:` dependency chains; workers can create and manage their own subtasks, and a parent can finish only after child results return; hard limits on nesting (5) and concurrency (8)
+- **Role-separated credentials** — root / dispatcher / worker session tokens; workers can cancel or register verify only for their own subtasks, never manage parents or other tasks, or read the board
+- **Crash recovery** — `kill -9` the service at any moment; append-only state + worker re-injection with the same credentials on restart
+- **Real-time accountability** — escalation pings to the main session, append-only JSONL audit for every state change, health patrol for dead dispatchers
+- **PR-workflow friendly** — `task_create(target_branch="feature/x")` merges into a feature branch instead of main
+- **Lightweight** — Python stdlib service, zero pip dependencies, localhost only, no telemetry
+
+## Comparison
+
+| | Manual multi-session | Swarm frameworks | opencode-agora |
+|---|---|---|---|
+| Per-task isolation | you manage worktrees | varies | enforced (plugin gate + worktree per task) |
+| "Tests pass" means | agent says so | agent says so | service ran the command itself |
+| Cross-repo dependencies | manual sequencing | yes | `after:` chains, parallel when unrelated |
+| Merge | manual | varies | automatic, only when both gates are green |
+| Audit trail | none | partial | append-only JSONL, every state change |
+| Install footprint | — | heavy runtimes | python3 stdlib + git + bun |
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `AGORA_HOME` | `~/plaza` | Ledger home (state, messages, audit, wiki) |
+| `$AGORA_HOME/.agora/inactive-repos` | empty | Repos where agora is fully dormant (one path per line) |
+| `AGORA_BOARD_INTERVAL` | `5` | Dashboard poll interval (seconds) |
+| `AGORA_HEALTH_INTERVAL` | `300` | Dispatcher health patrol (seconds) |
+| `AGORA_VERIFY_TIMEOUT` | `300` | Timeout per task/integration verify run (seconds); expiry kills the process group |
+| `enforce` | on | Global gate switch (root only, audited) |
+| `$AGORA_HOME/.agora/email.json` | off | Stuck-task email alerts (`{"to","command"}`) |
+
+## Safety Model
+
+Honest by design — what's machine-checked vs what's trusted:
+
+**Enforced** (cannot be bypassed):
+- Git-repo writes only within task worktrees (plugin gate + session tokens)
+- Verify must actually run and pass, executed by the service
+- Role matrix: workers can't cancel, modify verify, or toggle enforce
+- Every state change lands in the append-only audit ledger
+
+**Accepted risks** (single-machine trust model):
+- A worker using raw `bash` can bypass the write gate (audit is the backstop)
+- Token theft within the same user account
+- The review anchor is a process protocol, not an anti-cheat: the worker writes it, the service reads it. The verify gate is the real quality bar; review adds discipline, not security
+
+## FAQ
+
+**How do I update?** `git pull && ./install.sh` — the plugin and service payloads are copies, so re-running the installer is required after pulling.
+
+**How do I uninstall?**
+```bash
+rm -rf ~/.config/opencode/plugins/agora ~/.config/opencode/skills/agora-dispatch \
+       ~/.config/opencode/skills/agora-ops ~/.local/bin/agora ~/.local/bin/agora-board \
+       ~/plaza ~/.agora-home
+# then remove the "agora" entry from the mcp section of ~/.config/opencode/opencode.json
+```
+
+(`~/plaza` is the default `AGORA_HOME` — if you configured a custom one, remove that directory instead.)
+
+**Does it work without a review-loop?** Yes — verify still runs and gates everything; tasks finish at `done` and you merge manually. Implement the [open standard](docs/review-loop.md) to unlock auto-merge.
+
+**Where does my code go?** Nowhere. agorad binds to localhost, workers are local opencode sessions, there is no telemetry, no cloud, no agora API keys. Whatever models your opencode uses, agora orchestrates them.
+
+**Platforms?** Linux (verified). macOS: the code paths are in place (the installer falls back to `nohup` where `setsid` is absent) but not yet verified on a real Mac. Windows: run inside WSL.
+
+## License
+
+MIT

opencode_agora-0.1.0/README.md

@@ -0,0 +1,185 @@
+# opencode-agora
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab.svg)](https://www.python.org)
+[![made for opencode v2](https://img.shields.io/badge/made%20for-opencode%20v2-6e7bff.svg)](https://opencode.ai)
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Multi-agent delegation for [opencode](https://opencode.ai) v2. Installing it upgrades your main session into an **orchestration agent** — **the LLM plans, the machine verifies**. Each task runs in its own git worktree; only verified work gets merged.
+
+```text
+You:    "Fix the login bug in repoB. Run pytest -q, merge when green."
+agora:   └─ spawns a worker in an isolated git worktree
+             worker fixes → service runs pytest itself → review green → ff-only merge
+You:    "How's it going?"   →   board: ✅ merged
+```
+
+The difference in one line: **the LLM holds the steering wheel; the machine holds the brakes.** Orchestration — what to run, in what order, when to replan — stays in your conversation, so mid-flight intent (*"now apply the same fix to repoB and repoC"*) becomes a new schedule on the spot. And agents don't grade their own homework here: the verify command runs under the service, not the worker — green means the tests actually passed on the exact commit being merged.
+
+## Quick Start
+
+Prerequisites: [opencode](https://opencode.ai) v2 (`curl -fsSL https://opencode.ai/v2/install | bash`), [bun](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`), `git`, `python3` ≥ 3.10 (stdlib only — zero pip dependencies).
+
+```bash
+git clone https://github.com/guangbin79/opencode-agora.git
+cd opencode-agora && ./install.sh
+```
+
+From PyPI instead — equivalent install, no clone needed (the git route above stays as the source-code form):
+
+```bash
+pipx install opencode-agora
+agora-install
+```
+
+That's it. The installer is idempotent (safe to re-run); it registers the MCP server, copies the plugin + skills, and leaves a root credential at `$AGORA_HOME/.agora/root.token` (0600).
+
+Now just talk to your opencode session as usual:
+
+| You say | What happens |
+|---|---|
+| *"Have an agent fix X in repoY, verify with `pytest -q`"* | Task created, worker dispatched into its own worktree |
+| *"How's it going?"* | Live board: five buckets, dependency chains, escalation feed |
+| *"Stop that task"* | Cascade-cancel with confirmation |
+| *"Bump the dependency in repoA, then apply the same fix in repoB and repoC"* | `after:` dependency chain — B and C wait for A, unrelated repos run in parallel |
+
+Standalone dashboard: `agora-board` (vi-motion TUI). Update path: `git pull && ./install.sh`.
+
+## Where It Sits
+
+| | LLM-led orchestration | Machine-run quality gate |
+|---|:---:|:---:|
+| Task-graph orchestrators (plan once, execute a static graph) | ✗ | ✓ |
+| Agent-swarm frameworks | ✓ | ✗ (agents self-report) |
+| **opencode-agora** | ✓ | ✓ |
+
+Orchestration needs the model's flexibility — real intent surfaces mid-conversation, not in an upfront plan. Merge quality must not trust the agent — it has to run where the agent can't fake it. Most projects take one side; agora is built on the bet that you need both.
+
+Making your session an orchestrator isn't unique — subagent trees do that too. The unique part, on an open-source and model-neutral stack, is the **control plane that keeps the orchestrator honest**: verify gate, role-separated credentials, and append-only audit running as an independent service the agent cannot rewrite. Native tools may absorb this tomorrow; today the gap is real.
+
+Two capabilities this control plane buys in practice:
+
+- **Single repo: enforced worktree writes.** Every agent edit is forced into the task's own worktree by the plugin gate + session tokens — your main checkout is never touched. Convention becomes mechanism.
+- **Multiple repos: one root agent, sibling repos.** A single session at the parent directory orchestrates cross-repo chains with `after:` — the downstream task sees the upstream repo's merged result through the `../` sibling layout, while unrelated repos run in parallel.
+
+**Honest trade-offs** (the same reasons you might not want this):
+
+- A wrong `verify_cmd` at creation can stall a task — it fails safe: workers can't edit verify, so the worst case is a stuck task, never a bad merge
+- Your main session's context is the orchestration bottleneck — that's why `agora-board` exists: five-bucket state at a glance without spending conversation window
+- Every scheduling decision is a model call — if your work pre-decomposes into a clean static graph, a zero-token orchestrator is cheaper and more reproducible
+
+## How It Works
+
+```text
+Human ──▶ Main session (skills: agora-dispatch / agora-ops)
+              │  MCP (13 tools)
+              ▼
+         agorad — Python stdlib service on localhost
+         state authority · verify gate · auto-merge · message routing
+         crash recovery · audit ledger
+              │
+         Per-task git worktrees (enforced isolation)
+```
+
+Task lifecycle: `create → dispatch → worker codes → verify (service-run) → auto-merge (ff-only) → closed`
+
+After install, your session gains two skills (agora-dispatch / agora-ops) and 13 MCP tools. There is no background planner: the model you talk to **is** the orchestrator — task creation, `after:` chains, cancels, escalation replies are all model decisions from conversation context. agorad stays the state authority: verify executor, merge gate, message router, audit ledger.
+
+## Two Quality Gates
+
+**Verify gate** — the non-negotiable one. The verify command is registered at task creation (`task_create(verify_cmd="pytest -q")`, or `verify_pending: true` to defer). The **service runs it in the task worktree**, then trial-merges into a detached integration worktree and runs it again. Only two green runs advance the target branch; integration failures and test side effects never touch your main checkout. One hard requirement: your main checkout must be clean (no uncommitted or untracked changes) before the final push, otherwise the task reopens with a cleanup hint. Each run has a timeout (300 seconds by default). Red = the worker gets the output and retries. Three consecutive failures = blocked + escalation ping. The worker cannot skip it, fake it, or report results itself.
+
+**Review gate** — an open standard, bring your own reviewer. The contract is one anchor file:
+
+- If `.review-loop/` exists in the task worktree, the last-reviewed anchor is checked at `done` and **re-checked immediately before merge** (closes the "reviewed, then sneaked a commit" window).
+- Anchor green + verify green = automatic ff-only merge.
+- No `.review-loop/` directory? Everything still works — tasks complete at `done` and **you merge manually**. Autonomy is earned by both gates, not assumed.
+
+Any reviewer fits — OpenCodeReview, CodeRabbit, a human checklist — agora only reads the anchor. A minimal reviewer is ~10 lines:
+
+```bash
+#!/usr/bin/env bash
+# review-loop.sh <worktree> <target_branch> — run after each commit; exit non-zero if not green
+set -euo pipefail
+cd "$1"
+base=$(git merge-base HEAD "${2:?}"); sha=$(git rev-parse HEAD)
+findings=$(your_reviewer "$(git diff "$base"..HEAD)")   # OCR / CodeRabbit / human list
+printf '%s\n' "$findings" | grep -qiE 'blocker|high' && { printf '%s\n' "$findings"; exit 1; }
+mkdir -p .review-loop && printf '%s\n' "$sha" > .review-loop/.last-reviewed
+```
+
+Full spec — contract details, worker protocol, threat model, idle auto-trigger design notes: [docs/review-loop.md](docs/review-loop.md) (Chinese).
+
+## Highlights
+
+- **Verified autonomy** — auto-merge only after service-run tests pass and the review anchor is green, with the anchor re-verified at merge time
+- **Enforced isolation** — plugin-level gate blocks git-repo writes without task credentials; workers can't touch your main checkout. Accepted risk: nested dispatch lets a worker create subtasks on any local repo path with a self-chosen verify — worker-created task targets are not path-clamped
+- **Cross-repo and nested orchestration** — `after:` dependency chains; workers can create and manage their own subtasks, and a parent can finish only after child results return; hard limits on nesting (5) and concurrency (8)
+- **Role-separated credentials** — root / dispatcher / worker session tokens; workers can cancel or register verify only for their own subtasks, never manage parents or other tasks, or read the board
+- **Crash recovery** — `kill -9` the service at any moment; append-only state + worker re-injection with the same credentials on restart
+- **Real-time accountability** — escalation pings to the main session, append-only JSONL audit for every state change, health patrol for dead dispatchers
+- **PR-workflow friendly** — `task_create(target_branch="feature/x")` merges into a feature branch instead of main
+- **Lightweight** — Python stdlib service, zero pip dependencies, localhost only, no telemetry
+
+## Comparison
+
+| | Manual multi-session | Swarm frameworks | opencode-agora |
+|---|---|---|---|
+| Per-task isolation | you manage worktrees | varies | enforced (plugin gate + worktree per task) |
+| "Tests pass" means | agent says so | agent says so | service ran the command itself |
+| Cross-repo dependencies | manual sequencing | yes | `after:` chains, parallel when unrelated |
+| Merge | manual | varies | automatic, only when both gates are green |
+| Audit trail | none | partial | append-only JSONL, every state change |
+| Install footprint | — | heavy runtimes | python3 stdlib + git + bun |
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `AGORA_HOME` | `~/plaza` | Ledger home (state, messages, audit, wiki) |
+| `$AGORA_HOME/.agora/inactive-repos` | empty | Repos where agora is fully dormant (one path per line) |
+| `AGORA_BOARD_INTERVAL` | `5` | Dashboard poll interval (seconds) |
+| `AGORA_HEALTH_INTERVAL` | `300` | Dispatcher health patrol (seconds) |
+| `AGORA_VERIFY_TIMEOUT` | `300` | Timeout per task/integration verify run (seconds); expiry kills the process group |
+| `enforce` | on | Global gate switch (root only, audited) |
+| `$AGORA_HOME/.agora/email.json` | off | Stuck-task email alerts (`{"to","command"}`) |
+
+## Safety Model
+
+Honest by design — what's machine-checked vs what's trusted:
+
+**Enforced** (cannot be bypassed):
+- Git-repo writes only within task worktrees (plugin gate + session tokens)
+- Verify must actually run and pass, executed by the service
+- Role matrix: workers can't cancel, modify verify, or toggle enforce
+- Every state change lands in the append-only audit ledger
+
+**Accepted risks** (single-machine trust model):
+- A worker using raw `bash` can bypass the write gate (audit is the backstop)
+- Token theft within the same user account
+- The review anchor is a process protocol, not an anti-cheat: the worker writes it, the service reads it. The verify gate is the real quality bar; review adds discipline, not security
+
+## FAQ
+
+**How do I update?** `git pull && ./install.sh` — the plugin and service payloads are copies, so re-running the installer is required after pulling.
+
+**How do I uninstall?**
+```bash
+rm -rf ~/.config/opencode/plugins/agora ~/.config/opencode/skills/agora-dispatch \
+       ~/.config/opencode/skills/agora-ops ~/.local/bin/agora ~/.local/bin/agora-board \
+       ~/plaza ~/.agora-home
+# then remove the "agora" entry from the mcp section of ~/.config/opencode/opencode.json
+```
+
+(`~/plaza` is the default `AGORA_HOME` — if you configured a custom one, remove that directory instead.)
+
+**Does it work without a review-loop?** Yes — verify still runs and gates everything; tasks finish at `done` and you merge manually. Implement the [open standard](docs/review-loop.md) to unlock auto-merge.
+
+**Where does my code go?** Nowhere. agorad binds to localhost, workers are local opencode sessions, there is no telemetry, no cloud, no agora API keys. Whatever models your opencode uses, agora orchestrates them.
+
+**Platforms?** Linux (verified). macOS: the code paths are in place (the installer falls back to `nohup` where `setsid` is absent) but not yet verified on a real Mac. Windows: run inside WSL.
+
+## License
+
+MIT

opencode_agora-0.1.0/agora

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""agora CLI（F14）：bash 可判定的只读条件谓词——看门狗规范条件等待。
+
+wait 子命令阻塞等待任务终态（merged/closed/blocked/cancelled），对齐
+docker wait / kubectl wait 约定。status 子命令（F28 防误杀）单查任务三态
+判读：数据全取既有 /board 单任务视图＋/doctor（零服务端新端点），分类
+客户端推导。取数照抄 board_tui.py 形态：
+$AGORA_HOME/.agora/{root.token,service.json}，零直读状态文件、零格式逆向。
+非 MCP agora.wait(seconds)（那是 agent 回合内本地睡眠，两者不互替）。
+"""
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+TERMINAL = frozenset(("merged", "closed", "blocked", "cancelled"))
+_INFLIGHT = ("todo", "dispatched", "running", "done", "verify_failed", "reopened")
+_INTERVAL = 15        # 内部轮询间隔（秒）
+_HTTP_TIMEOUT = 5     # 单次请求超时（board_tui 同值）
+_TIMEOUT_MSG = "须为非负有限秒数"
+_STALE_AFTER = 1200   # 心跳冷阈值（秒）——与 agorad report._STALE_AFTER 同口径（客户端推导锚）
+
+
+class Fail(Exception):
+    """终局异常（不可重试）——exit 2。"""
+
+
+class Transient(Exception):
+    """瞬时不可达（连接拒等 OSError 族）——阻塞形态内部重试吸收。"""
+
+
+class Rejected(Transient):
+    """认牌失败（401/403）——牌换代窗口瞬态；不跟随换模时仍终局 Fail。"""
+
+
+def _pointer_home():
+    """~/.agora-home 指针回退（gt-32c051 统一发现桥；board_tui 同形）。"""
+    try:
+        return ((Path.home() / ".agora-home").read_text(encoding="utf-8")
+                .split("\n", 1)[0].strip() or None)
+    except (OSError, ValueError):  # ValueError＝坏字节（UnicodeDecodeError 非 OSError 族）
+        return None
+
+
+def discover(home=None):
+    """root 牌＋端口：$AGORA_HOME/.agora/{root.token,service.json}（board_tui 同形）。"""
+    home = Path(home or os.environ.get("AGORA_HOME") or _pointer_home()
+                or Path.home() / "plaza")
+    sj = json.loads((home / ".agora" / "service.json").read_text(encoding="utf-8"))
+    port = int(sj["port"])  # 非数端口（半写形态）在此炸 ValueError/TypeError，不外溢 fetch
+    token = (home / ".agora" / "root.token").read_text(encoding="utf-8").strip()
+    if "\n" in token or "\r" in token:  # 控制符会让 putheader 带牌面炸进 stderr／折叠改头
+        raise ValueError("root 牌撕裂（含换行/回车）")
+    return f"http://127.0.0.1:{port}", token
+
+
+def _call(base, token, path, body):
+    """HTTP 取数缝（fetch/status 共用）：POST <path> 带 root 牌回解析 JSON。
+
+    401/403→Rejected（换模跟随窗按瞬态）、其余 HTTP 错→Fail（404 注任务未知）、
+    网络错（OSError 族）→Transient（可重试）。
+    """
+    req = urllib.request.Request(
+        base + path, data=json.dumps(body).encode(),
+        headers={"Content-Type": "application/json", "X-Agora-Token": token},
+        method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT) as r:
+            return json.loads(r.read().decode())
+    except urllib.error.HTTPError as e:
+        if e.code in (401, 403):  # 认牌失败：牌换代/撕裂对窗口，跟随形态按瞬态
+            raise Rejected(f"HTTP {e.code}: {path}") from None
+        note = "（任务未知）" if e.code == 404 and path == "/board" else ""
+        raise Fail(f"HTTP {e.code}" + note + f": {path}") from None
+    except OSError as e:  # URLError（连接拒等）＝瞬时，可重试
+        raise Transient(str(e)) from None
+
+
+def fetch(base, token, tid):
+    """POST /board 单任务视图 → (state, commit)。报因尾附 tid（看门狗聚合 stderr 可归任务）。"""
+    try:
+        t = _call(base, token, "/board", {"task": tid})["task"]
+    except (Fail, Rejected) as e:
+        raise type(e)(f"{e}: {tid}") from None
+    return t["state"], t.get("commit")
+
+
+def classify(state):
+    """状态分类缝（exit code 决策）：终态→0，在飞（含未知态）→1。"""
+    return 0 if state in TERMINAL else 1
+
+
+def wait(tid, base, token, timeout=1800, once=False, interval=_INTERVAL,
+         clock=time.monotonic, pause=time.sleep, reread=None):
+    """轮询至终态：返回 (exit, stdout 行)；重试至超时仍不可达 raise Fail。
+
+    reread（run_wait 注入 discover）每轮轮询前重读指针——服务换模
+    （杀旧拉新、端口/牌换代）即跟随新端点续等，不对死端口空转到超时；
+    跟随时认牌失败（401/403，撕裂对/换代窗口）按瞬态重试。
+    """
+    deadline = clock() + timeout
+    while True:
+        if reread:
+            try:
+                nb, nt = reread()
+                if nb and nt:  # 半写空端点/空牌不采纳，保持旧端点下轮再读
+                    base, token = nb, nt
+            except (OSError, ValueError, TypeError, KeyError):
+                pass  # 指针半写/缺失（含非 dict JSON）保持旧端点，下轮再读
+        try:
+            state, commit = fetch(base, token, tid)
+        except Transient as e:
+            if isinstance(e, Rejected) and reread is None:
+                raise Fail(str(e)) from None  # 不跟随换模：认牌失败维持终局
+            if once or clock() >= deadline:
+                head = ("认牌失败" if isinstance(e, Rejected)
+                        else "服务不可达" if once else "服务不可达（重试至超时）")
+                raise Fail(f"{head}: {e}") from None
+        else:
+            if classify(state) == 0:
+                return 0, (f"{state} @{commit[:12]}" if commit else state)
+            if once or clock() >= deadline:
+                return 1, f"in-flight: {state}"
+        pause(min(interval, max(0.0, deadline - clock())))
+
+
+def run_wait(a):
+    base, token = discover()
+    if not token:
+        raise Fail("root 牌缺失")
+    code, line = wait(a.task_id, base, token, timeout=a.timeout, once=a.once,
+                      reread=discover)
+    print(line)
+    return code
+
+
+def status_view(tid, task, stale_ids, now):
+    """F28 三态判读（客户端推导，零服务端新端点）：数据＝/board 单任务视图＋/doctor。
+
+    fresh＝心跳近（last_seen 距今≤_STALE_AFTER）；busy_round＝在飞＋心跳冷＋
+    不在 doctor stale_candidates（基线含 env 活性，env 在写＝深潜中）；stale_candidate
+    ＝在 doctor 僵态候选单。终态或无 worker＝无判读（class None）。
+    """
+    state = task["state"]
+    seen = task.get("last_seen")
+    ago = None if not seen else max(0, int(now - seen))
+    if state in TERMINAL or not task.get("worker_sid"):
+        cls = None
+    elif tid in stale_ids:
+        cls = "stale_candidate"
+    elif ago is None or ago > _STALE_AFTER:
+        cls = "busy_round"
+    else:
+        cls = "fresh"
+    return {"task": tid, "state": state, "last_seen_ago": ago, "class": cls}
+
+
+def run_status(a):
+    base, token = discover()
+    if not token:
+        raise Fail("root 牌缺失")
+    now = time.time()
+    try:
+        task = _call(base, token, "/board", {"task": a.task_id})["task"]
+        doc = _call(base, token, "/doctor", {})
+    except Fail as e:  # 报因尾附 tid（镜像 fetch：看门狗聚合 stderr 可归任务）
+        raise type(e)(f"{e}: {a.task_id}") from None
+    except Transient as e:  # 单查不重试：判读要新鲜，旧数据不如报错
+        head = "认牌失败" if isinstance(e, Rejected) else "服务不可达"
+        raise Fail(f"{head}: {e}: {a.task_id}") from None
+    v = status_view(a.task_id, task,
+                    {tid for tid, _ in doc.get("stale_candidates", [])},
+                    now)  # 旧 daemon 无该键→空集降级，不裸 KeyError
+    if a.json:
+        print(json.dumps(v, ensure_ascii=False))
+    else:
+        ago = "-" if v["last_seen_ago"] is None else f"{v['last_seen_ago']}s"
+        print(f"{v['task']} state={v['state']} last_seen={ago} "
+              f"class={v['class'] or '-'}")
+    return 0
+
+
+def _timeout_arg(v):
+    """非负有限秒数；拒 nan/inf/负值（nan 会让 deadline 比较恒 False 变热轮询）。"""
+    try:
+        t = float(v)
+    except (ValueError, TypeError):
+        raise argparse.ArgumentTypeError(_TIMEOUT_MSG) from None
+    if not 0 <= t < float("inf"):
+        raise argparse.ArgumentTypeError(_TIMEOUT_MSG)
+    return t
+
+
+def _parser():
+    ap = argparse.ArgumentParser(
+        prog="agora",
+        description="agora CLI——bash 可判定的只读条件谓词（F14）。")
+    sub = ap.add_subparsers(dest="cmd", required=True, metavar="command")
+    w = sub.add_parser(
+        "wait", help="阻塞等待任务终态（--once 单查）",
+        description="阻塞等待任务终态（--once 单查）；非 MCP agora.wait(seconds)"
+                    "（那是 agent 回合内本地睡眠）。",
+        epilog="退出码：0＝终态到达（merged/closed/blocked/cancelled 任一）\n"
+               f"1＝--timeout 到期仍在飞（{'/'.join(_INFLIGHT)}），"
+               "或 --once 下当前在飞\n"
+               "2＝异常（用法错/任务未知 404/root 牌缺失/认牌失败/重试至超时仍不可达）",
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    w.add_argument("task_id", metavar="task-id", help="任务 id（ag-xxxxxx 或历史 task-/gt-xxxxxx）")
+    w.add_argument("--timeout", type=_timeout_arg, default=1800,
+                   help="到期仍在飞退出 1（秒）；缺省 1800（防调用方永挂）")
+    w.add_argument("--once", action="store_true", help="单查形态，立即返回不阻塞")
+    w.set_defaults(fn=run_wait)
+    s = sub.add_parser(
+        "status", help="任务三态判读单查（F28 防误杀：cancel 前先看一眼）",
+        description="单查任务三态判读：state＋last_seen 距今秒＋分类——"
+                    "fresh(心跳近)/busy_round(在飞＋心跳冷＋非僵态候选)/"
+                    "stale_candidate(在 doctor 僵态候选单)；数据取 /board＋/doctor。",
+        epilog="退出码：0＝取数成功（判读读输出，不作退出码）\n"
+               "2＝异常（用法错/任务未知/不可达/认牌失败）",
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    s.add_argument("task_id", metavar="task-id", help="任务 id（ag-xxxxxx 或历史 task-/gt-xxxxxx）")
+    s.add_argument("--json", action="store_true", help="机器可读 JSON 形态")
+    s.set_defaults(fn=run_status)
+    return ap
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    try:
+        a = _parser().parse_args(argv)
+        return a.fn(a)
+    except KeyboardInterrupt:
+        return 130  # 打断≠终态：非零防看门狗误判 merged
+    except Exception as e:
+        print(f"agora: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())