graphban-fleet 0.1.0__tar.gz

graphban_fleet-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# Python
+__pycache__/
+*.py[cod]
+backend/.venv/
+backend/*.db
+backend/.pytest.db
+# Bare too: pytest writes it to whatever directory it is invoked from, and a 0.7 MB
+# SQLite file reached main from the repo ROOT, where the backend-scoped line above
+# did not cover it (GRPH-428's branch, merged as #267). It fails
+# `test_no_tracked_control_bytes` on main and therefore on every PR built against it.
+.pytest.db
+.pytest.db-journal
+# The concurrency lock GRPH-554 added sits beside the database it guards, and xdist gives
+# each worker its own — so the pattern has to cover `.pytest_gw3.db.lock` as well as the
+# bare one. Untracked litter in `git status` is how a real change gets missed in the noise.
+*.db.lock
+# Same trap, same fix: scripts/docs_completeness.py opens a throwaway SQLite
+# database in whatever directory it is run from (GRPH-475).
+.docscheck.db
+.docscheck.db-journal
+backend/.pytest_cache/
+# graphban-fleet is a separate distribution with its own venv (PRD-22 D-e). `uv` drops a
+# self-ignoring .gitignore inside .venv/, but naming it here means the repo does not
+# depend on that convenience holding.
+fleet/.venv/
+fleet/.pytest_cache/
+*.egg-info/
+
+# Node
+web/node_modules/
+web/dist/
+web/.vite/
+web/*.tsbuildinfo
+
+# Env
+.env
+.env.local
+
+# Drive sync target (runtime data / mounted volume)
+sync/
+
+# Compose apply helper socket dir (docker-compose default mount)
+.graphban-apply/
+
+# Packed native/GitHub release trees (scripts/graphban_release.py publish)
+dist-release/
+
+# OS / editor
+.DS_Store
+
+# Tooling
+.serena/
+
+# Cursor MCP config — holds a real API key; copy .cursor/mcp.json.example instead
+.cursor/mcp.json
+
+# Project MCP config — holds a real API key
+.mcp.json
+
+# Cursor claim manifest — per-session runtime state (see .cursor/hooks/README.md)
+.cursor/graphban-claim.json
+.cursor/agentledger-claim.json

graphban_fleet-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright 2026 Ascme Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

graphban_fleet-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: graphban-fleet
+Version: 0.1.0
+Summary: Fleet supervisor for Graphban — spawns and retires fleet members on the machine the agents actually run on
+Project-URL: Homepage, https://github.com/asc-me/graphban
+Project-URL: Repository, https://github.com/asc-me/graphban
+Project-URL: Documentation, https://github.com/asc-me/graphban/blob/main/fleet/README.md
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# graphban-fleet
+
+The **fleet supervisor**: a thin local client that runs where the agents actually run.
+It spawns vendor CLI processes holding seats the Graphban *server* issued, and it reaps
+them. Ships as `graphban-fleet`, with a `gbfleet` entry point.
+
+Specified by [PRD-22](https://github.com/asc-me/graphban/blob/main/docs/prd-22-fleet-supervisor.md).
+
+## Two servers, and only one of them has authority
+
+Arbitration is remote and authoritative; process control is local and unprivileged.
+A planner attaches both:
+
+```
+planner (a terminal, or an in-session orchestrator)
+ ├─ graphban   (remote HTTP)  → mint_enrolment, propose_allocation, assign_role, fleet_status
+ └─ gbfleet    (local stdio)  → spawn, stop, ps, orphans
+```
+
+`gbfleet` runs on the developer's machine and the Graphban server never learns its calls
+happened. There are **no HTTP routes on the local surface**. Authentication there is
+process ownership — the planner speaks over a pipe to a child it launched — not a
+credential.
+
+**The supervisor holds no authority of its own.** It can only launch a process holding a
+seat the server issued, to do work the server arbitrates. Delete it and every invariant
+still holds; the fleet just needs a human to open terminals again. It is explicitly
+**not a security boundary** (PRD-22 D-k): a compromised vendor binary has whatever the
+user has, and the worktree is a blast-radius convention, not a sandbox.
+
+## Why it is in this repository, and not inside `backend/`
+
+**Not a second repository,** because the client↔server contract has no schema anywhere —
+the enrolment code format and its TTL, `register_agent`'s return shape, `independent()`'s
+seat semantics, the directive envelope. All of it is changeable in a single PR here, and
+a cross-repo break would present as absence reading clean: the fleet still spawns,
+nothing errors, review stops being independent.
+
+**Not inside `backend/`,** because `graphban-api` pulls fastapi, sqlalchemy, pgvector,
+psycopg, alembic, redis and cryptography, and a laptop running four vendor CLIs needs
+none of them. `tests/test_packaging.py` derives its forbidden-dependency set from the
+backend's own list, so that separation is checked rather than asserted.
+
+## Licence — Apache-2.0, deliberately not the repository's FSL-1.1
+
+The repository is [FSL-1.1-Apache-2.0](https://github.com/asc-me/graphban/blob/main/LICENSE.md). This directory is
+[Apache-2.0](https://github.com/asc-me/graphban/blob/main/fleet/LICENSE), and the divergence is a decision (PRD-22 §8), not an oversight:
+
+- **The supervisor is not the moat.** It is inert without a Graphban server and holds no
+  authority. FSL's Competing Use clause protects the server; it protects nothing here.
+- **Adapters are the contribution this component most wants**, and they come from people
+  who use other vendors' tools. A non-OSI licence is friction aimed at exactly that
+  audience.
+- **It is a laptop-installed developer CLI**, which is precisely the kind of dependency
+  that meets a corporate licence policy scanner.
+- FSL-1.1-**Apache-2.0** already commits to Apache-2.0 on a two-year delay. This brings
+  that grant forward for the one component least worth protecting.
+
+If this component is ever extracted to its own repository — the stated trigger is outside
+contributors who should not hold commit access to the server — extract **the adapter
+interface only**, not the supervisor.
+
+## Install
+
+Not on PyPI yet, so it installs from the repository:
+
+```bash
+uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=fleet"
+```
+
+That gives you `gbfleet` and `gbagent`. `uv tool update-shell` once if uv says its bin
+directory is not on your PATH, and `uv tool upgrade graphban-fleet` to move it forward — the
+spec tracks a branch, so an upgrade is not automatic and a fix landing here does not reach a
+machine until somebody asks for it.
+
+[`gban`](https://github.com/asc-me/graphban/blob/main/cli/README.md), the client for a human at a terminal, is a separate package —
+`#subdirectory=cli` — because it installs on laptops that never run a wave and must stay
+dependency-free.
+
+## Running it
+
+One wave, deterministically — you mint the seats, it spawns and reaps:
+
+```bash
+GBFLEET_API_KEY=... gbfleet up \
+    --server https://cloud.agentldgr.dev --seats-file seats.txt --adapter claude
+```
+
+A seats file is one enrolment code per line. A line may also bind the seat to an item
+(`WORKER-7F3K item=GRPH-755` — the child gets the BOUND instruction and claims that item
+at registration, PRD-36) or name its role (`REVIEWER-2Q9C role=reviewer` — the child gets
+the reviewer instruction). Both are what `until` says when it mints a seat itself; here
+you say them. A mistyped token refuses the whole file before any worktree is cut, and
+`doctor --seats-file` refuses it the same way.
+
+Or hand the local surface to a planner over stdio:
+
+```bash
+GBFLEET_API_KEY=... gbfleet mcp --server https://cloud.agentldgr.dev
+```
+
+`spawn` starts **one** child and takes no count. The planner decides how many to run —
+it holds both servers, so it can read `collision_clusters` and `get_backlog` itself, mint
+that many seats, and call `spawn` once each. The supervisor executes.
+
+**Delegate to a seat (PRD-36).** A parent that wants one item built on a cheaper model
+does it in two calls and keeps working: `delegate(id, lane, tier, seat=true)` on the
+Graphban server mints a worker seat *bound* to the item and returns its code; then
+`spawn(enrolment_code=<code>, tier="cheap", item=<id>)` here. Registering on a bound seat
+claims the item server-side, so the child holds it from its first call and never touches
+`claim_cluster`; the spawn reply echoes the roster's `assigned` block (`claimed`, or
+`taken` with who holds it). `tier` resolves through a table the operator names at launch —
+`gbfleet mcp --tier cheap=gbagent:qwen3.6:35b-a3b-coding-mtp-det --tier
+frontier=claude:opus` — fixed for the life of the process, and an explicit `adapter`
+overrides it. `gbfleet until` takes the same `--tier` table plus `--request cheap|frontier`
+for what its own delegations ask, and mints bound seats for the seeds it delegates, so the
+divvy no longer decides what its children claim. The outcome comes back through the ledger
+— the item moving on the board — never as a reply in the parent's context.
+
+**The preference matrix (PRD-37).** A tier with no `--tier` flag resolves through
+`src/gbfleet/matrix.toml`, a committed table of harness × model × lane × role × tier rows
+with a status (`verified`, `unverified`, `failed`, `unregistered`) and the item that proved
+it — facts only, reviewed like code. Resolution runs in a fixed order: the rows for the
+tier and role → the project's policy (`local_only`, `allowed_harnesses`,
+`reviewer_cross_vendor`) → the user's profile (an ordered allowlist of harnesses, weights
+over `cost`/`quality`/`latency`/`locality`, excludes) → `failed` rows out → what this
+machine has installed → score → ties (verified first, then the user's own order, then the
+row's `order`). Profile and policy come from the server: `gbfleet mcp` and `gbfleet until`
+read them off `fleet_status` **once at launch** (a change is read at the next launch, PRD-36
+D16) — the profile is the API key owner's, with a per-project override, edited in the Fleet
+view under the Wave tab; the policy is the project's. A key whose owner has no profile, or a
+server that cannot be reached at launch, resolves on matrix order and policy alone and the
+explanation says `profile: none`. A reviewer spawn may pass `builder_vendor` so a project's
+`reviewer_cross_vendor` rule can drop the builder's vendor. Every spawned child is told, in the same sentence
+as its enrolment code, to register with `capabilities={vendor, model?, tier}` for what the
+supervisor actually launched (GRPH-732), so the ledger can attribute its outcome; only a NAMED
+model is declared, since a vendor default is unknowable from here. Measured `quality` and `latency`
+also ride on `fleet_status` (per declared vendor × model × lane × tier, with `n`); the resolver
+reads the cell for the lane being resolved, never a pooled one, and counts an axis only past
+`n ≥ 5`. The spawn reply carries `resolution`: `source` (`flag`
+or `matrix`), how many rows survived each step, what each step dropped and why, the winner
+with its per-axis numbers, and the runner-up. An empty resolution is a tool error naming
+the step that emptied it — there is no silent default. Measured axes need `n ≥ 5` before
+they count and say `unmeasured` until then. `--matrix PATH` on `mcp`, `until` and `doctor`
+swaps the file; `gbfleet doctor` prints every row against this machine and what each
+role/tier would resolve to. The file is TOML, not the YAML the PRD first wrote, because
+gbfleet is httpx-thin by requirement and `tomllib` is standard library.
+
+**Name the project.** A credential that spans several projects resolves a call that names
+none to its *default* project, and that is not where the seats were minted: the child
+registers on the seat's project (the server takes it from the seat), but the supervisor's
+roster read and the child's own reads land elsewhere — the child never appears on the
+roster the supervisor polls and reads a backlog that is not its own. `gbfleet mcp`,
+`gbfleet until` and `gbfleet doctor` take `--project <id>`, named on every call; `doctor`
+fails a multi-project key that gives none. The child learns its project from the
+registration reply and names it afterwards (GRPH-718, GRPH-719).
+
+**What a wave reports about itself.** Beyond spawn and reap, `up` and `until` print three
+findings a reviewer otherwise has no way to see, all measured from the worktrees the
+supervisor already owns and none of them acted on:
+
+- `COLLIDED <path>: changed on <branch>, <branch>` — two workers changed the same file. The
+  failure the partition exists to prevent, observed rather than predicted: exact paths, no
+  coverage rule, and true whether the touchpoints were wrong or the divvy was.
+- `UNDECLARED <branch>: changed N file(s) no touchpoint covers` — the partition's INPUT was
+  wrong. Compared against the declaration as it stood when work was handed out, which is the
+  snapshot the divvy used. An item that declared nothing is not drift; its areas were
+  predicted, which the board already marks.
+- `BEHIND <branch>: cut from a base N commit(s) behind origin/main` — how much landed on the
+  trunk while the child worked. Two agents can each be green on their own base and conflict
+  on merge, and nothing else in the system can see it: the server has no git, the reviewer
+  gets a branch with no indication of what its diff is against, and the child was cut from
+  HEAD at spawn and never looked again. The trunk is fetched once per wave before measuring —
+  a remote-tracking ref is only as fresh as its last fetch, and a check that skipped it would
+  report every branch as current. `BEHIND unmeasured: <reason>` when it could not be asked,
+  because that is not the same as nothing having moved.
+
+Vendors and what each of them needs: [`docs/fleet-adapters.md`](https://github.com/asc-me/graphban/blob/main/docs/fleet-adapters.md).
+
+## Development
+
+```bash
+cd fleet
+uv venv --python 3.12 .venv
+uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+```
+
+The suite fails loudly if the package is not installed, rather than testing an
+uninstalled fallback and passing.

graphban_fleet-0.1.0/README.md

@@ -0,0 +1,190 @@
+# graphban-fleet
+
+The **fleet supervisor**: a thin local client that runs where the agents actually run.
+It spawns vendor CLI processes holding seats the Graphban *server* issued, and it reaps
+them. Ships as `graphban-fleet`, with a `gbfleet` entry point.
+
+Specified by [PRD-22](https://github.com/asc-me/graphban/blob/main/docs/prd-22-fleet-supervisor.md).
+
+## Two servers, and only one of them has authority
+
+Arbitration is remote and authoritative; process control is local and unprivileged.
+A planner attaches both:
+
+```
+planner (a terminal, or an in-session orchestrator)
+ ├─ graphban   (remote HTTP)  → mint_enrolment, propose_allocation, assign_role, fleet_status
+ └─ gbfleet    (local stdio)  → spawn, stop, ps, orphans
+```
+
+`gbfleet` runs on the developer's machine and the Graphban server never learns its calls
+happened. There are **no HTTP routes on the local surface**. Authentication there is
+process ownership — the planner speaks over a pipe to a child it launched — not a
+credential.
+
+**The supervisor holds no authority of its own.** It can only launch a process holding a
+seat the server issued, to do work the server arbitrates. Delete it and every invariant
+still holds; the fleet just needs a human to open terminals again. It is explicitly
+**not a security boundary** (PRD-22 D-k): a compromised vendor binary has whatever the
+user has, and the worktree is a blast-radius convention, not a sandbox.
+
+## Why it is in this repository, and not inside `backend/`
+
+**Not a second repository,** because the client↔server contract has no schema anywhere —
+the enrolment code format and its TTL, `register_agent`'s return shape, `independent()`'s
+seat semantics, the directive envelope. All of it is changeable in a single PR here, and
+a cross-repo break would present as absence reading clean: the fleet still spawns,
+nothing errors, review stops being independent.
+
+**Not inside `backend/`,** because `graphban-api` pulls fastapi, sqlalchemy, pgvector,
+psycopg, alembic, redis and cryptography, and a laptop running four vendor CLIs needs
+none of them. `tests/test_packaging.py` derives its forbidden-dependency set from the
+backend's own list, so that separation is checked rather than asserted.
+
+## Licence — Apache-2.0, deliberately not the repository's FSL-1.1
+
+The repository is [FSL-1.1-Apache-2.0](https://github.com/asc-me/graphban/blob/main/LICENSE.md). This directory is
+[Apache-2.0](https://github.com/asc-me/graphban/blob/main/fleet/LICENSE), and the divergence is a decision (PRD-22 §8), not an oversight:
+
+- **The supervisor is not the moat.** It is inert without a Graphban server and holds no
+  authority. FSL's Competing Use clause protects the server; it protects nothing here.
+- **Adapters are the contribution this component most wants**, and they come from people
+  who use other vendors' tools. A non-OSI licence is friction aimed at exactly that
+  audience.
+- **It is a laptop-installed developer CLI**, which is precisely the kind of dependency
+  that meets a corporate licence policy scanner.
+- FSL-1.1-**Apache-2.0** already commits to Apache-2.0 on a two-year delay. This brings
+  that grant forward for the one component least worth protecting.
+
+If this component is ever extracted to its own repository — the stated trigger is outside
+contributors who should not hold commit access to the server — extract **the adapter
+interface only**, not the supervisor.
+
+## Install
+
+Not on PyPI yet, so it installs from the repository:
+
+```bash
+uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=fleet"
+```
+
+That gives you `gbfleet` and `gbagent`. `uv tool update-shell` once if uv says its bin
+directory is not on your PATH, and `uv tool upgrade graphban-fleet` to move it forward — the
+spec tracks a branch, so an upgrade is not automatic and a fix landing here does not reach a
+machine until somebody asks for it.
+
+[`gban`](https://github.com/asc-me/graphban/blob/main/cli/README.md), the client for a human at a terminal, is a separate package —
+`#subdirectory=cli` — because it installs on laptops that never run a wave and must stay
+dependency-free.
+
+## Running it
+
+One wave, deterministically — you mint the seats, it spawns and reaps:
+
+```bash
+GBFLEET_API_KEY=... gbfleet up \
+    --server https://cloud.agentldgr.dev --seats-file seats.txt --adapter claude
+```
+
+A seats file is one enrolment code per line. A line may also bind the seat to an item
+(`WORKER-7F3K item=GRPH-755` — the child gets the BOUND instruction and claims that item
+at registration, PRD-36) or name its role (`REVIEWER-2Q9C role=reviewer` — the child gets
+the reviewer instruction). Both are what `until` says when it mints a seat itself; here
+you say them. A mistyped token refuses the whole file before any worktree is cut, and
+`doctor --seats-file` refuses it the same way.
+
+Or hand the local surface to a planner over stdio:
+
+```bash
+GBFLEET_API_KEY=... gbfleet mcp --server https://cloud.agentldgr.dev
+```
+
+`spawn` starts **one** child and takes no count. The planner decides how many to run —
+it holds both servers, so it can read `collision_clusters` and `get_backlog` itself, mint
+that many seats, and call `spawn` once each. The supervisor executes.
+
+**Delegate to a seat (PRD-36).** A parent that wants one item built on a cheaper model
+does it in two calls and keeps working: `delegate(id, lane, tier, seat=true)` on the
+Graphban server mints a worker seat *bound* to the item and returns its code; then
+`spawn(enrolment_code=<code>, tier="cheap", item=<id>)` here. Registering on a bound seat
+claims the item server-side, so the child holds it from its first call and never touches
+`claim_cluster`; the spawn reply echoes the roster's `assigned` block (`claimed`, or
+`taken` with who holds it). `tier` resolves through a table the operator names at launch —
+`gbfleet mcp --tier cheap=gbagent:qwen3.6:35b-a3b-coding-mtp-det --tier
+frontier=claude:opus` — fixed for the life of the process, and an explicit `adapter`
+overrides it. `gbfleet until` takes the same `--tier` table plus `--request cheap|frontier`
+for what its own delegations ask, and mints bound seats for the seeds it delegates, so the
+divvy no longer decides what its children claim. The outcome comes back through the ledger
+— the item moving on the board — never as a reply in the parent's context.
+
+**The preference matrix (PRD-37).** A tier with no `--tier` flag resolves through
+`src/gbfleet/matrix.toml`, a committed table of harness × model × lane × role × tier rows
+with a status (`verified`, `unverified`, `failed`, `unregistered`) and the item that proved
+it — facts only, reviewed like code. Resolution runs in a fixed order: the rows for the
+tier and role → the project's policy (`local_only`, `allowed_harnesses`,
+`reviewer_cross_vendor`) → the user's profile (an ordered allowlist of harnesses, weights
+over `cost`/`quality`/`latency`/`locality`, excludes) → `failed` rows out → what this
+machine has installed → score → ties (verified first, then the user's own order, then the
+row's `order`). Profile and policy come from the server: `gbfleet mcp` and `gbfleet until`
+read them off `fleet_status` **once at launch** (a change is read at the next launch, PRD-36
+D16) — the profile is the API key owner's, with a per-project override, edited in the Fleet
+view under the Wave tab; the policy is the project's. A key whose owner has no profile, or a
+server that cannot be reached at launch, resolves on matrix order and policy alone and the
+explanation says `profile: none`. A reviewer spawn may pass `builder_vendor` so a project's
+`reviewer_cross_vendor` rule can drop the builder's vendor. Every spawned child is told, in the same sentence
+as its enrolment code, to register with `capabilities={vendor, model?, tier}` for what the
+supervisor actually launched (GRPH-732), so the ledger can attribute its outcome; only a NAMED
+model is declared, since a vendor default is unknowable from here. Measured `quality` and `latency`
+also ride on `fleet_status` (per declared vendor × model × lane × tier, with `n`); the resolver
+reads the cell for the lane being resolved, never a pooled one, and counts an axis only past
+`n ≥ 5`. The spawn reply carries `resolution`: `source` (`flag`
+or `matrix`), how many rows survived each step, what each step dropped and why, the winner
+with its per-axis numbers, and the runner-up. An empty resolution is a tool error naming
+the step that emptied it — there is no silent default. Measured axes need `n ≥ 5` before
+they count and say `unmeasured` until then. `--matrix PATH` on `mcp`, `until` and `doctor`
+swaps the file; `gbfleet doctor` prints every row against this machine and what each
+role/tier would resolve to. The file is TOML, not the YAML the PRD first wrote, because
+gbfleet is httpx-thin by requirement and `tomllib` is standard library.
+
+**Name the project.** A credential that spans several projects resolves a call that names
+none to its *default* project, and that is not where the seats were minted: the child
+registers on the seat's project (the server takes it from the seat), but the supervisor's
+roster read and the child's own reads land elsewhere — the child never appears on the
+roster the supervisor polls and reads a backlog that is not its own. `gbfleet mcp`,
+`gbfleet until` and `gbfleet doctor` take `--project <id>`, named on every call; `doctor`
+fails a multi-project key that gives none. The child learns its project from the
+registration reply and names it afterwards (GRPH-718, GRPH-719).
+
+**What a wave reports about itself.** Beyond spawn and reap, `up` and `until` print three
+findings a reviewer otherwise has no way to see, all measured from the worktrees the
+supervisor already owns and none of them acted on:
+
+- `COLLIDED <path>: changed on <branch>, <branch>` — two workers changed the same file. The
+  failure the partition exists to prevent, observed rather than predicted: exact paths, no
+  coverage rule, and true whether the touchpoints were wrong or the divvy was.
+- `UNDECLARED <branch>: changed N file(s) no touchpoint covers` — the partition's INPUT was
+  wrong. Compared against the declaration as it stood when work was handed out, which is the
+  snapshot the divvy used. An item that declared nothing is not drift; its areas were
+  predicted, which the board already marks.
+- `BEHIND <branch>: cut from a base N commit(s) behind origin/main` — how much landed on the
+  trunk while the child worked. Two agents can each be green on their own base and conflict
+  on merge, and nothing else in the system can see it: the server has no git, the reviewer
+  gets a branch with no indication of what its diff is against, and the child was cut from
+  HEAD at spawn and never looked again. The trunk is fetched once per wave before measuring —
+  a remote-tracking ref is only as fresh as its last fetch, and a check that skipped it would
+  report every branch as current. `BEHIND unmeasured: <reason>` when it could not be asked,
+  because that is not the same as nothing having moved.
+
+Vendors and what each of them needs: [`docs/fleet-adapters.md`](https://github.com/asc-me/graphban/blob/main/docs/fleet-adapters.md).
+
+## Development
+
+```bash
+cd fleet
+uv venv --python 3.12 .venv
+uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+```
+
+The suite fails loudly if the package is not installed, rather than testing an
+uninstalled fallback and passing.