okf-agentbus 0.2.3__tar.gz

okf_agentbus-0.2.3/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+.agentbus/

okf_agentbus-0.2.3/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [0.2.3] - 2026-07-07
+
+### Changed
+
+- PyPI package renamed to **`okf-agentbus`** — `agentbus-mcp` rejected as too similar to existing `agentbus` project
+
+## [0.2.2] - 2026-07-07
+
+### Added
+
+- `tests/factory_validate.py` — MCP integration validation (Agy event-56 criteria)
+- `tests/test_factory_mcp_validation.py` — pytest `@integration` wrapper
+
+### Fixed
+
+- Integration validation: real TTL wait, 3-client concurrency hammer, MCP-only auth test
+
+## [0.2.1] - 2026-07-07
+
+### Fixed
+
+- MCP auth: workspace token file now wins over stale `AGENTBUS_TOKEN` env in subprocesses
+- `mcp-serve.sh` resolves `agentbus` from `$PATH` (pip install) before repo venv
+
+### Changed
+
+- PyPI package renamed to **`agentbus-mcp`** (avoids collision with unrelated `agentbus` NATS project)
+- Docs updated to v0.2: lease tools, 40 tests, Hermes MCP example
+- MCP integration tests for lock tools
+
+## [0.2.0] - 2026-07-07
+
+### Added
+
+- Phase 5 advisory lease locks in `events.db` (`leases` table)
+- MCP tools: `agentbus_lock_acquire`, `agentbus_lock_release`, `agentbus_lock_renew`, `agentbus_lock_status`
+- CLI: `agentbus lock acquire|release|renew|status`
+- `tests/test_leases.py` — acquire, conflict, renew, TTL expiry, auth, workspace boundary
+
+## [0.1.0] - 2026-07-07
+
+### Added
+
+- MCP stdio server with `agentbus_publish`, `agentbus_poll`, `agentbus_status`
+- SQLite event store with idempotency and retention
+- Workspace ephemeral token authentication (`{workspace}/.agentbus/token`)
+- CLI: `serve`, `publish`, `poll`, `status`, `token`, `project-log`
+- `scripts/mcp-serve.sh` wrapper for MCP client token injection
+- Reference topics: `okf/handoff`, `okf/status/<initiative>`
+- 22 tests including MCP stdio round-trip
+
+[0.2.3]: https://github.com/onicarps/agentbus/releases/tag/v0.2.3
+[0.2.2]: https://github.com/onicarps/agentbus/releases/tag/v0.2.2
+[0.2.1]: https://github.com/onicarps/agentbus/releases/tag/v0.2.1
+[0.2.0]: https://github.com/onicarps/agentbus/releases/tag/v0.2.0
+[0.1.0]: https://github.com/onicarps/agentbus/releases/tag/v0.1.0

