peerhub 0.1.10__tar.gz

peerhub-0.1.10/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 greatgc-flow
+
+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.

peerhub-0.1.10/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: peerhub
+Version: 0.1.10
+Summary: Local transactional coordination for collaborating AI peers
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/greatgc-flow/peerhub
+Project-URL: Repository, https://github.com/greatgc-flow/peerhub
+Project-URL: Issues, https://github.com/greatgc-flow/peerhub/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typing_extensions>=4.6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
+Requires-Dist: pyright>=1.1.370; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: alembic>=1.13.0; extra == "dev"
+Dynamic: license-file
+
+# peerhub
+
+A lightweight, installable coordination layer for orchestrating multiple AI CLI agents (Claude, Codex, Antigravity, ...) as collaborating peers: dispatch, routing, consensus, and health. It's built to eventually replace an existing hand-rolled multi-peer coordination system (`hub.py`) with a proper, tested package.
+
+## Status (2026-08-17)
+
+**`peerhub ask` works end-to-end today** — it genuinely dispatches a prompt to a real peer CLI (agy/claude/codex) through peerhub's own governance, admission, and process-supervision layers, and returns the response. See "Try it" below.
+
+- **Implemented**:
+  - Coordination kernel: dispatch, process supervision, heartbeat/liveness, routing, health, telemetry, SQLite persistence.
+  - GovernanceBroker's outbox/delivery-tracking split is fully completed end-to-end (legacy mirror writes removed, tables dropped).
+  - Capability-lease enforcement (all 5 increments): required capability tier threaded end-to-end, with an atomic pre-spawn enforcement gate and explicitly documented evidence audit.
+  - Persistence UoW split (read/write separation) and a migration-runner sequence-derivation fix that fast-fails on FK violations.
+  - A typed command boundary (`ApplicationAPI`/`Client`) with Pydantic v2 strict validation at the wire edge.
+  - **Real peer adapters** for all 3 target CLIs — `RealAgyAdapter`, `RealClaudeAdapter`, `RealCodexAdapter` — each proven both standalone and through the full supervised `dispatch_and_execute()` pipeline (not a bypass), plus a `FakePeerAdapter` for tests. Selectable via a peer-kind registry (`peerhub.adapters.registry`).
+  - **A real CLI**: `peerhub --version`, `peerhub status [--workspace PATH] [--peer/--all]`, and `peerhub ask PEER PROMPT [options]` — the last one performs a genuine end-to-end dispatch (admission → routing → supervised process execution → decoded response), not a stub. See "Try it" below.
+  - A direct-ask admission bootstrap (`peerhub.direct-ask/v1`) that auto-provisions a real, measured-readiness health/routing configuration for a single requested peer on a fresh workspace — no manual policy setup required.
+  - Static type checking (Pyright, 0 errors) and CI (GitHub Actions: pytest + pyright on every push/PR).
+  - A ratified traceability convention and fact-refresh procedure (`docs/design/TRACEABILITY-CONVENTION-R1.md`, `docs/design/FACT-REFRESH-PROCEDURE-R1.md`) — the fact-refresh tool (`tools/peerhub_facts/`) is built, functional, and handles drift reporting via live CLI probes.
+  - The full T1 Phase 3 outer loop: `dispatch_with_retries()`, session resume, streaming, tool-call capture, and failover routing.
+  - Multi-peer broadcast primitive A: Correlation schema and a working `BroadcastCoordinator.fan_out()` loop (T3).
+  - `EvidenceArtifact` / 3-tier context partitioning (completed for Claude and Codex adapters).
+  - Health/quota tracking CLI surface: `peerhub status --peer/--all` and quota telemetry persistence.
+  - Ctrl-C during `peerhub ask` walks the real cancellation ladder (`SOFT_CANCEL` → `TERMINATE_TREE` → `KILL_TREE`) via a proper background-thread dispatch and cancellation hook.
+- **Designed, but not yet built**:
+  - Health/quota tracking's periodic background polling (`TelemetryWorker`) — currently awaiting a user decision on the process-host model (e.g., poll-on-demand vs. daemon).
+  - Windows-native Brokered Read-Only Reducers — blocked pending a policy call on required OS privileges.
+- **Explicitly deferred (with named triggers)**:
+  - Alembic runtime cutover: Ratified as HOLD. The bespoke runner remains the sole runtime migration engine. Will revisit only if peerhub adopts SQLAlchemy ORM or is about to become the primary dispatch path.
+  - Formal multi-peer consensus (voting machinery / Primitive B): Deferred until the first `r10_requires_finalized_for` decision class is actually routed to peerhub.
+  - Durable response transcripts for broadcast: Deferred until a dispatch-layer durability mechanism is ratified.
+  - Capability-lease enforcement evidence: Changing adapter receipts to claim positive enforcement is deferred until a machine-owned launcher, plan-bound digest, empirical negative probe, and post-plan corroboration gate exist.
+  - Parallel fan-out: Deferred (blocked on measuring SQLite write contention).
+- **Not yet implemented / honest gaps**:
+  - Phase 4 shadow-by-ownership-cluster validation and same-revision comparison + rollback proof.
+  - Crash-linkage recovery (resuming an interrupted round after a coordinator crash).
+  - Detailed per-vendor error-taxonomy mapping, and PTY transport are deliberately out of scope for the current adapter slice.
+  - No shadow-mode validation yet (routing a subset of real traffic through peerhub in parallel with `hub.py` for comparison before any real cutover) — `hub.py` remains the authoritative system for real multi-peer coordination work today; `peerhub ask` is a real, working command, not yet a production replacement.
+
+See [`docs/design/HUB-REPLACEMENT-ROADMAP-2026-08-09.md`](docs/design/HUB-REPLACEMENT-ROADMAP-2026-08-09.md) for the full phased plan toward functional hub.py parity, and [`docs/design/PEERHUB-P-DRIVE-ISOLATION-2026-08-09.md`](docs/design/PEERHUB-P-DRIVE-ISOLATION-2026-08-09.md) for how peerhub's own runtime state relates to (and is deliberately isolated from) the wider P: development environment this repo happens to live inside during development. For the Engram/peerhub architectural separation itself (Engram is a portable dev-environment package, peerhub is the standalone AI-collaboration layer that used to live inside it) — what's done, what's verified clean in both directions, and what's left on either side — see [Engram's `2026-09-03_separation-completion-backlog.md`](https://github.com/greatgc-flow/Engram/blob/main/_sys/data/sessions/2026-09-03_separation-completion-backlog.md).
+
+**hub.py-replacement TDD (2026-08-27, in progress; last updated 2026-09-02)**: real, tested code now exists for gap-2 (consensus), gap-4 (duty-lease), gap-5 (task lifecycle), gap-6 (governance/lessons, capability matching) in full, and gap-3/gap-7 partially. **All 6 domains now have real, runnable CLI commands** — `peerhub consensus|task|lesson|room|duty|session`, see "Try it" below — and `LegacyTranslator` (`peerhub/application/legacy.py`) translates 71 of the 90 legacy `hub.py` action names into typed wire commands for these same domains (plus a new room-participation-session domain — `init-session`/`end-session`, backed by a new `RoomParticipationCoordinator`, a new private-mailbox domain — `send`/`check`/`mark-read`/`thread-promote`/`lesson-broadcast`, a final-arbiter escalation domain — `arbiter-review`, backed by `ArbiterReviewCoordinator`, a peer-node-registry domain — `register-node`/`list-nodes`, backed by `PeerRegistryService`, a durable role-assignment domain — `assign-role`/`release-role`/`role-status`, backed by `RoleAssignmentService`, a feedback-journal domain — `feedback-add`/`feedback-list`/`feedback-resolve`, backed by `FeedbackService`, an operational-error journal domain — `report-error`, backed by `OperationalErrorService`, a workspace-global leadership domain — `leader-claim`/`leader-yield`, backed by `LeadershipService`, the core room-status aggregate — `status`, backed by `RoomsService`, plus (since 2026-09-01/02) health/admission quick wins — `health-check`/`peer-status`/`peer-recover`/`health-precheck`/`check-gate`/`health-sweep`/`peer-quarantine`, session-lease visibility — `lease-status`/`lease-sweep`, room coordination — `update-status`/`thread-new`/`broadcast`, model/profile binding — `model-status`, governance proposals — `proposal-add`/`proposal-vote` backed by a new `ProposalCoordinator`, a durable artifact ledger — `artifact-claim`/`artifact-status`/`artifact-finalize` backed by a new `ArtifactRecordService`, a bounded effect-outbox view — `broker-status`, and capability-scored leadership — `discover`/`elect-leader` backed by `CapabilityMatchingCoordinator`/`CapabilityConfigService`/`ElectionAuditService`). **All 71 of those actions now execute end-to-end**: `ApplicationAPI` registers a `CommandDescriptor` for each one, backed by the same real services the native CLI uses, so a legacy action name genuinely runs through `LegacyTranslator.translate()` → `Client.submit()` → a persisted result, not just a name-to-wire-command translation. See [`docs/design/HUB-REPLACEMENT-TDD-PROGRESS-2026-08-27.md`](docs/design/HUB-REPLACEMENT-TDD-PROGRESS-2026-08-27.md) for exactly what's real vs. still missing — the remaining 19 of the 90 `LEGACY_CATALOG` actions are each a settled, cited, permanent waiver (host-environment-only tooling, an architecturally-incompatible generic write queue, upstream account/billing management peerhub deliberately does not fake, one policy divergence, and a known counting-formula nuance around `ask`/`ask-all`/`ask-coordinator`'s non-executing translator branches) — not open work. **See [`docs/design/PEERHUB-BACKLOG-2026-08-27.md`](docs/design/PEERHUB-BACKLOG-2026-08-27.md) for the full consolidated remaining-work backlog**, organized by how ready each item is (mechanical wiring vs. needs new component code vs. needs a design round vs. entirely undesigned domain), and [`docs/design/SESSION-LESSONS-INDEX-2026-09-02.md`](docs/design/SESSION-LESSONS-INDEX-2026-09-02.md) for a topic-indexed pointer into this session's recurring bug classes and process lessons (peer-dispatch reliability, codebase-specific pitfalls, design discipline), each linking back to its full account in the TDD progress log rather than restating it.
+
+**hub.py-replacement design phase (2026-08-23 to 2026-08-26): DESIGN-complete, TDD-ready.** The 7 functional categories `hub.py` covers beyond basic dispatch — compat/cutover strategy, consensus, session/room/thread continuity, health/leadership/duty-lease, task lifecycle/approval, governance/learning, and diagnostics parity — each now have either a concrete `TargetState` JSON schema or a concrete dedicated design, all converged and ratified (52 of 53 remaining open items resolved by design-consistency reasoning, 1 genuine business decision resolved by the user, 1 shared infrastructure prerequisite scoped as its own task). Start at [`docs/design/HUB-REPLACEMENT-PRE-TDD-FINAL-RATIFICATION-2026-08-26.md`](docs/design/HUB-REPLACEMENT-PRE-TDD-FINAL-RATIFICATION-2026-08-26.md) (supersedes older per-doc "Unresolved" lists), then [`docs/design/HUB-REPLACEMENT-DESIGN-REINFORCEMENT-INDEX-2026-08-24.md`](docs/design/HUB-REPLACEMENT-DESIGN-REINFORCEMENT-INDEX-2026-08-24.md) for the full per-gap breakdown. **Update**: most of this design has since been implemented during the TDD phase below (consensus, task, lessons, duty-lease, and half of session/room/thread) — see [`docs/design/PEERHUB-BACKLOG-2026-08-27.md`](docs/design/PEERHUB-BACKLOG-2026-08-27.md) for exactly what from this design phase is still unimplemented.
+
+The target architecture was designed and converged through a 9-round adversarial review (`ag`/`cx`/`cc`) documented in [`docs/design/ARCHITECTURE.md`](docs/design/ARCHITECTURE.md). The full debate record, including rejected alternatives and evidence citations, is in [`docs/design/peerhub-architecture-debate.md`](docs/design/peerhub-architecture-debate.md). Later design decisions are under [`docs/design/`](docs/design/), dated by filename.
+
+## Install
+
+### Option A: Install via Pip from GitHub Release (Recommended)
+
+```bash
+pip install "git+https://github.com/greatgc-flow/peerhub.git@v0.1.10"
+```
+
+### Option B: Local Editable Development Install
+
+```bash
+git clone https://github.com/greatgc-flow/peerhub.git
+cd peerhub
+pip install -e .          # runtime only
+pip install -e .[dev]     # + pytest, pyright, hypothesis, alembic (needed to run tests/type-check locally)
+```
+
+Requires Python >= 3.11. This installs the `peerhub` package and registers a `peerhub` entrypoint on your PATH (verified via a real sdist build + install: `pyproject.toml`'s `[project.scripts]` defines only `peerhub`, not a separate `hub` alias).
+
+## Try it
+
+```bash
+peerhub --version
+
+# Real-time multi-peer quota telemetry, headroom matrix, and active failover routing targets
+peerhub diag
+# Add a governed-domain state section (consensus/task/lesson) to the same command
+peerhub diag --domains --workspace ./my-workspace
+
+# Check a workspace (read-only; reports "uninitialized" if no database yet)
+peerhub status --workspace ./my-workspace
+
+# Auto-detect which built-in peer CLIs (agy/claude/codex) are installed and
+# resolvable on PATH right now -- no workspace required
+peerhub adapter discover
+peerhub adapter discover --json   # MEASURED/UNAVAILABLE/ABSENT per peer
+
+# Genuinely dispatch a prompt to a real peer and get its response
+peerhub ask ag "say hello in exactly three words" --capability-tier READ_ONLY
+peerhub ask cc "..." --capability-tier READ_ONLY --profile <profile-id>   # claude, if you have more than one profile configured
+peerhub ask cx "..." --capability-tier WORKTREE_WRITE --json              # structured output instead of plain text
+
+# Multi-peer broadcast coordination across peers with unified consensus
+peerhub broadcast "reply with exactly: pong" --peers ag,cx --capability-tier READ_ONLY
+
+# Propose a consensus round
+peerhub consensus propose --round-id r1 --title "Ship" --question "Ready?" --body "Decide" --proposer cx --required cx,ag --eligible cx,ag
+# Create a task
+peerhub task create --task-id t1 --summary "Ship" --spec "Do it" --creator cx
+# Propose a governance lesson
+peerhub lesson propose --lesson-id l1 --title "Rule" --rule "Do this" --category ops --severity HIGH --proposer cx --affected cx,ag
+# Create a room
+peerhub room create --room-id room1 --topic-id topic1 --title "Work" --creator cx --participants cx,ag
+# Claim terminal duty
+peerhub duty claim --room-id room1 --instance-id i1 --profile-id cx.standard --owner-principal-id p1 --authority-epoch 1
+# Open a room-participation session
+peerhub session open --workspace-scope-id ws1 --room-id room1 --actor-principal-id p1 --instance-id i1 --profile-id cx.standard --session-fingerprint fp1
+```
+
+`ask` accepts `--capability-tier` (required: READ_ONLY, WORKTREE_WRITE, GIT_MUTATE, REMOTE_MUTATE),
+`--workspace PATH` (default `.`), `--profile PROFILE_ID`,
+`--timeout-seconds`/`--silence-timeout-seconds`/`--max-output-bytes`
+(process limits), and `--json`. Exit codes: `0` verified response,
+`2` usage/config/pre-spawn failure (unknown peer, executable not found,
+readiness probe failed), `3` definite peer/protocol failure, `4`
+uncertain execution (timeout, lost lease ownership), `130` interrupted.
+It requires the real peer CLI (`agy.exe`/`claude.cmd`/`codex.cmd`) to be
+installed and authenticated on your machine — `ask` will tell you clearly
+if it can't find or run one, rather than failing silently.
+
+Example `status` output against a workspace with one active lease:
+```
+Workspace: /path/to/my-workspace
+Database: /path/to/my-workspace/.peerhub/peerhub.sqlite3
+Schema Migrations Applied: 24
+Health Circuit ('system'): (no listing API exists yet -- not queryable from the CLI)
+Active Leases: 1
+Status: OK
+```
+
+## Run the tests
+
+```bash
+pytest -q                 # fast suite, no real CLI calls
+pytest -q -m slow          # + the real-adapter/real-dispatch integration tests (needs real CLIs installed & authenticated, real wall-clock time)
+pyright                    # static type check, should report 0 errors
+```
+
+This repo's own convention (see `docs/design/FACT-REFRESH-PROCEDURE-R1.md`)
+is to never cite a specific "current passing count" in this file — it
+changes with nearly every commit. Run `pytest -q` yourself for the real,
+current number.

peerhub-0.1.10/README.md

@@ -0,0 +1,139 @@
+# peerhub
+
+A lightweight, installable coordination layer for orchestrating multiple AI CLI agents (Claude, Codex, Antigravity, ...) as collaborating peers: dispatch, routing, consensus, and health. It's built to eventually replace an existing hand-rolled multi-peer coordination system (`hub.py`) with a proper, tested package.
+
+## Status (2026-08-17)
+
+**`peerhub ask` works end-to-end today** — it genuinely dispatches a prompt to a real peer CLI (agy/claude/codex) through peerhub's own governance, admission, and process-supervision layers, and returns the response. See "Try it" below.
+
+- **Implemented**:
+  - Coordination kernel: dispatch, process supervision, heartbeat/liveness, routing, health, telemetry, SQLite persistence.
+  - GovernanceBroker's outbox/delivery-tracking split is fully completed end-to-end (legacy mirror writes removed, tables dropped).
+  - Capability-lease enforcement (all 5 increments): required capability tier threaded end-to-end, with an atomic pre-spawn enforcement gate and explicitly documented evidence audit.
+  - Persistence UoW split (read/write separation) and a migration-runner sequence-derivation fix that fast-fails on FK violations.
+  - A typed command boundary (`ApplicationAPI`/`Client`) with Pydantic v2 strict validation at the wire edge.
+  - **Real peer adapters** for all 3 target CLIs — `RealAgyAdapter`, `RealClaudeAdapter`, `RealCodexAdapter` — each proven both standalone and through the full supervised `dispatch_and_execute()` pipeline (not a bypass), plus a `FakePeerAdapter` for tests. Selectable via a peer-kind registry (`peerhub.adapters.registry`).
+  - **A real CLI**: `peerhub --version`, `peerhub status [--workspace PATH] [--peer/--all]`, and `peerhub ask PEER PROMPT [options]` — the last one performs a genuine end-to-end dispatch (admission → routing → supervised process execution → decoded response), not a stub. See "Try it" below.
+  - A direct-ask admission bootstrap (`peerhub.direct-ask/v1`) that auto-provisions a real, measured-readiness health/routing configuration for a single requested peer on a fresh workspace — no manual policy setup required.
+  - Static type checking (Pyright, 0 errors) and CI (GitHub Actions: pytest + pyright on every push/PR).
+  - A ratified traceability convention and fact-refresh procedure (`docs/design/TRACEABILITY-CONVENTION-R1.md`, `docs/design/FACT-REFRESH-PROCEDURE-R1.md`) — the fact-refresh tool (`tools/peerhub_facts/`) is built, functional, and handles drift reporting via live CLI probes.
+  - The full T1 Phase 3 outer loop: `dispatch_with_retries()`, session resume, streaming, tool-call capture, and failover routing.
+  - Multi-peer broadcast primitive A: Correlation schema and a working `BroadcastCoordinator.fan_out()` loop (T3).
+  - `EvidenceArtifact` / 3-tier context partitioning (completed for Claude and Codex adapters).
+  - Health/quota tracking CLI surface: `peerhub status --peer/--all` and quota telemetry persistence.
+  - Ctrl-C during `peerhub ask` walks the real cancellation ladder (`SOFT_CANCEL` → `TERMINATE_TREE` → `KILL_TREE`) via a proper background-thread dispatch and cancellation hook.
+- **Designed, but not yet built**:
+  - Health/quota tracking's periodic background polling (`TelemetryWorker`) — currently awaiting a user decision on the process-host model (e.g., poll-on-demand vs. daemon).
+  - Windows-native Brokered Read-Only Reducers — blocked pending a policy call on required OS privileges.
+- **Explicitly deferred (with named triggers)**:
+  - Alembic runtime cutover: Ratified as HOLD. The bespoke runner remains the sole runtime migration engine. Will revisit only if peerhub adopts SQLAlchemy ORM or is about to become the primary dispatch path.
+  - Formal multi-peer consensus (voting machinery / Primitive B): Deferred until the first `r10_requires_finalized_for` decision class is actually routed to peerhub.
+  - Durable response transcripts for broadcast: Deferred until a dispatch-layer durability mechanism is ratified.
+  - Capability-lease enforcement evidence: Changing adapter receipts to claim positive enforcement is deferred until a machine-owned launcher, plan-bound digest, empirical negative probe, and post-plan corroboration gate exist.
+  - Parallel fan-out: Deferred (blocked on measuring SQLite write contention).
+- **Not yet implemented / honest gaps**:
+  - Phase 4 shadow-by-ownership-cluster validation and same-revision comparison + rollback proof.
+  - Crash-linkage recovery (resuming an interrupted round after a coordinator crash).
+  - Detailed per-vendor error-taxonomy mapping, and PTY transport are deliberately out of scope for the current adapter slice.
+  - No shadow-mode validation yet (routing a subset of real traffic through peerhub in parallel with `hub.py` for comparison before any real cutover) — `hub.py` remains the authoritative system for real multi-peer coordination work today; `peerhub ask` is a real, working command, not yet a production replacement.
+
+See [`docs/design/HUB-REPLACEMENT-ROADMAP-2026-08-09.md`](docs/design/HUB-REPLACEMENT-ROADMAP-2026-08-09.md) for the full phased plan toward functional hub.py parity, and [`docs/design/PEERHUB-P-DRIVE-ISOLATION-2026-08-09.md`](docs/design/PEERHUB-P-DRIVE-ISOLATION-2026-08-09.md) for how peerhub's own runtime state relates to (and is deliberately isolated from) the wider P: development environment this repo happens to live inside during development. For the Engram/peerhub architectural separation itself (Engram is a portable dev-environment package, peerhub is the standalone AI-collaboration layer that used to live inside it) — what's done, what's verified clean in both directions, and what's left on either side — see [Engram's `2026-09-03_separation-completion-backlog.md`](https://github.com/greatgc-flow/Engram/blob/main/_sys/data/sessions/2026-09-03_separation-completion-backlog.md).
+
+**hub.py-replacement TDD (2026-08-27, in progress; last updated 2026-09-02)**: real, tested code now exists for gap-2 (consensus), gap-4 (duty-lease), gap-5 (task lifecycle), gap-6 (governance/lessons, capability matching) in full, and gap-3/gap-7 partially. **All 6 domains now have real, runnable CLI commands** — `peerhub consensus|task|lesson|room|duty|session`, see "Try it" below — and `LegacyTranslator` (`peerhub/application/legacy.py`) translates 71 of the 90 legacy `hub.py` action names into typed wire commands for these same domains (plus a new room-participation-session domain — `init-session`/`end-session`, backed by a new `RoomParticipationCoordinator`, a new private-mailbox domain — `send`/`check`/`mark-read`/`thread-promote`/`lesson-broadcast`, a final-arbiter escalation domain — `arbiter-review`, backed by `ArbiterReviewCoordinator`, a peer-node-registry domain — `register-node`/`list-nodes`, backed by `PeerRegistryService`, a durable role-assignment domain — `assign-role`/`release-role`/`role-status`, backed by `RoleAssignmentService`, a feedback-journal domain — `feedback-add`/`feedback-list`/`feedback-resolve`, backed by `FeedbackService`, an operational-error journal domain — `report-error`, backed by `OperationalErrorService`, a workspace-global leadership domain — `leader-claim`/`leader-yield`, backed by `LeadershipService`, the core room-status aggregate — `status`, backed by `RoomsService`, plus (since 2026-09-01/02) health/admission quick wins — `health-check`/`peer-status`/`peer-recover`/`health-precheck`/`check-gate`/`health-sweep`/`peer-quarantine`, session-lease visibility — `lease-status`/`lease-sweep`, room coordination — `update-status`/`thread-new`/`broadcast`, model/profile binding — `model-status`, governance proposals — `proposal-add`/`proposal-vote` backed by a new `ProposalCoordinator`, a durable artifact ledger — `artifact-claim`/`artifact-status`/`artifact-finalize` backed by a new `ArtifactRecordService`, a bounded effect-outbox view — `broker-status`, and capability-scored leadership — `discover`/`elect-leader` backed by `CapabilityMatchingCoordinator`/`CapabilityConfigService`/`ElectionAuditService`). **All 71 of those actions now execute end-to-end**: `ApplicationAPI` registers a `CommandDescriptor` for each one, backed by the same real services the native CLI uses, so a legacy action name genuinely runs through `LegacyTranslator.translate()` → `Client.submit()` → a persisted result, not just a name-to-wire-command translation. See [`docs/design/HUB-REPLACEMENT-TDD-PROGRESS-2026-08-27.md`](docs/design/HUB-REPLACEMENT-TDD-PROGRESS-2026-08-27.md) for exactly what's real vs. still missing — the remaining 19 of the 90 `LEGACY_CATALOG` actions are each a settled, cited, permanent waiver (host-environment-only tooling, an architecturally-incompatible generic write queue, upstream account/billing management peerhub deliberately does not fake, one policy divergence, and a known counting-formula nuance around `ask`/`ask-all`/`ask-coordinator`'s non-executing translator branches) — not open work. **See [`docs/design/PEERHUB-BACKLOG-2026-08-27.md`](docs/design/PEERHUB-BACKLOG-2026-08-27.md) for the full consolidated remaining-work backlog**, organized by how ready each item is (mechanical wiring vs. needs new component code vs. needs a design round vs. entirely undesigned domain), and [`docs/design/SESSION-LESSONS-INDEX-2026-09-02.md`](docs/design/SESSION-LESSONS-INDEX-2026-09-02.md) for a topic-indexed pointer into this session's recurring bug classes and process lessons (peer-dispatch reliability, codebase-specific pitfalls, design discipline), each linking back to its full account in the TDD progress log rather than restating it.
+
+**hub.py-replacement design phase (2026-08-23 to 2026-08-26): DESIGN-complete, TDD-ready.** The 7 functional categories `hub.py` covers beyond basic dispatch — compat/cutover strategy, consensus, session/room/thread continuity, health/leadership/duty-lease, task lifecycle/approval, governance/learning, and diagnostics parity — each now have either a concrete `TargetState` JSON schema or a concrete dedicated design, all converged and ratified (52 of 53 remaining open items resolved by design-consistency reasoning, 1 genuine business decision resolved by the user, 1 shared infrastructure prerequisite scoped as its own task). Start at [`docs/design/HUB-REPLACEMENT-PRE-TDD-FINAL-RATIFICATION-2026-08-26.md`](docs/design/HUB-REPLACEMENT-PRE-TDD-FINAL-RATIFICATION-2026-08-26.md) (supersedes older per-doc "Unresolved" lists), then [`docs/design/HUB-REPLACEMENT-DESIGN-REINFORCEMENT-INDEX-2026-08-24.md`](docs/design/HUB-REPLACEMENT-DESIGN-REINFORCEMENT-INDEX-2026-08-24.md) for the full per-gap breakdown. **Update**: most of this design has since been implemented during the TDD phase below (consensus, task, lessons, duty-lease, and half of session/room/thread) — see [`docs/design/PEERHUB-BACKLOG-2026-08-27.md`](docs/design/PEERHUB-BACKLOG-2026-08-27.md) for exactly what from this design phase is still unimplemented.
+
+The target architecture was designed and converged through a 9-round adversarial review (`ag`/`cx`/`cc`) documented in [`docs/design/ARCHITECTURE.md`](docs/design/ARCHITECTURE.md). The full debate record, including rejected alternatives and evidence citations, is in [`docs/design/peerhub-architecture-debate.md`](docs/design/peerhub-architecture-debate.md). Later design decisions are under [`docs/design/`](docs/design/), dated by filename.
+
+## Install
+
+### Option A: Install via Pip from GitHub Release (Recommended)
+
+```bash
+pip install "git+https://github.com/greatgc-flow/peerhub.git@v0.1.10"
+```
+
+### Option B: Local Editable Development Install
+
+```bash
+git clone https://github.com/greatgc-flow/peerhub.git
+cd peerhub
+pip install -e .          # runtime only
+pip install -e .[dev]     # + pytest, pyright, hypothesis, alembic (needed to run tests/type-check locally)
+```
+
+Requires Python >= 3.11. This installs the `peerhub` package and registers a `peerhub` entrypoint on your PATH (verified via a real sdist build + install: `pyproject.toml`'s `[project.scripts]` defines only `peerhub`, not a separate `hub` alias).
+
+## Try it
+
+```bash
+peerhub --version
+
+# Real-time multi-peer quota telemetry, headroom matrix, and active failover routing targets
+peerhub diag
+# Add a governed-domain state section (consensus/task/lesson) to the same command
+peerhub diag --domains --workspace ./my-workspace
+
+# Check a workspace (read-only; reports "uninitialized" if no database yet)
+peerhub status --workspace ./my-workspace
+
+# Auto-detect which built-in peer CLIs (agy/claude/codex) are installed and
+# resolvable on PATH right now -- no workspace required
+peerhub adapter discover
+peerhub adapter discover --json   # MEASURED/UNAVAILABLE/ABSENT per peer
+
+# Genuinely dispatch a prompt to a real peer and get its response
+peerhub ask ag "say hello in exactly three words" --capability-tier READ_ONLY
+peerhub ask cc "..." --capability-tier READ_ONLY --profile <profile-id>   # claude, if you have more than one profile configured
+peerhub ask cx "..." --capability-tier WORKTREE_WRITE --json              # structured output instead of plain text
+
+# Multi-peer broadcast coordination across peers with unified consensus
+peerhub broadcast "reply with exactly: pong" --peers ag,cx --capability-tier READ_ONLY
+
+# Propose a consensus round
+peerhub consensus propose --round-id r1 --title "Ship" --question "Ready?" --body "Decide" --proposer cx --required cx,ag --eligible cx,ag
+# Create a task
+peerhub task create --task-id t1 --summary "Ship" --spec "Do it" --creator cx
+# Propose a governance lesson
+peerhub lesson propose --lesson-id l1 --title "Rule" --rule "Do this" --category ops --severity HIGH --proposer cx --affected cx,ag
+# Create a room
+peerhub room create --room-id room1 --topic-id topic1 --title "Work" --creator cx --participants cx,ag
+# Claim terminal duty
+peerhub duty claim --room-id room1 --instance-id i1 --profile-id cx.standard --owner-principal-id p1 --authority-epoch 1
+# Open a room-participation session
+peerhub session open --workspace-scope-id ws1 --room-id room1 --actor-principal-id p1 --instance-id i1 --profile-id cx.standard --session-fingerprint fp1
+```
+
+`ask` accepts `--capability-tier` (required: READ_ONLY, WORKTREE_WRITE, GIT_MUTATE, REMOTE_MUTATE),
+`--workspace PATH` (default `.`), `--profile PROFILE_ID`,
+`--timeout-seconds`/`--silence-timeout-seconds`/`--max-output-bytes`
+(process limits), and `--json`. Exit codes: `0` verified response,
+`2` usage/config/pre-spawn failure (unknown peer, executable not found,
+readiness probe failed), `3` definite peer/protocol failure, `4`
+uncertain execution (timeout, lost lease ownership), `130` interrupted.
+It requires the real peer CLI (`agy.exe`/`claude.cmd`/`codex.cmd`) to be
+installed and authenticated on your machine — `ask` will tell you clearly
+if it can't find or run one, rather than failing silently.
+
+Example `status` output against a workspace with one active lease:
+```
+Workspace: /path/to/my-workspace
+Database: /path/to/my-workspace/.peerhub/peerhub.sqlite3
+Schema Migrations Applied: 24
+Health Circuit ('system'): (no listing API exists yet -- not queryable from the CLI)
+Active Leases: 1
+Status: OK
+```
+
+## Run the tests
+
+```bash
+pytest -q                 # fast suite, no real CLI calls
+pytest -q -m slow          # + the real-adapter/real-dispatch integration tests (needs real CLIs installed & authenticated, real wall-clock time)
+pyright                    # static type check, should report 0 errors
+```
+
+This repo's own convention (see `docs/design/FACT-REFRESH-PROCEDURE-R1.md`)
+is to never cite a specific "current passing count" in this file — it
+changes with nearly every commit. Run `pytest -q` yourself for the real,
+current number.

peerhub-0.1.10/peerhub/__init__.py

@@ -0,0 +1,5 @@
+"""PeerHub coordination engine."""
+
+__version__ = "0.1.7"
+
+__all__ = ("__version__",)

peerhub-0.1.10/peerhub/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""PeerHub adapter-boundary contract package."""
+
+from __future__ import annotations
+
+__all__ = [
+    "contract",  # pyright: ignore[reportUnsupportedDunderAll]
+]

peerhub-0.1.10/peerhub/adapters/agy_adapter.py

@@ -0,0 +1,253 @@
+"""Real Antigravity adapter implementation for Stage 3."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+
+from peerhub.adapters.contract import (
+    AdapterRequest,
+    Capability,
+    DecodedOutput,
+    DecoderEvent,
+    DecoderEventKind,
+    InvocationPlan,
+    OutputChannel,
+    OutputDecoder,
+    PeerDescriptor,
+    ProfileDescriptor,
+    ProtocolAssessment,
+    PromptPolicy,
+    SessionAction,
+    SessionHint,
+)
+from peerhub.core.protocol import ErrorCode
+from peerhub.core.execution import (
+    ProcessTerminalEvidence,
+    TransportKind,
+    TransportLimits,
+)
+
+
+def _split_canonical_lines(text: str) -> tuple[str, ...]:
+    if not text:
+        return ()
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    lines = normalized.split("\n")
+    if normalized.endswith("\n"):
+        lines = lines[:-1]
+    return tuple(lines)
+
+
+_AGY_PROFILE = ProfileDescriptor(
+    profile_id="ag.standard",
+    profile_class="tier",
+    supports_reasoning_effort=True,
+)
+
+_AGY_DESCRIPTOR = PeerDescriptor(
+    adapter_id="agy-peer",
+    adapter_version="1.0.0",
+    peer_kind="ag",
+    profiles=(_AGY_PROFILE,),
+    transports=frozenset({TransportKind.PIPE}),
+    capabilities=frozenset({Capability.SESSION}),
+    usage_provider_id=None,
+    readiness_probe_id="agy-readiness",
+)
+
+
+class AgyOutputDecoder:
+    """Decoder for agy.exe --output-format json."""
+
+    def __init__(self) -> None:
+        self._chunks: list[bytes] = []
+        self._finalized = False
+        self._events: list[DecoderEvent] = []
+
+    def feed(self, chunk: bytes, *, channel: OutputChannel = OutputChannel.STDOUT) -> tuple[DecoderEvent, ...]:
+        if self._finalized:
+            raise RuntimeError("feed called after finalize")
+        if type(chunk) is not bytes:
+            raise ValueError("chunk must be bytes")
+        self._chunks.append(chunk)
+        return ()
+
+    def finalize(self) -> DecodedOutput:
+        if self._finalized:
+            raise RuntimeError("finalize already called")
+        self._finalized = True
+
+        raw_bytes = b"".join(self._chunks)
+        canonical_text = ""
+        events: list[DecoderEvent] = []
+
+        try:
+            if raw_bytes:
+                decoded = raw_bytes.decode("utf-8")
+                start_idx = decoded.find("{")
+                end_idx = decoded.rfind("}")
+                if start_idx != -1 and end_idx != -1 and end_idx >= start_idx:
+                    json_str = decoded[start_idx:end_idx + 1]
+                    try:
+                        parsed = json.loads(json_str)
+
+                        conv_id = parsed.get("conversation_id")
+                        if conv_id and isinstance(conv_id, str):
+                            events.append(
+                                DecoderEvent(
+                                    kind=DecoderEventKind.SESSION_IDENTITY,
+                                    payload={"session_id": conv_id},
+                                )
+                            )
+
+                        response_text = parsed.get("response", "")
+                        canonical_text = response_text or decoded
+                        if response_text:
+                            event = DecoderEvent(
+                                kind=DecoderEventKind.ASSISTANT_TEXT,
+                                payload={"text": response_text},
+                            )
+                            events.append(event)
+                        if "error" in parsed:
+                            error_val = parsed["error"]
+                            err_type = ""
+                            if isinstance(error_val, dict):
+                                err_type = str(error_val.get("type", ""))  # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType]
+                            elif isinstance(error_val, str):
+                                err_type = error_val
+
+                            if err_type == "session_not_found":
+                                events.append(DecoderEvent(kind=DecoderEventKind.VENDOR_ERROR, payload={"normalized_kind": "session_invalid", "evidence_source": "structured_vendor_output"}))
+                            elif err_type == "invalid_model":
+                                events.append(DecoderEvent(kind=DecoderEventKind.VENDOR_ERROR, payload={"normalized_kind": "invocation_plan_rejected", "evidence_source": "structured_vendor_output"}))
+                            elif err_type == "rate_limit_exceeded":
+                                events.append(DecoderEvent(kind=DecoderEventKind.VENDOR_ERROR, payload={"normalized_kind": "rate_limited", "evidence_source": "structured_vendor_output"}))
+                            elif err_type == "network_error":
+                                events.append(DecoderEvent(kind=DecoderEventKind.VENDOR_ERROR, payload={"normalized_kind": "network_unavailable", "evidence_source": "structured_vendor_output"}))
+                            elif "auth" in err_type.lower() or "unauthorized" in err_type.lower():
+                                events.append(DecoderEvent(kind=DecoderEventKind.VENDOR_ERROR, payload={"normalized_kind": "auth_unavailable", "evidence_source": "structured_vendor_output"}))
+                    except Exception:
+                        canonical_text = decoded
+                else:
+                    canonical_text = decoded
+        except Exception:
+            # Not valid decoding or other error
+            if not canonical_text:
+                canonical_text = raw_bytes.decode("utf-8", errors="replace")
+
+        if "model_operand_invalid" in canonical_text and not any(e.kind == DecoderEventKind.VENDOR_ERROR for e in events):
+            events.append(DecoderEvent(kind=DecoderEventKind.VENDOR_ERROR, payload={"normalized_kind": "invocation_plan_rejected", "evidence_source": "known_terminal_pattern"}))
+
+        return DecodedOutput(
+            canonical_text=canonical_text,
+            canonical_lines=_split_canonical_lines(canonical_text),
+            events=tuple(events),
+        )
+
+
+class RealAgyAdapter:
+    """Real adapter that shells out to agy.exe."""
+
+    descriptor = _AGY_DESCRIPTOR
+
+    def prompt_policy(self, profile: ProfileDescriptor) -> PromptPolicy:
+        if profile.profile_id != _AGY_PROFILE.profile_id:
+            raise ValueError(f"Unsupported profile {profile.profile_id}")
+        return PromptPolicy(
+            policy_id="ag-standard-policy",
+            max_inline_utf8_bytes=1000000,
+            artifact_reference_supported=False,
+        )
+
+    def plan_invocation(
+        self,
+        request: AdapterRequest,
+        profile: ProfileDescriptor,
+        session: SessionHint | None,
+        limits: TransportLimits,
+    ) -> InvocationPlan:
+
+        if profile.profile_id != _AGY_PROFILE.profile_id:
+            raise ValueError(f"Unsupported profile {profile.profile_id}")
+
+        prompt = request.prompt_content
+        if prompt is None:
+            raise ValueError("prompt_content is required")
+
+        if request.requested_session_action == SessionAction.RESUME:
+            if session is None or session.external_session_id is None:
+                raise ValueError("external_session_id is required for RESUME")
+            argv = ("agy.exe", "-p", prompt, "--output-format", "json", "--conversation", session.external_session_id)
+            redacted_display = "agy.exe -p <redacted> --output-format json --conversation <redacted>"
+        else:
+            argv = ("agy.exe", "-p", prompt, "--output-format", "json")
+            redacted_display = "agy.exe -p <redacted> --output-format json"
+
+        return InvocationPlan(
+            argv=argv,
+            cwd_reference=request.workspace_scope,
+            environment_delta={},
+            transport=TransportKind.PIPE,
+            stdin_payload=None,
+            limits=limits,
+            redacted_display=redacted_display,
+            artifacts=(),
+            session_action=request.requested_session_action,
+        )
+
+    def new_decoder(self, plan: InvocationPlan) -> OutputDecoder:
+        return AgyOutputDecoder()
+
+    def interpret_output(
+        self,
+        plan: InvocationPlan,
+        process: ProcessTerminalEvidence,
+        raw_chunks: Sequence[bytes],
+    ) -> ProtocolAssessment:
+        decoder = self.new_decoder(plan)
+        for chunk in raw_chunks:
+            decoder.feed(chunk, channel=OutputChannel.STDOUT)
+        decoded = decoder.finalize()
+        has_vendor_error = any(e.kind == DecoderEventKind.VENDOR_ERROR for e in decoded.events)
+
+        raw_bytes = b"".join(raw_chunks)
+        try:
+            decoded = raw_bytes.decode("utf-8")
+            start_idx = decoded.find("{")
+            end_idx = decoded.rfind("}")
+            if start_idx != -1 and end_idx != -1 and end_idx >= start_idx:
+                json_str = decoded[start_idx:end_idx + 1]
+                parsed = json.loads(json_str)
+                if "response" in parsed:
+                    return ProtocolAssessment(
+                        parsed=True,
+                        response_present=True,
+                        vendor_completion_marker=None,
+                        suspected_truncation=False,
+                        protocol_failure=None,
+                    )
+                else:
+                    return ProtocolAssessment(
+                        parsed=True,
+                        response_present=False,
+                        vendor_completion_marker=None,
+                        suspected_truncation=False,
+                        protocol_failure=None if has_vendor_error else ErrorCode.INTERNAL_ERROR,
+                    )
+
+            return ProtocolAssessment(
+                parsed=True,
+                response_present=False,
+                vendor_completion_marker=None,
+                suspected_truncation=False,
+                protocol_failure=None if has_vendor_error else ErrorCode.INTERNAL_ERROR,
+            )
+        except Exception:
+            return ProtocolAssessment(
+                parsed=False,
+                response_present=False,
+                vendor_completion_marker=None,
+                suspected_truncation=False,
+                protocol_failure=None if has_vendor_error else ErrorCode.INTERNAL_ERROR,
+            )