0.2.0: ledger precheck + events:batch, run_state, data_scope (TokenOps remote-only)

[susheem-k]

Phase 1 of the TokenOps remote-only effort. Closes #10. Companion: theagentplane/tokenops#118.

Additive — nothing removed. A 0.1-era client keeps working against this. The
destructive fold (drop run_registrations, remove create_run, narrow PATCH) is
split out to #11 and ships as 0.3.0 after tokenops <next> — not needed for the
decoupling.

What's here

POST /v1/ledger/events:batch	batched writes: spent_add (multi-target fan-out), admit/complete, step, halt_mark/halt_clear; array order, one transaction, idempotent per idempotency_key (ledger_events table); ack returns totals + halted
POST /v1/ledger/precheck	one read for a pre_call pass — halt + requested spent / inflight / window slices
run_state table	per-run step_count / bounded window ring (64) / velocity, fed by step events
policy_instances.data_scope	local|global (default local) — schema, migration ALTER, serde, PUT /v1/policies, YAML seed, emitted in GET /v1/governance/{agent}
POST /v1/runs	returns the full record incl. registered_at — SDK binds without a follow-up GET .../registration
PATCH /v1/run-records	client-sent steps / cost_micros are ignored + logged (derived server-side; 0.3.0 rejects)
GET|POST|DELETE /v1/ledger/runs/{run_id}/halt	run-scoped halt; /v1/ledger/halt/* kept as aliases
GET /health	advertises max_batch / max_body_bytes
PRAGMA user_version	forward-only _apply_migrations() (SCHEMA_VERSION = 2); opening a 0.1 DB adds the new tables/column, bumps the version, no data loss. v3 = the #11 fold
docs/api-contract.md	the ratified TokenOps ⇄ control-plane wire spec
test infra	make_client fixture closes SQLite before temp-dir cleanup — the suite was fully red on Windows before this (open handles → WinError 32); test_health.py / test_envelopes.py migrated onto it

Tests

test_ledger_events.py (10), test_ledger_precheck.py (6), test_data_scope.py (5),
test_runs_and_halt.py (5), test_migrations.py (3, incl. a legacy user_version=0
DB upgrading additively). Full suite: 34 passed. ruff check clean.

Also in this PR: control-plane start / stop / status (Tier 1 one-click run)

Running the plane locally is now a prerequisite for TokenOps's remote-only work, so
this adds a managed background mode instead of requiring a dedicated terminal tab:

control-plane start    # detached, waits for /health before returning, prints pid + log path
control-plane status   # pid, port, version
control-plane stop     # terminate() -> kill() on timeout

• Singleton per state dir (platformdirs user-state dir); all three are idempotent.
• PID trust is verified (cmdline() match), not assumed — PIDs get reused by the OS.
• Cross-platform detach: start_new_session (POSIX) / DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP (Windows).
• start never lies: polls /health, kills and reports the log tail if the process never comes up.
• Documented limitation: Windows has no SIGTERM, so stop there is a hard stop, not a graceful drain.
• New deps: psutil, platformdirs.

tests/test_servicectl.py — real integration tests, no mocking of the OS layer: spawns
an actual subprocess, hits real HTTP. Full lifecycle (start → /health → status → stop
→ confirm the process actually exited), idempotent start/stop, stale-state-file
recovery, and a smoke pass over the real TokenOps-facing routes (/v1/runs,
/v1/governance, /v1/ledger/events:batch, /v1/ledger/precheck,
/v1/ledger/runs/{id}/halt) through the managed instance. The Windows detach/terminate
path was verified manually (this repo's CI is Ubuntu-only).

Full suite now: 42 passed. ruff check clean.

Not in this PR

• Idempotency-Key header on the legacy single-op spent/add + inflight/* writes —
  those are 0.3.0: destructive cleanup — fold run_registrations, remove create_run + legacy ledger wrappers #11-removal fodder and the SDK writes via events:batch.
• Everything in 0.3.0: destructive cleanup — fold run_registrations, remove create_run + legacy ledger wrappers #11 (the 0.3.0 destructive fold).

🤖 Generated with Claude Code