okf_agentbus-0.2.3/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to AgentBus
+
+Thank you for helping make multi-agent local coordination better for everyone.
+
+## Quick start
+
+```bash
+git clone https://github.com/onicarps/agentbus.git
+cd agentbus
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest tests/ -q
+python tests/factory_validate.py   # MCP integration validation (Agy gate)
+```
+
+## What to work on
+
+See [ROADMAP.md](ROADMAP.md) and [open issues](https://github.com/onicarps/agentbus/issues). High-value contribution areas:
+
+1. **New topic schemas** — propose JSON Schema for real-world handoff patterns
+2. **Client recipes** — tested MCP configs for Cursor, Claude Desktop, Windsurf, etc.
+3. **Poll ergonomics** — helpers, SDKs, retry/backoff patterns
+4. **Docs** — architecture notes, deployment guides, comparison with file-based blackboards
+
+## Pull request checklist
+
+- [ ] Tests pass: `pytest tests/ -q`
+- [ ] New behavior has tests
+- [ ] Public API changes documented in `docs/MCP_SCHEMA.md` or README
+- [ ] No secrets, tokens, or machine-local paths committed
+
+## Architecture notes
+
+| Module | Role |
+|--------|------|
+| `store.py` | SQLite event log, retention, idempotency |
+| `server.py` | FastMCP tool definitions |
+| `auth.py` | Workspace ephemeral token |
+| `schemas.py` | Topic registry + JSON Schema validation |
+| `leases.py` | Advisory lease store (SQLite `leases` table) |
+| `cli.py` | `serve`, `publish`, `poll`, `status`, `token`, `lock`, `project-log` |
+
+## Versioning
+
+AgentBus is **0.x** (pre-1.0). Minor releases may add topics and tools; patch releases are bugfixes. Breaking changes will be noted in [CHANGELOG.md](CHANGELOG.md).
+
+## Code of conduct
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

okf_agentbus-0.2.3/LICENSE

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

okf_agentbus-0.2.3/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: okf-agentbus
+Version: 0.2.3
+Summary: Local MCP event log for multi-agent workspaces
+Project-URL: Homepage, https://github.com/onicarps/agentbus
+Project-URL: Repository, https://github.com/onicarps/agentbus
+Project-URL: Issues, https://github.com/onicarps/agentbus/issues
+Project-URL: Documentation, https://github.com/onicarps/agentbus/blob/main/docs/MCP_SCHEMA.md
+Author: onicarps
+License: MIT
+License-File: LICENSE
+Keywords: agents,event-log,mcp,multi-agent,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: mcp>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentBus
+
+[![Test](https://github.com/onicarps/agentbus/actions/workflows/test.yml/badge.svg)](https://github.com/onicarps/agentbus/actions/workflows/test.yml)
+[![Python](https://img.shields.io/pypi/pyversions/okf-agentbus.svg)](https://pypi.org/project/okf-agentbus/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Local MCP event log and advisory lease coordinator for multi-agent workspaces.**
+
+When Cursor, Claude Code, Antigravity, Hermes, and other agents share a workspace, they usually coordinate through append-only files (`log.md`, sticky notes, Slack). That works until you need ordering, idempotency, cursors, schema validation, or file-edit mutexes.
+
+AgentBus is a **localhost sidecar**: a Python MCP server backed by SQLite. Agents publish structured events; peers poll with `since_id` cursors. Advisory lease locks prevent concurrent edits. No orchestrator runtime lock-in.
+
+> **v0.2 (July 2026):** Events + advisory lease locks — `publish`, `poll`, `status`, `lock_*`. SSE subscribe and custom topics on the [roadmap](ROADMAP.md).
+
+> **Note:** PyPI names `agentbus` (NATS) and `agentbus-mcp` (blocked as too similar) are unavailable. Install as **`okf-agentbus`** (CLI command remains `agentbus`).
+
+## Why AgentBus?
+
+| Alternative | Limitation | AgentBus |
+|-------------|------------|----------|
+| `log.md` blackboard | No schema, races, manual cursors | Typed topics, monotonic IDs, poll API |
+| `flock` / git mutex | No agent identity, no TTL | Advisory leases with heartbeat renewal |
+| Redis pub/sub | Extra daemon, no MCP path | stdio MCP — works in existing IDEs |
+| LangGraph / AutoGen | Same-runtime only | Heterogeneous out-of-process clients |
+
+## Install
+
+```bash
+pip install okf-agentbus
+
+# Or from GitHub
+pip install "okf-agentbus @ git+https://github.com/onicarps/agentbus@v0.2.3"
+
+# Or clone for development
+git clone https://github.com/onicarps/agentbus.git
+cd agentbus
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+export AGENTBUS_WORKSPACE=/path/to/workspace
+export AGENTBUS_PRODUCER_ID=my-agent
+
+# Terminal A — MCP server (stdio)
+agentbus serve --workspace "$AGENTBUS_WORKSPACE"
+
+# Terminal B — publish a handoff
+agentbus publish \
+  --topic okf/handoff \
+  --payload '{"from":"my-agent","to":"peer","summary":"Hello bus"}'
+
+# Poll events
+agentbus poll --topic okf/handoff --since-id 0
+
+# Acquire an advisory lease before editing a shared file
+agentbus lock acquire --resource "$AGENTBUS_WORKSPACE/log.md" --owner-id my-agent
+agentbus lock status --resource "$AGENTBUS_WORKSPACE/log.md"
+agentbus lock release --resource "$AGENTBUS_WORKSPACE/log.md" --lease-id <uuid> --owner-id my-agent
+```
+
+## MCP setup
+
+Use `scripts/mcp-serve.sh` so the workspace token is injected automatically:
+
+```json
+{
+  "mcpServers": {
+    "agentbus": {
+      "command": "/path/to/agentbus/scripts/mcp-serve.sh",
+      "env": {
+        "AGENTBUS_WORKSPACE": "/path/to/workspace",
+        "AGENTBUS_PRODUCER_ID": "cursor"
+      }
+    }
+  }
+}
+```
+
+Client-specific templates:
+
+| Client | Config |
+|--------|--------|
+| Cursor | [examples/mcp-cursor.json](examples/mcp-cursor.json) |
+| Claude Desktop | [examples/mcp-claude-desktop.json](examples/mcp-claude-desktop.json) |
+| Hermes | [examples/mcp-hermes.json](examples/mcp-hermes.json) |
+
+### MCP tools
+
+| Tool | Auth | Purpose |
+|------|------|---------|
+| `agentbus_publish` | Yes | Append one validated event |
+| `agentbus_poll` | No | Fetch events after `since_id` (at-least-once) |
+| `agentbus_status` | No | Event counts, topics, health |
+| `agentbus_lock_acquire` | Yes | Exclusive advisory lease on a resource path |
+| `agentbus_lock_release` | Yes | Release a held lease |
+| `agentbus_lock_renew` | Yes | Extend TTL (heartbeat) |
+| `agentbus_lock_status` | No | Check lock state without acquiring |
+
+Full schema: [docs/MCP_SCHEMA.md](docs/MCP_SCHEMA.md)
+
+## Authentication
+
+On `serve`, AgentBus writes an ephemeral token to `{workspace}/.agentbus/token` (mode `0600`). Publish and lock mutations require a matching token via:
+
+- `scripts/mcp-serve.sh` (recommended for MCP — reads workspace file, not stale env)
+- `AGENTBUS_TOKEN` environment variable
+- `--token` CLI flag
+- `auth_token` MCP tool argument (optional; omit when using `mcp-serve.sh`)
+
+Poll, status, and lock_status remain open. Set `AGENTBUS_AUTH=off` to disable during local development.
+
+Details: [docs/AUTH.md](docs/AUTH.md)
+
+## Topics (v0.2)
+
+| Topic | Purpose |
+|-------|---------|
+| `okf/handoff` | Structured agent handoff (`from`, `to`, `summary`) |
+| `okf/status/<name>` | Status ping (`idle`, `active`, `blocked`, `complete`) |
+
+Custom topics are planned — [contributions welcome](CONTRIBUTING.md).
+
+## CLI reference
+
+```bash
+agentbus serve [--workspace PATH] [--rotate-token]
+agentbus publish --topic TOPIC --payload JSON [--producer-id ID]
+agentbus poll --topic TOPIC [--since-id N] [--limit N]
+agentbus status [--producer-id ID]
+agentbus token show|ensure|rotate
+agentbus lock acquire|release|renew|status
+agentbus project-log [--log-file log.md]   # optional markdown projection
+```
+
+Set `AGENTBUS_WORKSPACE` to avoid repeating `--workspace`.
+
+## Development
+
+```bash
+.venv/bin/pytest tests/ -q          # 40+ tests
+.venv/bin/pytest tests/ --cov=agentbus --cov-report=term-missing
+```
+
+## Project layout
+
+```
+src/agentbus/     # Python package
+tests/            # pytest suite (40 tests)
+docs/             # MCP schema, auth guide
+examples/         # MCP client configs (Cursor, Claude, Hermes)
+scripts/          # mcp-serve.sh wrapper
+```
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md). v0.2 ships events + advisory locks; v0.3 targets custom topics and HTTP transport.
+
+## Contributing
+
+We want real-world use cases from teams running heterogeneous agent stacks. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

okf_agentbus-0.2.3/README.md

@@ -0,0 +1,167 @@
+# AgentBus
+
+[![Test](https://github.com/onicarps/agentbus/actions/workflows/test.yml/badge.svg)](https://github.com/onicarps/agentbus/actions/workflows/test.yml)
+[![Python](https://img.shields.io/pypi/pyversions/okf-agentbus.svg)](https://pypi.org/project/okf-agentbus/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Local MCP event log and advisory lease coordinator for multi-agent workspaces.**
+
+When Cursor, Claude Code, Antigravity, Hermes, and other agents share a workspace, they usually coordinate through append-only files (`log.md`, sticky notes, Slack). That works until you need ordering, idempotency, cursors, schema validation, or file-edit mutexes.
+
+AgentBus is a **localhost sidecar**: a Python MCP server backed by SQLite. Agents publish structured events; peers poll with `since_id` cursors. Advisory lease locks prevent concurrent edits. No orchestrator runtime lock-in.
+
+> **v0.2 (July 2026):** Events + advisory lease locks — `publish`, `poll`, `status`, `lock_*`. SSE subscribe and custom topics on the [roadmap](ROADMAP.md).
+
+> **Note:** PyPI names `agentbus` (NATS) and `agentbus-mcp` (blocked as too similar) are unavailable. Install as **`okf-agentbus`** (CLI command remains `agentbus`).
+
+## Why AgentBus?
+
+| Alternative | Limitation | AgentBus |
+|-------------|------------|----------|
+| `log.md` blackboard | No schema, races, manual cursors | Typed topics, monotonic IDs, poll API |
+| `flock` / git mutex | No agent identity, no TTL | Advisory leases with heartbeat renewal |
+| Redis pub/sub | Extra daemon, no MCP path | stdio MCP — works in existing IDEs |
+| LangGraph / AutoGen | Same-runtime only | Heterogeneous out-of-process clients |
+
+## Install
+
+```bash
+pip install okf-agentbus
+
+# Or from GitHub
+pip install "okf-agentbus @ git+https://github.com/onicarps/agentbus@v0.2.3"
+
+# Or clone for development
+git clone https://github.com/onicarps/agentbus.git
+cd agentbus
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+export AGENTBUS_WORKSPACE=/path/to/workspace
+export AGENTBUS_PRODUCER_ID=my-agent
+
+# Terminal A — MCP server (stdio)
+agentbus serve --workspace "$AGENTBUS_WORKSPACE"
+
+# Terminal B — publish a handoff
+agentbus publish \
+  --topic okf/handoff \
+  --payload '{"from":"my-agent","to":"peer","summary":"Hello bus"}'
+
+# Poll events
+agentbus poll --topic okf/handoff --since-id 0
+
+# Acquire an advisory lease before editing a shared file
+agentbus lock acquire --resource "$AGENTBUS_WORKSPACE/log.md" --owner-id my-agent
+agentbus lock status --resource "$AGENTBUS_WORKSPACE/log.md"
+agentbus lock release --resource "$AGENTBUS_WORKSPACE/log.md" --lease-id <uuid> --owner-id my-agent
+```
+
+## MCP setup
+
+Use `scripts/mcp-serve.sh` so the workspace token is injected automatically:
+
+```json
+{
+  "mcpServers": {
+    "agentbus": {
+      "command": "/path/to/agentbus/scripts/mcp-serve.sh",
+      "env": {
+        "AGENTBUS_WORKSPACE": "/path/to/workspace",
+        "AGENTBUS_PRODUCER_ID": "cursor"
+      }
+    }
+  }
+}
+```
+
+Client-specific templates:
+
+| Client | Config |
+|--------|--------|
+| Cursor | [examples/mcp-cursor.json](examples/mcp-cursor.json) |
+| Claude Desktop | [examples/mcp-claude-desktop.json](examples/mcp-claude-desktop.json) |
+| Hermes | [examples/mcp-hermes.json](examples/mcp-hermes.json) |
+
+### MCP tools
+
+| Tool | Auth | Purpose |
+|------|------|---------|
+| `agentbus_publish` | Yes | Append one validated event |
+| `agentbus_poll` | No | Fetch events after `since_id` (at-least-once) |
+| `agentbus_status` | No | Event counts, topics, health |
+| `agentbus_lock_acquire` | Yes | Exclusive advisory lease on a resource path |
+| `agentbus_lock_release` | Yes | Release a held lease |
+| `agentbus_lock_renew` | Yes | Extend TTL (heartbeat) |
+| `agentbus_lock_status` | No | Check lock state without acquiring |
+
+Full schema: [docs/MCP_SCHEMA.md](docs/MCP_SCHEMA.md)
+
+## Authentication
+
+On `serve`, AgentBus writes an ephemeral token to `{workspace}/.agentbus/token` (mode `0600`). Publish and lock mutations require a matching token via:
+
+- `scripts/mcp-serve.sh` (recommended for MCP — reads workspace file, not stale env)
+- `AGENTBUS_TOKEN` environment variable
+- `--token` CLI flag
+- `auth_token` MCP tool argument (optional; omit when using `mcp-serve.sh`)
+
+Poll, status, and lock_status remain open. Set `AGENTBUS_AUTH=off` to disable during local development.
+
+Details: [docs/AUTH.md](docs/AUTH.md)
+
+## Topics (v0.2)
+
+| Topic | Purpose |
+|-------|---------|
+| `okf/handoff` | Structured agent handoff (`from`, `to`, `summary`) |
+| `okf/status/<name>` | Status ping (`idle`, `active`, `blocked`, `complete`) |
+
+Custom topics are planned — [contributions welcome](CONTRIBUTING.md).
+
+## CLI reference
+
+```bash
+agentbus serve [--workspace PATH] [--rotate-token]
+agentbus publish --topic TOPIC --payload JSON [--producer-id ID]
+agentbus poll --topic TOPIC [--since-id N] [--limit N]
+agentbus status [--producer-id ID]
+agentbus token show|ensure|rotate
+agentbus lock acquire|release|renew|status
+agentbus project-log [--log-file log.md]   # optional markdown projection
+```
+
+Set `AGENTBUS_WORKSPACE` to avoid repeating `--workspace`.
+
+## Development
+
+```bash
+.venv/bin/pytest tests/ -q          # 40+ tests
+.venv/bin/pytest tests/ --cov=agentbus --cov-report=term-missing
+```
+
+## Project layout
+
+```
+src/agentbus/     # Python package
+tests/            # pytest suite (40 tests)
+docs/             # MCP schema, auth guide
+examples/         # MCP client configs (Cursor, Claude, Hermes)
+scripts/          # mcp-serve.sh wrapper
+```
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md). v0.2 ships events + advisory locks; v0.3 targets custom topics and HTTP transport.
+
+## Contributing
+
+We want real-world use cases from teams running heterogeneous agent stacks. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

okf_agentbus-0.2.3/ROADMAP.md

@@ -0,0 +1,57 @@
+# AgentBus Roadmap
+
+**Status:** v0.2 — events + advisory lease locks (July 2026)
+
+## Shipped (v0.1)
+
+- [x] MCP stdio server: `publish`, `poll`, `status`
+- [x] SQLite durable event log with monotonic `event_id`
+- [x] Topic JSON Schema validation
+- [x] Idempotency keys + 7-day retention
+- [x] Workspace ephemeral token auth
+- [x] CLI for non-MCP clients
+- [x] `project-log` — optional markdown projection for handoff topics
+
+## Shipped (v0.2)
+
+- [x] Advisory lease locks in `events.db` (`leases` table)
+- [x] MCP: `agentbus_lock_acquire`, `agentbus_lock_release`, `agentbus_lock_renew`, `agentbus_lock_status`
+- [x] CLI: `agentbus lock acquire|release|renew|status`
+- [x] 40 tests including lease store + MCP stdio round-trip
+- [x] PyPI package name `okf-agentbus` (`agentbus`/`agentbus-mcp` blocked on PyPI)
+
+## Next (community-driven)
+
+### v0.2.x — Distribution & onboarding
+
+- [x] PyPI publish as `okf-agentbus`
+- [ ] GitHub Release assets (wheel/sdist) on tag
+- [ ] End-to-end multi-agent handoff walkthrough in docs
+- [ ] Client capability matrix with tested configs per IDE
+
+### v0.3 — Developer experience
+
+- [ ] Pluggable topic registry (user-defined schemas)
+- [ ] Generic `workspace/handoff` topic alongside reference `okf/handoff`
+- [ ] Poll ergonomics helpers (backoff, cursor management)
+
+### v0.4 — Operations
+
+- [ ] HTTP transport (optional, localhost-only)
+- [ ] Topic ACLs
+- [ ] Export / backup commands
+
+### v1.0 — Stable API
+
+- [ ] SSE subscribe where MCP clients support it
+- [ ] Stable 1.0 API guarantee
+
+## How to influence the roadmap
+
+Open an issue with:
+
+1. **Use case** — what agents/clients you run
+2. **Pain** — what breaks with `log.md`, Redis, or ad-hoc files today
+3. **Proposal** — schema, tool, or behavior change
+
+Real-world dogfood reports beat theoretical features.

okf_agentbus-0.2.3/docs/AUTH.md

@@ -0,0 +1,51 @@
+# Authentication
+
+AgentBus v0.2 uses **workspace-scoped ephemeral tokens** to prevent unauthorized local processes from publishing events or mutating leases.
+
+## How it works
+
+1. `agentbus serve` calls `ensure_ephemeral_token(workspace)`
+2. Token is written to `{workspace}/.agentbus/token` with file mode **0600**
+3. `agentbus_publish` and `agentbus_lock_*` (except `lock_status`) must present the same token
+4. `agentbus_poll`, `agentbus_status`, and `agentbus_lock_status` do **not** require a token
+
+## Token resolution order
+
+When validating publish/lock operations:
+
+1. `auth_token` tool argument (if provided)
+2. Workspace token file (`{workspace}/.agentbus/token`)
+3. `AGENTBUS_TOKEN` environment variable
+
+The workspace file **wins over** a stale `AGENTBUS_TOKEN` in MCP subprocesses. This is why `scripts/mcp-serve.sh` reads the file and exports a fresh value on each start.
+
+## Providing the token
+
+| Channel | Mechanism |
+|---------|-----------|
+| MCP (recommended) | `scripts/mcp-serve.sh` exports `AGENTBUS_TOKEN` from workspace file |
+| MCP tool arg | `auth_token` parameter (optional when wrapper injects env) |
+| CLI | Auto-reads workspace token file, or `--token`, or `AGENTBUS_TOKEN` env |
+| Legacy | `AGENTBUS_EXPECTED_TOKEN` env (fallback when no token file) |
+
+## Disabling auth
+
+For local development only:
+
+```bash
+export AGENTBUS_AUTH=off
+```
+
+## Rotating tokens
+
+```bash
+agentbus serve --rotate-token
+# or
+agentbus token rotate --workspace /path/to/workspace
+```
+
+All MCP clients must restart to pick up the new token.
+
+## Threat model
+
+v0.2 assumes a **single-user localhost workspace**. The token file gates who can publish and acquire locks; it is not a multi-tenant identity system. Do not expose AgentBus over a network without additional hardening.