Draft: PlugBrain 0.5.0-dev.1 integration candidate

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "PlugBrain — local project and code memory for AI agents",
-    "version": "0.3.1"
+    "version": "0.5.0-dev.1"
   },
   "plugins": [
     {
       "name": "plugbrain",
       "source": "./",
       "description": "Ask the brain first: AST code intelligence, Obsidian-style notes and agent coordination for this repository, served locally over MCP.",
-      "version": "0.3.1",
+      "version": "0.5.0-dev.1",
       "license": "MIT",
       "category": "productivity",
       "keywords": [

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "plugbrain",
-  "version": "0.3.1",
+  "version": "0.5.0-dev.1",
   "description": "Local project and code memory for AI agents: AST code intelligence, Obsidian-style notes and multi-agent coordination, asked through MCP.",
   "author": {
     "name": "litbitrim"

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to PlugBrain are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/) and the
 project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.5.0-dev.1] — 2026-09-30 (development candidate)
+
+This branch carries the local PlugBrain 0.5 source candidate onto the public
+repository history for review and cross-platform verification. It is not an
+installed or published release. See `release/RELEASE-NOTES-v0.5.0-dev.1.md`
+for the included work and the open acceptance gates.
+
 ## [0.3.1] — 2026-09-26
 
 The `v0.3.0` tag exists, but no 0.3.0 release was published: its cross-platform

README.md

@@ -56,7 +56,7 @@ plugbrain swarm release codex-1 --task <task-id>
 # The integrator looks, approves, and sends the next hint
 plugbrain swarm board --git
 plugbrain swarm approve codex-1 --note "Reviewed. Commit it."
-plugbrain swarm send codex-1 --subject "Next" --body "Rebase on main after your commit"
+plugbrain swarm send codex-1 --subject "Next" --body "Rebase on main after your commit" --from integrator
 ```
 
 A turn ends in one of four states: `needs-task` (done, give me work),
@@ -127,7 +127,9 @@ plugbrain serve    # the local daemon: web UI and API on http://127.0.0.1:4310
 `plugbrain setup --all` (or `claude`, `codex`, `cursor`, `windsurf`, `hermes`,
 `agy`, `opencode`) adds PlugBrain to an MCP client later. It backs up the
 client's config first; `--undo` restores it. The data directory defaults to
-`~/.plugbrain`; set `PLUGBRAIN_HOME` to choose another one.
+`~/.plugbrain`; set `PLUGBRAIN_HOME` to choose another one. One page per client,
+with the file it writes, how to check it took effect and how to remove it again:
+[docs/agents/](docs/agents/).
 
 ### Claude Code plugin
 

bench/m18-gold-30-draft.md

@@ -0,0 +1,68 @@
+# M18: 30 Goldfragen, Entwurf vom 30.09.2026
+
+**Status: Messplan, kein Paritätsnachweis.** Dieser Korpus ersetzt für die nächste
+Messung die alte `goldfragen.json`-Auswahl mit 28 Brain- und zwei PlugEngine-Fällen.
+Jede Frage muss mit der rohen Antwort von Brain und GitNexus gegen denselben
+Quellstand bewertet werden. Ein `found`-Status allein ist keine richtige Antwort.
+
+## Eingefrorene Kandidaten vor Messbeginn
+
+| Kürzel | Checkout | beobachteter Commit |
+| --- | --- | --- |
+| H | `Code/PlugHarness--int-orch` | `9f90dcf` |
+| B | `Code/PlugBoard--dag` | `9165be2` |
+| S | `Code/PlugPT-Shell--suite` | `7cd326b` |
+
+Die drei Commits sind Vorschläge für die Messung. Vor dem Lauf müssen Branch,
+HEAD, Dirty-Vektor, Brain-Auswahl und GitNexus-Index für **denselben** Stand
+nachgewiesen werden. Die `changes`-Fragen verwenden eingefrorene synthetische
+Diffs; sie ändern keine dieser Checkouts.
+
+## Fragen und Quell-Oracle
+
+Pfade sind relativ zum jeweiligen Checkout. Zeilen und Bezeichner sind ein
+Startpunkt für das Oracle und werden beim Einfrieren des Korpus erneut geprüft.
+
+| ID | Art | Frage und Anker | Zu bewerten |
+| --- | --- | --- | --- |
+| H01 | query | Wo wird HTTP-Inferenz-Dispatch erzeugt? `packages/plug/gateway/src/server.ts:95#createPlugGateway` | Exakte Definition statt namensähnlicher Operator-Funktion. |
+| H02 | context | Welche Prüfungen und Admission-Writes gehören zu `packages/plug/gateway/src/governor.ts:121#Governor.admit`? | Ledger, harte Limits, Parallelität und Cooldown nur soweit quellenbelegt. |
+| H03 | impact | Wer hängt von `packages/plug/gateway/src/route-registry.ts:314#materializeRoutes` ab? | Operator-Nutzung um `server.ts:377,390`; Tests getrennt ausweisen. |
+| H04 | changes | Hunk in `packages/plug/operator/src/native-admission.ts:62#admitNativeDeployment`. | Exaktes Symbol und Checkout; keine fremden Checkouts. |
+| H05 | Cypher | Finde `packages/plug/operator/src/brain-core.ts:123#callBrainCore`. | Scoped Function-Identität und gegen AST geprüfte Anzahl. |
+| H06 | query | Wer wählt die installierte Brain-Bindung? `packages/plug/operator/src/brain-core.ts:86#resolvePlugBrainCoreBinding` | Definition von `ensureBrainCore` unterscheiden. |
+| H07 | context | Was ruft `packages/plug/operator/src/brain-core.ts:194#ensureBrainCore` auf, und wer ruft es? | `brainCoreIsHealthy`, `brainCoreServiceSpec`, Operator-Server um Zeile 1091. |
+| H08 | impact | Wer ruft `packages/plug/gateway/src/ledger.ts:365#RequestLedger.reserveTokens`? | Konkreter Aufruf in `gateway/src/budgets.ts:137`, keine Modul-Import-Inflation. |
+| H09 | query | Wo ist Board-Agent-Spawn implementiert? `packages/plug/operator/src/board-agent-spawn.ts:202#spawnBoardResourceAgents` | Exakte Quelle statt generischer Spawn-Helfer. |
+| H10 | context | Was prüft `packages/plug/gateway/src/route-registry.ts:768#acquireRouteForAgent`? | `resolveBoundRoute` und belegte Zweige; keine erfundenen Runtime-Caller. |
+| B01 | query | Wo liest Board Planet/Galaxy? `src/main/brain/register.ts:145#readGalaxy` | Main-Prozess-Definition statt Renderer-Treffer. |
+| B02 | context | Wie registriert und indiziert `src/main/brain/register.ts:187#ensureWorkspace`? | `/api/workspaces`, `/api/reindex`, Handler um Zeile 349, Fehlerpfad. |
+| B03 | impact | Welcher Startpfad nutzt `src/main/agents/register.ts:84#registerAgentLaneHandlers`? | `src/main/index.ts:281`; Tests von Runtime trennen. |
+| B04 | changes | Hunk in `src/renderer/shell/spawn.ts:152#spawnTerminal`. | Symbol, Zeile, Revision und Checkout exakt zuordnen. |
+| B05 | Cypher | Finde `src/renderer/fleet/FleetSurface.tsx:31#FleetSurface`. | Scoped Function/Komponente; Anzahl unabhängig aus AST prüfen. |
+| B06 | query | Wo ist das Brain-Workspace-Panel? `src/renderer/brain/BrainWorkspacePanel.tsx:54#BrainWorkspacePanel` | Exakte Komponente und Checkout. |
+| B07 | context | Was ruft `src/main/agents/harness-operator-client.ts:529#HarnessOperatorClient.sessionSend`? | `/v1/session/send` und belegter Registry-Consumer. |
+| B08 | impact | Wer ruft `src/renderer/terminal/launch.ts:167#startFreebuffInSession`? | Swarm um Zeile 201 und AgentSurface um 606/612; keine anderen Launches. |
+| B09 | query | Wo wird City/Mesh gerendert? `src/renderer/brain/CityMeshPanel.tsx:41#CityMeshPanel` | Panel von Core-Projektion unterscheiden. |
+| B10 | context | Welchen Endpunkt benutzt `src/main/brain/register.ts:267#attachAgent`? | `/api/agent/attach`, Handler um Zeile 352, Fehler nicht als Erfolg melden. |
+| S01 | query | Wo werden Desktop-HostBridge-Operationen gemappt? `apps/desktop/electron/plug-host-bridge.ts:126#routePlugHostBridgeInvocation` | Exakte Map, keine erfundene freie Fetch-Route. |
+| S02 | context | Was ruft `apps/desktop/electron/plug-host-bridge.ts:225#createPlugHostBridgeMainClient`? | Mapper um Zeile 357, Identität und Transport; keine Secrets. |
+| S03 | impact | Wer registriert `apps/desktop/electron/plug-host-bridge.ts:392#registerPlugHostBridgeIpc`? | `apps/desktop/electron/main.ts:386`; Tests getrennt. |
+| S04 | changes | Hunk in `apps/desktop/electron/plug-host-bridge.ts:409#isTrustedPlugDeskRendererUrl`. | Trust-Funktion im richtigen Checkout. |
+| S05 | Cypher | Finde `hermes_cli/commands.py:414#resolve_command`. | Python-Definition und AST-Anzahl; Parser-Lücke ehrlich melden. |
+| S06 | query | Wo startet PlugDesk-Rendering? `apps/desktop/src/plugdesk/plugdesk-root.tsx:1251#PlugDeskBootstrap` | Definition und Referenzen in `apps/desktop/src/main.tsx`. |
+| S07 | context | Wer nutzt `hermes_cli/commands.py:619#gateway_help_lines`? | Direkte Aufrufe in `hermes_cli/slash_exec.py:165,204`. |
+| S08 | impact | Welche Caller hängen von `agent/skill_commands.py:655#get_skill_commands` ab? | Belegte CLI- und Slash-Exec-Caller; Dynamik als unaufgelöst. |
+| S09 | context | Wo wird `hermes_cli/auth.py:205#normalize_actual_base_url` genutzt? | Referenzen in auth, runtime_provider und auxiliary_client; keine Credential-Inhalte. |
+| S10 | query | Wo wird `/skill`-Payload gebaut? `agent/skill_commands.py:766#build_skill_invocation_message` | Exakte Definition statt Helper um Zeile 862. |
+
+## Messregel
+
+Für jeden Fall: Frage, eingefrorener Quellanker, erwartete konkrete Antwort,
+Brain- und GitNexus-Rohantwort, richtige/falsche/unaufgelöste Behauptungen,
+Latenz und Index-Revision speichern. Precision und Recall auf derselben
+bewerteten Faktenmenge rechnen. Zusätzlich die kritischen Identitäts-,
+Revisions- und Restorefälle des Masters prüfen. M18 bleibt offen, bis die
+30 Fragen mit beiden Werkzeugen auf derselben Revision ausgeführt sind,
+Brain mindestens so viele korrekt beantwortet, Precision **und** Recall
+jeweils mindestens 95 % betragen und p95 höchstens 2 s ist.

desktop/PlugBrain.nsi

@@ -1,7 +1,9 @@
 Unicode true
 
 !define PRODUCT_NAME "PlugBrain"
-!define PRODUCT_VERSION "0.3.1"
+!ifndef PRODUCT_VERSION
+  !error "PRODUCT_VERSION must be supplied by the packager"
+!endif
 !define PRODUCT_PUBLISHER "PLUG"
 
 Name "${PRODUCT_NAME} ${PRODUCT_VERSION}"

docs/agent-protocol.md

@@ -6,18 +6,28 @@ agent follows on every turn. Paste the block below into your project's
 (Claude Code), and give every agent its own id.
 
 Commands are the `plugbrain swarm` CLI, so any agent that can run a shell
-command can take part. See [cli.md](cli.md#swarm) for every option.
+command can take part. See [cli.md](cli.md#swarm) for every option, and
+[agents/](agents/README.md) for teaching a client to reach PlugBrain in the
+first place.
 
 ## Before the first turn
 
 Register each agent once. The account label tells the board which quota the
-agent spends; one key or subscription can carry several agents.
+agent spends. Set `--quota-pool` to the provider project/account limit shared by
+its agents; different keys in that project must use the same pool name.
 
 ```bash
 plugbrain swarm register codex-1 --surface other --account openai --model gpt-6-luna
 plugbrain swarm register claude-1 --surface claude-code --account anthropic
+plugbrain swarm register nv01 --surface freebuff --account nvidia:key-01 --key nvidia-01 --quota-pool nvidia:project-a
+plugbrain swarm register nv02 --surface freebuff --account nvidia:key-02 --key nvidia-02 --quota-pool nvidia:project-a
 ```
 
+Configure the shared pool once with `plugbrain swarm quota-pool set nvidia:project-a
+--max-concurrent 2 --rpm 30`. Supervised runs reserve an attempt atomically and
+settle it after the worker exits. Provider-reported usage is only recorded when
+available; missing usage stays unknown.
+
 Surfaces are `claude-code`, `codex-app`, `freebuff`, `agy`, `native` and `other`.
 
 ## Block for AGENTS.md / CLAUDE.md
@@ -34,21 +44,29 @@ You are one agent in a team coordinated by PlugBrain. Your agent id is `<id>`.
 2. **Before you write:** claim the paths you will change:
    `plugbrain swarm claim <id> <path>... --task <taskId>`. If the claim is
    refused, another agent owns the path. Message that agent
-   (`plugbrain swarm send <agent> --subject "..." --body "..."`) instead of
-   writing anyway.
+   (`plugbrain swarm send <agent> --subject "..." --body "..." --from <your id>`) instead of
+   writing anyway. Set `PLUGBRAIN_AGENT=<your id>` once in your shell and every
+   message is signed with your id; a message without a sender is refused.
 3. **Before tests, builds, installs or new worktrees:** run
    `plugbrain swarm admit test|build|install|worktree`. Exit code 5 means the
    machine has no room. Do not start the work; end the turn as `blocked`.
-4. **End of every turn,** with exactly one state:
+4. **Hand in completed work:** run
+   `plugbrain swarm deliver <id> <taskId> --path <evidence> [--repo <worktree>]`.
+   The evidence must be a non-empty file inside the workspace. The receipt stores
+   its SHA-256, your agent id, attempt, and source revision when available. Review
+   tasks (title starts with `R-` or `--review`) also need a verdict and reviewed commit hash.
+5. **End of every turn,** with exactly one state:
    `plugbrain swarm turn <id> end --state <state> --summary "<one or two sentences>"`
    - `needs-task`: you are done and need new work
    - `awaiting-commit`: a tested change is ready; wait for approval
    - `blocked`: a real blocker, named in the summary
    - `paused`: you were told to stop
    Then release your claims: `plugbrain swarm release <id> --task <taskId>`.
-5. **Commit only after approval.** Approval arrives as a message with the
+   Ending with `needs-task` without a delivery leaves the task claimed and visible
+   under `plugbrain swarm board --next`.
+6. **Commit only after approval.** Approval arrives as a message with the
    subject "Commit freigegeben". Commit, then end the turn with `needs-task`.
-6. **Report limits, never secrets.** If your tool shows a quota, report the
+7. **Report limits, never secrets.** If your tool shows a quota, report the
    number: `plugbrain swarm quota <account> <remaining> percent|credits|requests|rpm|tokens`.
    Never put keys or tokens into commands, summaries, messages or notes.
 ```
@@ -61,8 +79,10 @@ role.
 | Task | Command |
 | --- | --- |
 | See every agent, its turn, task, claims and worktree | `plugbrain swarm board --git` |
-| Queue work, optionally for one agent | `plugbrain swarm enqueue "<title>" --body "<brief>" [--to <id>]` |
-| Send a message | `plugbrain swarm send <id> --subject "<s>" --body "<b>"` |
+| Queue work, optionally for one agent, optionally after another task | `plugbrain swarm enqueue "<title>" --body "<brief>" [--to <id>] [--after <taskId>]` |
+| Send a message | `plugbrain swarm send <id> --subject "<s>" --body "<b>" --from integrator` |
+| See who is still, and release arrivals | `plugbrain swarm watchdog` |
+| Reviewer list and automatic review routing | `plugbrain swarm review-pool set <id>... && plugbrain swarm review-pool auto on` |
 | Let an agent commit | `plugbrain swarm approve <id> [--note "<n>"]` |
 | Machine room and quotas | `plugbrain swarm resources` |
 | Take an agent off the board | `plugbrain swarm retire <id> --note "<reason>"` |

docs/agents/README.md

@@ -0,0 +1,68 @@
+# Agent setup
+
+One page per client: what it needs, the one command that configures it, what
+lands in which file, how to check that it worked, and how to take it back out.
+
+| Client | Page | Config file (under your home) | Format, map key |
+| --- | --- | --- | --- |
+| Claude Code | [claude-code.md](claude-code.md) | `.claude.json` | JSON, `mcpServers` |
+| Codex | [codex.md](codex.md) | `.codex/config.toml` | TOML, `mcp_servers` |
+| Cursor | [cursor.md](cursor.md) | `.cursor/mcp.json` | JSON, `mcpServers` |
+| Windsurf | [windsurf.md](windsurf.md) | `.codeium/windsurf/mcp_config.json` | JSON, `mcpServers` |
+| OpenCode | [opencode.md](opencode.md) | `.config/opencode/opencode.json` | JSON, `mcp` |
+| Hermes | [hermes.md](hermes.md) | `.hermes/config.yaml` | YAML, `mcp_servers` |
+| AGY | [agy.md](agy.md) | `.gemini/antigravity/mcp_config.json` | JSON, `mcpServers` |
+
+The seven ids, paths, formats and map keys are `CLIENTS` in
+[`src/setup/clients.ts`](../../src/setup/clients.ts).
+
+## What every setup does
+
+- **One command.** `plugbrain setup <id>`, or `plugbrain setup --all` for every
+  client that is installed. An unknown id is refused (exit code 1) and the known
+  ones are listed.
+- **One entry, nothing else.** It writes a server named `plugbrain` into the
+  client's own config file and changes no other entry's content.
+- **No ids, no tokens.** The entry is only *the node binary*, *the PlugBrain CLI*
+  and the argument `mcp`.
+- **The workspace comes from the folder.** PlugBrain takes the project from the
+  directory the client starts it in: `PLUGBRAIN_WORKSPACE` if set, else the
+  registered root that contains the folder, else the folder's git root
+  ([`src/setup/workspace-from-cwd.ts`](../../src/setup/workspace-from-cwd.ts)).
+  So the same entry works in every project, and no workspace id has to be
+  written anywhere.
+- **A backup before the first real change.** A copy named
+  `<file>.plugbrain-backup-<stamp>` lands next to the file. If setup created the
+  file, the backup is an empty marker instead, so `--undo` can tell a creation
+  from an update.
+- **Idempotent.** A second run that would write the same entry writes nothing and
+  takes no backup.
+- **`--dry-run` writes nothing at all** — no file, no backup — and prints only
+  the changed lines.
+- **`--undo` takes it back out.** For a file setup created it removes just the
+  `plugbrain` entry (and the file, when nothing of yours remains); for an
+  existing file it restores the newest backup. Either way the state it replaces
+  is kept as `<file>.plugbrain-undobackup-<stamp>` first, so edits you made after
+  setup are not lost.
+- **A client that is not installed is skipped**, and the report says how many
+  were. Nothing is written for them.
+- **Errors stay local.** A client whose config cannot be parsed is reported as an
+  `error`; the other clients are still configured.
+- `PLUGBRAIN_CONFIG_HOME` moves where the client config files are looked for.
+  That is not `PLUGBRAIN_HOME`, which is the brain's own data directory.
+
+Run `plugbrain setup --dry-run` first if you want to see the change before it
+happens.
+
+## After setup: the per-turn rules
+
+Setup teaches a client how to *reach* PlugBrain. What an agent should do on every
+turn — check in, claim paths, admit work, end the turn with a state — is the
+agent protocol block in [agent-protocol.md](../agent-protocol.md). Paste it into
+the project's `AGENTS.md` or `CLAUDE.md`, and give every agent its own id.
+
+## See also
+
+- [`plugbrain setup`](../cli.md#setup) — the command and its flags
+- [MCP tools](../mcp-tools.md) — what an agent can call once the server runs
+- [agent-protocol.md](../agent-protocol.md) — the turn rules