logplane 0.13.0__tar.gz

logplane-0.13.0/COMPATIBILITY.md

@@ -0,0 +1,193 @@
+# Compatibility and support policy
+
+This document defines the pre-v1.0 baseline and the intended v1.x contract.
+It does not declare v1.0 released or retroactively certify every old version.
+Release status and outstanding evidence live in [ROADMAP.md](ROADMAP.md).
+
+## Supported deployment target
+
+logplane targets one trusted local host running macOS or Linux, using CPython
+3.10 or newer. The CI matrix covers 3.10, 3.13, and 3.14; results for a new
+matrix entry must pass before that entry is treated as verified. Other Python
+versions are not verified merely because package metadata permits installation.
+Native Windows is not supported: process locking uses `fcntl`. WSL, alternative
+interpreters, network filesystems, and distributed deployments are not certified.
+
+CI tests the declared direct dependency minimums on Python 3.10 separately from
+latest-compatible resolution. The floor constraint file is a test input, not
+a production lockfile or a claim to test every transitive dependency combination.
+Resolved dependency versions are retained with each run. Supported releases
+require a passing package-install smoke, not just tests in an editable checkout.
+
+## Versioned surfaces
+
+| Surface | Current baseline | Compatibility boundary |
+| --- | --- | --- |
+| Package | `0.13.0` release | Pre-1.0 changes must be documented; do not infer a 1.x guarantee yet |
+| Python integration | Names exported by `logplane`, `logplane.adapters`, `logplane.protocol` | Documented constructors, methods, typed outcomes, and effect identity |
+| Executor wire format | `agent-bus.executor` v1 | Selected envelope version is explicit; headers are strict |
+| Event envelope | Built-in writes use schema v2 | History is immutable; acceptance and replay semantics are part of the contract |
+| Local/adapter configuration | Each uses schema v1 | Version and supported keys must match that component |
+| CLI | Documented commands, options, `--json` fields, and exit statuses | Human-readable wording/layout is not an API |
+| Database indexes / PM snapshots | Derived local caches | No public table layout or snapshot-file compatibility promise |
+| Recovery bundles | Versioned verified local format | Unsupported formats must fail safely; hashes are integrity checks, not signatures |
+
+Implementation modules live under `logplane.*` (for example `logplane.bus`),
+but integrations should import from `logplane`, `logplane.adapters`, and
+`logplane.protocol`. Private helpers, reducer dataclass internals,
+SQLite tables, test fixtures, and benchmark output are not public integration
+APIs. The `demo` module behind `logplane demo` is a CLI implementation detail,
+not an integration API. Importable implementation modules are not a promise
+to freeze their private members. Repository examples are source assets, not installed packages.
+
+### Additions and unknown values
+
+- Do not remove or change the meaning/type of an existing public field silently.
+  A new optional field needs a default and a compatibility test. Adding a
+  required field or changing interpretation is a breaking change.
+- Do not assume every JSON object permits arbitrary keys. Executor envelopes
+  and protocol headers, local/adapter configs, and some payloads use strict
+  shapes. A change rejected by an older supported reader needs a new format
+  version or an explicit coordinated upgrade, not the label "additive".
+- Executor v1 `supported_versions` may advertise future versions as long as the
+  selected version is included. It is not automatic negotiation; use the same
+  selected version at both ends. Legacy unversioned v0 is limited to the existing
+  legacy subprocess path; new configured CLI/HTTP integrations use v1.
+- New built-in writes use event schema v2. Legacy stored rows remain readable;
+  readable history does not mean old events satisfy every modern reducer rule.
+  Existing migrations and release fixtures, not a blanket "all history works"
+  statement, define demonstrated coverage.
+- Unknown custom topics are storage extensions, not permission to influence the
+  PM. Keep custom readers tolerant of unrelated topics. Raw telemetry topics
+  are not replayed by the PM; compact `workflow.usage_recorded` coordination
+  events may affect budget admission.
+- CLI JSON consumers should tolerate additional object fields and avoid parsing
+  human output. Existing fields must retain their meaning. Unknown status/enum
+  values should be displayed as unknown, not treated as completed/successful.
+  Newly emitted enum values require release notes and a consumer review.
+
+### CLI exit statuses
+
+| Code | Meaning |
+| ---: | --- |
+| 0 | Command succeeded; inspect the result for task/diagnostic state |
+| 2 | Invalid usage/configuration, transport failure, or rejected operation |
+| 3 | Lookup did not find the requested task/workflow |
+| 4 | An adapter probe fails/times out, a storage audit fails, or replay rejects a recorded operator intent |
+| 130 | Interrupted by the operator |
+
+Zero does not mean a submitted task completed, or that all doctor checks are
+healthy: read `--json` and the check/state fields. Errors currently go to stderr
+and need not be JSON even when `--json` was selected. Unexpected crashes are not
+a stable error protocol. Tail output is a stream, not one JSON document.
+
+## Upgrade, downgrade, and deployment versions
+
+1. Read release notes. Stop PMs, workers, submitters, and artifact publishers.
+2. Preserve configuration and a verified database/artifact backup using
+   [RECOVERY.md](RECOVERY.md). Do not delete history or copy a live SQLite file
+   without its supported backup mechanism.
+3. Upgrade bus, PM, workers, and operator CLI together. Mixed coordination
+   package versions are not a supported rolling-upgrade strategy. External
+   adapters can remain on their explicitly supported wire version.
+4. Start the bus to run transactional migrations, then PM/workers; verify
+   doctor, pending work, and representative task/workflow output.
+
+Indexes may be rebuilt and incompatible snapshots discarded. These operations
+must not rewrite original events. Downgrading binaries over an upgraded live
+database is unsupported and is not universally rejected by the current code.
+For rollback, stop new processes and restore a pre-upgrade backup into a separate
+directory with its matching version. Later work and external side effects do
+not disappear or roll back automatically; reconcile them before resuming.
+
+## Release and deprecation rules
+
+Before v1.0, releases may change contracts but must document known breaks and
+provide tests/upgrade guidance. The readiness baseline protects v0.11.0 public
+exports and representative adapter messages; it is not exhaustive coverage of
+all old releases, CLI outputs, or historical database semantics.
+
+The released-database baseline now also captures v0.11.0's actual SQLite
+schema/history/snapshot as SQL, plus release-produced CLI and adapter outputs.
+Tests reconstruct disposable databases, run current initialization repeatedly,
+and verify raw event values/identity, idempotency, counters, snapshot fallback,
+index reconstruction, and continued reconciliation. Cases include DAG result
+propagation, human decisions, retry, pause/resume, cancellation, lease/deadline
+expiry, and persisted policy with missing usage. Public JSON comparisons permit
+additional fields but preserve existing field types and values.
+
+This demonstrates **v0.11.0 → current development** for the captured cases.
+v0.12.0 adds CLI commands and options only (`demo`, `submit --depends-on`, and
+`demo-worker` outcome flags), corrects `serve`'s startup-failure status to 2,
+and changes no event, executor, configuration, or `--json` field contract.
+It adds no schema migration and does not certify physical WAL recovery, every
+historical release, or downgrades. See the [fixture provenance](tests/fixtures/compatibility/v0.11.0-upgrade/README.md).
+
+v0.13.0 renames the project from agent-bus to logplane: the distribution,
+import package, `logplane` command, `LOGPLANE_*` environment variables, and
+`logplane.local.json` config file. The pre-0.13 flat modules and the
+`agent_bus` package are removed, and old `AGENT_BUS_*` variables or an
+`agent-bus.local.json` without a `logplane.local.json` fail with a rename
+message instead of being ignored. Identifiers stored in history or shared with
+external adapters keep their original spelling, so existing databases,
+backups, and adapters work unchanged: the `agent-bus` ownership owner, the
+effect-key salts behind `effect_id()`, the `agent-bus.executor` protocol name,
+the `X-Agent-Bus-*` HTTP headers, the `agent_bus_conformance_probe` context
+key, and the backup bundle kinds. See the
+[migration steps](RELEASE_NOTES.md#migrating-from-agent-bus).
+
+The owner-approved v1.0 upgrade baseline is **v0.11.0**: this is the oldest
+starting release for a supported direct upgrade to v1.0. Direct upgrades from
+earlier releases are not promised. Any intervening release included in the
+supported path needs its own release-derived regression coverage; do not infer
+coverage solely from its version number. The final v1.0 build must pass these
+upgrade checks before release. This is a selected support scope, not a claim
+that v1.0 has shipped or that every historical database has been tested.
+
+For v1.x, patches are intended for compatible fixes; minor releases may add
+compatible capabilities. Removing supported APIs or changing existing wire/
+event semantics requires a major version, except urgent security corrections
+whose impact and mitigation must be called out explicitly. Deprecations should
+be documented in release notes and remain available through the current major
+series; use runtime warnings where actionable and safe for protocol output.
+Bug fixes can change behavior outside the documented contract.
+
+Maintenance targets the latest release; no LTS/backport window or response-time
+SLA is promised. The project uses the [MIT License](LICENSE), with copyright
+held by deki and development acknowledgements in [CONTRIBUTORS.md](CONTRIBUTORS.md).
+Trials continue using GitHub source installations; PyPI publication, native
+Windows, and a distributed service remain separate decisions. No package is
+published by selecting a license. The public 1.x promise requires
+the remaining roadmap gates, including independent onboarding evidence.
+
+Building from source requires setuptools 77.0.3 or newer for standard SPDX
+license metadata. Isolated builds install that build dependency automatically;
+the runtime Python and dependency requirements are unchanged.
+
+## Running the release checks
+
+From a development checkout with a supported Python:
+
+```sh
+python -m pip install -r requirements-dev.txt
+python -m pip install -e .
+python -m pytest -q
+python -m build
+python scripts/check_release.py --wheel dist/logplane-0.13.0-py3-none-any.whl
+```
+
+Use the wheel filename produced by the build if its version differs. The build
+creates an sdist and builds the wheel from it. The check creates a fresh venv,
+installs the wheel/dependencies, verifies import origins, and exercises a
+successful and timed-out CLI adapter check plus a credential-free live task
+outside the checkout. It also checks discovery, human response, retry, and
+cancellation through a small live worker, including duplicate commands, and
+runs released-database upgrade tests against the installed package. It downloads dependencies and
+uses only a disposable loopback server; it makes no model calls. It reports the
+retained evidence directory and stops its own processes on success or failure.
+Pass `--constraints ci/constraints-min.txt` to exercise direct dependency floors.
+GitHub CI uses the same check and uploads its diagnostics; configuring CI is
+not evidence that remote jobs have already passed.
+
+The workflow follows GitHub's [Python build/test guidance](https://docs.github.com/en/actions/tutorials/build-and-test-code/python),
+uses read-only repository permissions, and pins official actions to commit IDs.

logplane-0.13.0/CONTRIBUTORS.md

@@ -0,0 +1,15 @@
+# Credits
+
+Project owner and copyright holder: **deki**.
+
+## AI-assisted development acknowledgements
+
+The following names are credited as requested by the project owner:
+
+- GPT Sol
+- Fable 5.1
+- GPT-6 Astra
+
+These are development acknowledgements, not additional copyright-holder
+designations or endorsements. The project is distributed under the
+[MIT License](LICENSE).

logplane-0.13.0/LICENSE

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

logplane-0.13.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include COMPATIBILITY.md RECOVERY.md RELEASE_NOTES.md ROADMAP.md
+include LICENSE CONTRIBUTORS.md
+include requirements.txt requirements-dev.txt
+recursive-include benchmarks *.py *.md
+recursive-include scripts *.py
+recursive-include ci *.txt
+recursive-include tests *.py *.json *.sql *.md
+recursive-include examples *.py *.json *.md
+recursive-include docs *.md

logplane-0.13.0/PKG-INFO

@@ -0,0 +1,359 @@
+Metadata-Version: 2.4
+Name: logplane
+Version: 0.13.0
+Summary: A local control plane for AI agents, built on an append-only event log
+Author: deki
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dekizk/logplane
+Project-URL: Documentation, https://github.com/dekizk/logplane#documentation
+Project-URL: Changelog, https://github.com/dekizk/logplane/blob/main/RELEASE_NOTES.md
+Project-URL: Issues, https://github.com/dekizk/logplane/issues
+Keywords: ai-agents,orchestration,control-plane,event-sourcing,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.8
+Requires-Dist: uvicorn<1,>=0.30
+Dynamic: license-file
+
+# logplane
+
+**A local control plane for AI agents.** logplane assigns work, recovers from
+crashes, holds risky actions for human approval, and enforces cost caps, and
+it drives all of it from an append-only event log instead of a mutable task
+board.
+
+![logplane demo recovery: a worker and the coordinator are killed mid-task, then a new worker finishes the workflow from the log](docs/demo-recovery.gif)
+
+Agent workflows fail in ordinary ways. A worker crashes mid-task, the
+coordinator restarts, two runners pick up the same job, an agent needs a human
+answer, or a retry repeats an external action. A kanban-style board only shows
+where a card was last moved. logplane records what actually happened, as
+immutable events, and derives current state by replaying them. Ownership,
+retries, dependencies, and human decisions are all events, so a crash loses
+nothing and every state can be explained.
+
+### See it in a minute
+
+```sh
+git clone https://github.com/dekizk/logplane.git && cd logplane
+python3 -m venv .venv && . .venv/bin/activate   # Python 3.10+
+python -m pip install -e .
+
+logplane demo recovery       # kill the worker and the coordinator mid-task
+logplane demo approval       # an agent asks before an irreversible tool call
+logplane demo budget         # a cost cap stops a runaway bill
+logplane demo audit-triage   # parallel reviewers, a human severity call,
+                              # findings submitted once despite a crash
+```
+
+Each demo starts its own bus, coordinator, and workers as real processes in a
+throwaway directory, narrates what happens, and keeps the history for you to
+inspect. The crashes are real `kill -9`s. None of it touches your other
+logplane data.
+
+<details>
+<summary>Watch <code>logplane demo approval</code>: an agent asks before an irreversible tool call</summary>
+
+![logplane demo approval: a support agent blocks before calling issue_refund, a human approves, and the refund runs once](docs/demo-approval.gif)
+
+</details>
+
+<details>
+<summary>Watch <code>logplane demo budget</code>: a cost cap stops a runaway bill</summary>
+
+![logplane demo budget: ten summaries under a $2 cost cap stop at $1.60, then finish after the cap is raised](docs/demo-budget.gif)
+
+</details>
+
+### What you get
+
+- **Crash recovery by design.** Workers hold leases. A dead worker's attempt is
+  expired and reassigned, and a restarted coordinator rebuilds state by replay.
+- **One owner per task.** Only the current attempt can advance a task, and late
+  results from a lost worker are rejected.
+- **Dependencies.** Tasks form a DAG, wait for upstream results, and propagate
+  failure downstream.
+- **Humans in the loop.** An agent can block with a question, such as approval
+  for a risky tool call. `logplane decide` answers it, and the answer is on
+  record.
+- **Spend limits.** Model calls report tokens and cost per task and attempt.
+  Workflow budgets stop new work at a cap, and raising the cap is an event too.
+- **Retry-safe external effects.** `assignment.effect_id(...)` is stable across
+  attempts, so a retry can skip work a crashed attempt already did.
+- **Bring your own agents.** Wrap a Python object, a CLI, or an HTTP service.
+  logplane never needs your agent's internals.
+- **Explainable state.** `logplane task`, `explain`, and `workflow --mermaid`
+  answer "why is this waiting?" from the log.
+
+It is local-first: one machine, SQLite, loopback only. See
+[trust and scope](#trust-and-scope) for what it does not do yet.
+
+## How it works
+
+The bus never stores a mutable card as truth. Every action (a task created, an
+attempt assigned, a worker's result, a human decision) is an immutable SQLite
+event. The project manager (PM) derives current state by replaying those
+events and reconciles anything missing, so any process can crash and restart
+without losing ownership state.
+
+- **You and your tools publish intent:** tasks, dependencies, policies,
+  decisions, cancellations.
+- **The PM** replays the log, assigns work to live workers, and records lease
+  expiries, retries, decision requests, and terminal states.
+- **Workers** execute only assignments addressed to their current process and
+  report one outcome per attempt.
+- **Every view** (`task`, `explain`, `workflow`) is rebuilt from the log.
+
+Four identities keep retries and replays unambiguous: `correlation_id` (one
+workflow), `task_id` (one logical outcome), `assignment_id` (one execution
+attempt), and `instance_id` (one worker process). The normal lifecycle is
+`task.created → task.assigned → task.started → task.completed`; recovery,
+human input, cancellation, and pauses are explicit events too.
+
+[How logplane works](docs/architecture.md) covers the full lifecycle,
+components, invariants, crash recovery, and trust model.
+
+## Install
+
+Use macOS or Linux with Python 3.10+; native Windows is not supported (see the
+[tested-platform policy](COMPATIBILITY.md#supported-deployment-target)).
+
+```sh
+git clone --branch v0.13.0 https://github.com/dekizk/logplane.git
+cd logplane
+python3 -m venv .venv && . .venv/bin/activate   # python3 --version must be 3.10+
+python -m pip install -e .
+logplane init
+```
+
+Use `--branch main` instead for the latest development version, and follow
+the README for the version you installed. If you already have a checkout, use
+it rather than cloning over it, and record `git rev-parse HEAD` when reporting
+trial results. Create the environment in `.venv`, not in the repository root.
+If your default `python3` is older than 3.10, create `.venv` with a supported
+interpreter such as `python3.11`. The editable install keeps this checkout as
+the source of the `logplane` command, so after pulling changes that add
+modules (for example `demo.py`), rerun `python -m pip install -e .`. logplane is not yet
+published on PyPI.
+
+## Run your own bus
+
+Run these in four terminals from the checkout, with `.venv` activated in each.
+The generated configuration binds only to loopback and keeps runtime data in
+the ignored `.logplane/` directory.
+
+```sh
+# terminal 1
+logplane serve
+
+# terminal 2
+logplane pm
+
+# terminal 3
+logplane demo-worker alice
+
+# terminal 4
+RESPONSE=$(logplane submit "Verify the logplane quick start" --json)
+TASK_ID=$(printf '%s' "$RESPONSE" | python -c \
+  'import json,sys; print(json.load(sys.stdin)["payload"]["task_id"])')
+CORRELATION_ID=$(printf '%s' "$RESPONSE" | python -c \
+  'import json,sys; print(json.load(sys.stdin)["correlation_id"])')
+printf 'Task: %s\nWorkflow: %s\n' "$TASK_ID" "$CORRELATION_ID"
+```
+
+After about one second, verify the bus, task, and derived workflow:
+
+```sh
+logplane doctor
+logplane task "$TASK_ID"
+logplane workflow "$CORRELATION_ID"
+```
+
+The expected state is a healthy schema-v2 bus with one healthy worker, a
+`completed` task whose last attempt belongs to `alice`, and a one-task
+`completed` workflow. The demo worker emits no model telemetry, so
+`tokens not reported` and `cost not reported` are expected rather than errors.
+
+<details>
+<summary>Machine-readable pass/fail checks</summary>
+
+```sh
+logplane task "$TASK_ID" --json | python -c '
+import json, sys
+task = json.load(sys.stdin)
+assert task["status"] == "completed", task
+assert task["assignment_active"] is False, task
+print("PASS: task is completed with no active assignment")
+'
+
+logplane workflow "$CORRELATION_ID" --json | python -c '
+import json, sys
+workflow = json.load(sys.stdin)
+assert workflow["status"] == "completed", workflow
+assert workflow["task_count"] == 1, workflow
+print("PASS: workflow reports one completed task")
+'
+```
+
+</details>
+
+If the task is still `assigned` or `started`, wait briefly and check again. If
+`logplane doctor` keeps warning, the PM, worker, or bus is probably using a
+different URL; see [connecting to the bus](docs/operations.md#connecting-to-the-bus).
+If `logplane` is not found, check that the terminal is in the checkout with
+`.venv` activated before reinstalling. `logplane tasks` and
+`logplane workflows` find IDs again if you lose them, and
+`logplane workflow "$CORRELATION_ID" --mermaid` prints the workflow as a
+Mermaid flowchart: another projection over the log, never an editable board.
+
+These checks inspect projected state; they do not prove exactly-once execution
+or external effects. To stop, press Ctrl-C in the worker terminal, then the PM,
+then the server. Local history is preserved.
+
+### Try dependencies, decisions, and failures
+
+The demo worker can deliberately block, fail, or work slowly so you can watch
+the other paths without writing an agent. Use one outcome flag per worker; the
+outcome happens once for that task ID.
+
+```sh
+logplane demo-worker alice --block 2           # task 2 asks a human for a decision
+logplane demo-worker alice --fail 2            # one retryable failure
+logplane demo-worker alice --fail-permanently 2
+logplane demo-worker alice --delay 30          # slow enough to kill mid-task
+```
+
+`submit --depends-on` builds a DAG from the command line; repeat it for
+fan-in. Dependents inherit the upstream workflow automatically (IDs below
+assume a fresh bus):
+
+```sh
+logplane submit "Research options"                                  # task 1
+logplane submit "Design storage" --depends-on 1                     # task 2
+logplane submit "Write docs" --depends-on 1                         # task 3
+logplane submit "Ship it" --depends-on 2 --depends-on 3             # task 4
+```
+
+A lease expiry or retryable failure consumes one retry, and `submit` defaults
+to no retries. If you plan to use `--fail` or kill a worker mid-task, submit
+with `--max-retries 2` (or higher) so the next attempt is allowed; otherwise
+the task correctly ends `failed`.
+
+## Everyday commands
+
+| Command | What it does |
+|---|---|
+| `logplane submit TITLE` | Create a task (`--depends-on`, `--capability`, `--max-retries`, `--priority`, `--context`) |
+| `logplane tasks` / `workflows` / `decisions` | List work, workflows, and pending questions with next-step commands |
+| `logplane task ID` / `explain ID` | Show one task's state and exactly why it is waiting or finished |
+| `logplane workflow ID` | Show a workflow's tasks, dependencies, policy, and token/cost usage (`--mermaid` for a diagram) |
+| `logplane tail ID` | Follow a workflow's events live |
+| `logplane decide` / `retry` / `cancel` | Answer a decision, grant more retries, or cancel a task |
+| `logplane pause` / `resume` / `supersede` | Pause or resume a task or workflow, or replace a task with new intent |
+| `logplane policy` / `agent-policy` | Set workflow concurrency and budgets, or per-agent limits |
+| `logplane workers` / `doctor` | Check worker leases and overall bus health |
+| `logplane adapter check` / `adapter run` | Verify and run an existing agent as a worker |
+| `logplane backup` / `verify-backup` / `restore` | Verified local backups ([recovery operations](RECOVERY.md)) |
+
+Finite commands accept `--json` for scripts. [Operating logplane](docs/operations.md)
+covers every command, scheduling, fairness, budgets, and controls in detail.
+
+## Connect your own agent
+
+Wrap an existing agent instead of rewriting it. A Python object with `run()`
+becomes a worker:
+
+```python
+from logplane import BusClient, Completed, PythonAgentAdapter, WorkerRuntime
+
+class ExistingAgent:
+    def run(self, assignment):
+        result = do_existing_work(
+            goal=assignment.goal,
+            context=assignment.context,
+            idempotency_key=assignment.effect_id("do-existing-work"),
+        )
+        return Completed("agent finished", {"result_ref": result.ref})
+
+bus = BusClient("http://127.0.0.1:8765", actor="existing-agent")
+WorkerRuntime(
+    bus,
+    name="existing-agent",
+    executor=PythonAgentAdapter(ExistingAgent()),
+    capacity=2,
+    capabilities=["python"],
+).run()
+```
+
+Check the contract before connecting it to a live bus:
+
+```sh
+logplane adapter check --python-target my_package.agent:ExistingAgent
+```
+
+CLI and HTTP agents use the same versioned protocol through a small JSON
+config. Use `assignment.effect_id(...)` for any irreversible external effect so
+a retry cannot repeat it. [Integrating agents](docs/integration.md) covers the
+adapters, the safety contract, telemetry, and safe adoption alongside an
+existing system; [`examples/`](examples/README.md) has copyable Python, CLI,
+HTTP, and real-agent integrations.
+
+## Documentation
+
+| Page | Contents |
+|---|---|
+| [How logplane works](docs/architecture.md) | Event log, identities, lifecycle, components, invariants, crash recovery, trust model |
+| [Operating logplane](docs/operations.md) | Commands, decisions, retries, cancellation, pauses, DAGs, scheduling, fairness, budgets |
+| [Integrating agents](docs/integration.md) | Python, CLI, and HTTP adapters, safety contract, telemetry, adoption modes |
+| [Event contracts and the HTTP API](docs/events.md) | Envelope, topics, limits, reading and publishing events |
+| [Local recovery operations](RECOVERY.md) | Artifact audits, backup and restore, task-index rebuilds, PM snapshots |
+| [Compatibility and support](COMPATIBILITY.md) | Platforms, versioned surfaces, upgrades, release checks |
+| [Roadmap](ROADMAP.md) and [release notes](RELEASE_NOTES.md) | Direction, remaining v1.0 gates, and what changed in each release |
+
+## Trust and scope
+
+logplane is for local, single-user orchestration on one trusted host:
+
+- **Perimeter auth is opt-in.** Set `LOGPLANE_TOKEN` to require a bearer token
+  on every data route; without it, anyone who can reach the port can publish.
+- **Actors are self-reported.** The token authenticates clients, not
+  identities, so any authorized client may publish as any actor, including
+  `pm`.
+- **It is not distributed.** Run one PM per bus and one uvicorn worker; the PM
+  lock is per machine and event wake-ups are per process.
+
+See the [trust model and scope](docs/architecture.md#trust-model) for details.
+
+## Development
+
+```sh
+python -m pip install -r requirements-dev.txt
+python -m pytest -q
+python -m build
+```
+
+The suite focuses on orchestration failures (restarts, stale attempts, retry
+exhaustion, races, DAG propagation, adapter contracts, telemetry isolation)
+and includes live runs of every demo. See
+[running the release checks](COMPATIBILITY.md#running-the-release-checks) for
+the full pre-release procedure.
+
+## Status and license
+
+logplane was called agent-bus before v0.13.0; if you used it under that name,
+follow the [migration steps](RELEASE_NOTES.md#migrating-from-agent-bus).
+
+Current release: **v0.13.0**, the rename to logplane and a `src/` layout. See the
+[release notes](RELEASE_NOTES.md) and the [roadmap](ROADMAP.md) for the path to
+v1.0. Licensed under the [MIT License](LICENSE). Copyright (c) 2026 deki. See
+[credits and acknowledgements](CONTRIBUTORS.md).