@aron98/load-lock 0.0.0-stage → 0.1.0

package/docs/AGENT_GUIDE.md

@@ -0,0 +1,142 @@
+# load-lock agent guide
+
+load-lock coordinates heavy work across all coding agents on this machine.
+Every session — any harness, any repo, any worktree — shares one machine-
+wide capacity budget. Before resource-intensive work, acquire a permit. The
+whole thing is cooperative: you decide what is heavy; the budget only works
+if everyone participates.
+
+This guide is also available as `load-lock agent-guide` and as a skill in
+supported harnesses.
+
+## 1. Deciding heavy vs light
+
+Judge by **expected** CPU/memory/IO cost, not by name:
+
+- **Heavy** (acquire first): builds, test suites, `cargo build`/`cargo
+  test`, `npm test`, container builds, migration runs, anything you expect
+  to saturate cores or memory for more than a few seconds.
+- **Light** (no permit): file edits, greps, reads, git status/diff, short
+  shell snippets, install/status probes, anything bounded and cheap.
+
+If in doubt about the machine's headroom, call `inspect_machine` — it
+reports effective cores and memory *including container/cgroup limits*
+(the machine may have 8 logical cores but a 2-core cgroup quota — never
+assume "N cores means N jobs") plus current load and memory pressure. Use
+`get_config`/`configure` when the budget genuinely needs adjustment.
+
+## 2. Core flow
+
+```
+acquire(reason, op_key)
+  ├─ granted  → you hold a permit → do the heavy work now
+  ├─ queued   → keep doing LIGHT work; offers reach you at your next
+  │             load-lock tool call, or via a wakeup message
+  └─ ...
+offer arrives (token, expiry) → claim(token) BEFORE the window closes
+claim → held → start the heavy work
+  best:  run_with_permit(permit_token, command)   # daemon tracks the process
+  else:  attach_pid(permit_token, pid)            # you started it yourself
+  else:  mark_started(permit_token)               # lease-based, weaker
+work finishes → release(permit_token)
+no longer needed while queued → cancel(request_id)
+offer arrived but you won't make it → decline(offer_token)
+```
+
+Rules, in order of importance:
+
+1. **Acquire immediately before** the heavy work — not at the start of a
+   long task.
+2. **While queued, continue useful light work** — read code, write plans,
+   make edits. Do not sleep or spin; offers are delivered to you.
+3. **Claim before starting.** Heavy work starts only after `acquire`
+   returned granted (or `claim` succeeded). A notification alone never
+   authorizes work.
+4. **Hold until the process truly finishes** — including background
+   execution. If the shell returned but the job still runs, you still hold
+   the permit (that is the point).
+5. **Release promptly** — success or failure. Release is idempotent; calling
+   it twice is safe, calling it after a crash-recovery release is safe.
+6. **Cancel** queued requests you no longer need, so someone else can have
+   the capacity.
+
+Notes on the details:
+
+- `op_key` makes duplicate acquires idempotent: if your pending request for
+  the same op already exists, `acquire` returns it instead of a second one.
+  Use a stable key per distinct operation (e.g. `build/auth-module`), and
+  different keys for different operations.
+- Offers have a **claim window** (default 30s). If it lapses, the request
+  becomes **paused** — capacity moves on and your request waits until you
+  explicitly `rejoin(request_id)`. If you know you can't start in time,
+  `decline` instead of letting it expire.
+
+## 3. Running heavy work (lifecycle options)
+
+How you start the work determines how reliably the permit cleans up after
+you — pick the best available:
+
+1. **`run_with_permit(permit_token, command)`** — the helper spawns your
+   command in its own process group, atomically associates it with the
+   permit, and auto-releases when the process group *actually finishes*
+   (including background children). Check `job_status(job_id)` for
+   completion/exit code/tail of output; `job_stop(job_id)` to kill it.
+   Do **not** manually release a permit you handed to `run_with_permit`.
+2. **`attach_pid(permit_token, pid)`** — you spawned the process yourself;
+   the daemon now tracks that pid (and its process group) and releases when
+   it is confirmed dead. Works for `... &` background jobs whose parent
+   shell exits.
+3. **`mark_started(permit_token)`** — no observable process (e.g. you call
+   an external service). The permit is held under a lease (default 15 min)
+   that is kept alive by heartbeats from your harness integration. Honest
+   limitation: if your agent process dies silently, the lease eventually
+   frees the capacity, but during that window nobody can guarantee the
+   unseen work has stopped. Prefer 1 or 2 whenever possible.
+
+If you `acquire` and get **granted** but then fail to start the work within
+the start deadline (default 120s), the permit is automatically reclaimed —
+nobody is stranded by a crashed claimant, and neither are you.
+
+The equivalent CLI forms exist for shell-driven flows:
+
+```sh
+load-lock acquire --reason "cargo test" --op-key "test/core"      # prints JSON
+load-lock run --permit <permit-token> -- cargo test --quiet       # tracks + releases
+# or acquire+run in one go:
+load-lock run --reason "nightly build" -- npm run build
+load-lock wait --id <request-id> --timeout 120000                # bounded wait → auto-claim
+```
+
+## 4. Reading state
+
+- `status(pool?)` — snapshot of the whole machine: holders (with phase,
+  reason, age), outstanding offers, queue depth, paused requests.
+- `pending()` — *your* requests and offers (with claim tokens).
+- `inspect_machine()` — cores/memory incl. cgroup limits, pressure.
+- `get_config()` / `configure(expected_version, changes, reason)` —
+  versioned CAS budget changes; every change is recorded with author and
+  rationale. On `version_conflict`, re-read and retry with the fresh
+  version.
+- Events have durable ids; after reconnects or restarts, consult
+  `events(since)` rather than assuming.
+
+## 5. Cleanup and failure etiquette
+
+| Situation | Do this |
+| --- | --- |
+| Work finished (success or failure) | `release` |
+| Queued request no longer needed | `cancel` |
+| Claim window will lapse before you can start | `decline` the offer |
+| Offer already expired (`offer_expired`) | `rejoin` when actually ready |
+| Your harness session is about to end with a live tracked job | Nothing — `run_with_permit`/`attach_pid` jobs release themselves when done |
+| You suspect a stuck holder | `status` → `recover list` diagnostics, and discuss with the operator before `force-release` |
+
+Never force-release someone else's permit without checking `recover list`
+first — a long hold with a live tracked process is working as intended.
+
+## 6. Suggested internal parallelism
+
+When you hold the permit, you own a share of the machine — bound your own
+work too: prefer e.g. `cargo test -j 2` or a bounded test-worker count over
+unbounded parallelism, and publish what you did via
+`configure(... guidance ...)` notes if it should become convention.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,195 @@
+# load-lock architecture
+
+load-lock is a cross-harness coordination plugin for parallel coding agents. It
+provides a machine-wide counting semaphore: before doing resource-intensive
+work (builds, test suites, long compiles), an agent acquires a permit; while
+queued it keeps doing light work; when capacity frees up it receives a FIFO
+offer, claims it, runs the heavy work, and releases. Coordination is
+cooperative and advisory — nothing wraps or rewrites shell commands, and agents
+decide for themselves what counts as "heavy".
+
+## Why a small dedicated service (vs extending something existing)
+
+We evaluated the existing landscape before building:
+
+- **WorkOS Airlock** (the closest name match) is a commercial, cloud-hosted
+  *authorization* gateway for agents: it approves or denies tool calls
+  (agent identity, intent, egress policies) via WorkOS Pipes. It answers "is
+  this agent allowed to do this?", not "does this machine have spare capacity
+  right now?". It has no machine-local state, no queue, no offers, and no
+  process-lifecycle tracking. Smaller GitHub projects named "airlock"
+  (an agent type-checker gate, an MCP egress allow-list) are similarly
+  unrelated.
+- **mic-lock** (npm) provides local sticky locks for shared test resources,
+  but it is a single lock with no counting semaphore, no FIFO queue, no
+  offer/claim protocol, no harness integration, and no automatic cleanup.
+- **flock-wrapper scripts** (advisory lock around a command) cannot work
+  across harness tool calls: the acquire step is a short-lived process that
+  must exit before the agent does its real work, releasing the lock with it.
+  A `flock` held by a process that has already exited protects nothing. (We
+  do use an flock-style spawn lock internally — for daemon bootstrapping —
+  but never for permits.)
+
+No existing project combines a counting semaphore, FIFO offers with claim
+tokens, per-agent identity, automatic permit cleanup tied to real process
+lifetimes, and harness instruction/notification adapters. The coordination
+state is small and its lifetime is the machine, not a repo — so a small
+dedicated daemon plus thin per-harness adapters is the right shape. Extending
+a larger system (e.g. a build tool) would couple the budget to one harness
+and inherit unrelated constraints.
+
+## Core design
+
+**One daemon, one budget.** A single `load-lock` daemon process per machine
+owns all state. Every client — any harness, any repo, any worktree — talks to
+the same Unix-domain socket, so all sessions share one capacity budget
+regardless of working directory. The default configuration is one pool
+`heavy` with capacity 1; pools, capacity, and timings are changed at runtime
+through `configure` (versioned compare-and-swap, persisted with author +
+reason). The state directory lives outside any checkout
+(`$XDG_STATE_HOME/load-lock`, default `~/.local/state/load-lock`, overridable
+via `LOAD_LOCK_STATE_DIR`).
+
+**Single-threaded atomicity.** The daemon is one Node process; every state
+mutation happens on one event loop turn. There is no interleaving between
+"check capacity" and "grant" — acquisition is atomic by construction, and
+there is no window in which a release can be missed between a failed check
+and queue registration. `acquire` either grants or registers in the queue in
+one operation; there is no separate failed-acquire/subscribe sequence that
+could miss a wakeup.
+
+**FIFO offers with claim tokens.** When capacity frees, the daemon reserves
+it and creates an offer for the head of the queue: an opaque claim token with
+an expiry (default 30s). The offer is delivered to the agent (see
+notifications below); heavy work starts only after a successful `claim`,
+which atomically converts the offer into a permit. Outstanding offers consume
+capacity, so an unclaimed offer cannot admit a second agent over budget. If
+the offer expires, capacity passes to the next waiter and the expired request
+becomes **paused** — it will not be re-offered until the agent explicitly
+`rejoin`s. This prevents endless recycling of offers to absent agents.
+
+**Permit lifecycle (automatic cleanup).** A permit moves through phases:
+
+1. **Claimed, awaiting execution** — has a configurable start deadline
+   (default 120s). If execution never starts, the permit is reclaimed.
+2. **Running, tracked** — associated with a real OS process via
+   `attach_pid`/`run_with_permit` (pid + process-group id + `/proc` start
+   time). The permit lives as long as the associated job: parent shells may
+   exit, background children keep the group alive, and the daemon
+   auto-releases only on confirmed termination. It is never auto-expired
+   merely because time passed. PID reuse is defended by comparing
+   `/proc/<pid>/stat` start times.
+3. **Running, untracked** — `mark_started` for jobs the daemon cannot
+   observe. Held under a lease (default 15 min) kept alive by heartbeats
+   (the MCP server and OpenCode plugin heartbeat automatically every 30s).
+   This is an explicit tradeoff: a lease cannot simultaneously guarantee
+   prompt reclamation and never overlap an unobserved surviving process.
+   We reclaim when the owner stops heartbeating, and we document the
+   residual risk instead of claiming a guarantee we can't make.
+
+Explicit `release` always remains available and is idempotent (a duplicate or
+late release is a no-op, not an error). `admin release` / `recover
+force-release` exists for humans with holder/job diagnostics.
+
+**Association is atomic.** `run_with_permit` spawns the job (its own process
+group) and only then associates pid+pgid with the permit in a single daemon
+operation; a reclamation racing the start loses cleanly (stale token /
+wrong-state error), and a failed start kills the process group immediately.
+Background execution is handled honestly: the helper returns after *the whole
+process group* finishes, never merely when a shell returns a task id.
+
+**Identity.** Per-agent identity comes from the harness (OpenCode session ID)
+or an explicit `agent_id` argument; every entry also records an agent label,
+cwd, op key (for idempotent duplicate suppression), and reason. Idempotency:
+a duplicate `acquire` from the same agent for the same pending op key returns
+the existing request rather than a second one; multiple distinct ops per
+agent are supported. All tokens (permits, offers) are opaque; releasing or
+claiming with someone else's token fails.
+
+**Restart behavior.** Config is persisted (atomic write + rename). Held
+permits are journaled: on daemon restart, tracked permits are reconciled
+against real process liveness (dead ⇒ released, alive ⇒ kept, same tokens
+still valid), claimed permits keep their original start deadline, untracked
+permits get a fresh lease window, and a release arriving late for an entry
+that was reconciled is idempotent. Queues and offers are *not* journaled:
+they are ephemeral by design — queued agents are still running, notice the
+missed offer via their next tool call, and re-acquire; the daemon
+auto-spawns on the next client connection, so an agent never needs to know
+the daemon restarted. This is documented, deliberate behavior, not a bug.
+
+## Notification honesty
+
+A critical constraint discovered by research: **no harness reliably pushes
+MCP-server-initiated notifications into model context.** MCP transports
+having a notification mechanism says nothing about whether the harness wakes
+an idle agent or injects into context. load-lock therefore uses four
+mechanisms, and labels exactly which apply per harness:
+
+1. **Tool-boundary delivery (always available).** Every load-lock tool
+   result and every `status`/`pending` call carries the caller's current
+   offers (with claim tokens) — an agent performing light work discovers its
+   offer at its next tool call, without polling.
+2. **Bounded blocking wait.** `acquire(wait_ms)` blocks briefly (default
+   5s) inside the tool call and auto-claims if capacity frees during the
+   wait. The CLI `wait` command and MCP `wait` pattern provide longer
+   bounded waits. No model-authored busy-polling required.
+3. **Idle wakeup where the harness genuinely supports it.**
+   - OpenCode (live-verified): the native plugin watches daemon events and
+     calls `ctx.session.synthetic(...)`, delivering the offer (with token)
+     to an idle session at its next execution boundary — it never
+     interrupts an in-flight shell command.
+   - Claude Code (contract-tested): a `Stop` hook checks for cwd-matching
+     offers and continues the session with a claim instruction; an async
+     `await-offer` watcher with `asyncRewake: true` wakes idle sessions.
+   - Codex CLI (contract-tested): `Stop` hook with `decision: "block"`
+     continuation. Note: Codex async background hooks do **not** start a new
+     turn — documented as a limitation.
+4. **Durable event identities.** All events have monotonic IDs; agents can
+   pull owner-filtered events since a cursor and deduplicate after reconnect
+   or daemon restart. A notification NEVER grants permission — only
+   `claim(offer_token)` does; expired offers are rejected and stale
+   notifications authorize nothing.
+
+## Instruction delivery (policy teaching)
+
+The behavioral policy (acquire before heavy work, keep doing light work
+while queued, claim before starting, hold until the process truly finishes,
+release promptly, cancel unneeded work, use inspect/configure when the
+budget needs adjustment) is delivered per harness using its real mechanism,
+and restored after context compaction:
+
+- **OpenCode**: plugin `context` hook injects the brief on every model call
+  (compaction-proof, live-verified), plus a registered skill with the full
+  guide.
+- **Claude Code**: `SessionStart` hook (matchers include `compact`) +
+  `~/.claude/CLAUDE.md` section + skill.
+- **Codex CLI**: `SessionStart` hook (matcher `compact`) + `SubagentStart`
+  hook + `~/.codex/AGENTS.md` section (hooks require `/hooks` trust review).
+- Other harnesses: MCP server `instructions` + a global instructions file
+  snippet where the harness supports one (see COMPATIBILITY.md).
+
+Policy is short (one brief, no repeated reminders), reinforced by tool
+names/descriptions, and never interrupts ordinary work with approval
+prompts.
+
+## Failure modes covered
+
+| Failure | Behavior |
+| --- | --- |
+| Agent disconnects mid-heavy-work | Permit retained; tracked job keeps capacity until the real process finishes; untracked job's lease survives until heartbeats stop |
+| Agent process crashes | Tracked permit auto-releases on confirmed process death; untracked reclaims after lease expiry |
+| Background job outlives the tool call | pgid tracking retains the permit until the whole group exits |
+| Daemon crash/restart | Auto-respawn on next connect; journal reconciliation of held permits (conservative: dead ⇒ released, alive ⇒ kept); queues/offers ephemeral by design |
+| Stale/forged token | Opaque tokens; wrong-owner claim/release rejected; expired offers rejected with a precise error |
+| Forgotten release | start deadline (claimed), process death (tracked), lease expiry (untracked), plus human `recover force-release` |
+| PID reuse | `/proc` start-time comparison |
+| Config change while offers outstanding | Capacity increase admits queued agents immediately; capacity decrease lets holders finish and delays new admissions; outstanding offers keep their reservations |
+| Duplicate claims/releases | Idempotent or precise `stale_token`/`offer_expired` errors, never double effects |
+
+## Extension points
+
+The protocol already carries weights (a request may ask for >1 units of
+capacity; admission is FIFO with head-of-line blocking) and multiple pools;
+the machine currently uses one pool by default but accepts arbitrary pool
+names through the same code paths. Adding a second budget (e.g. `network`)
+is configuration, not code.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,116 @@
+# Harness compatibility matrix
+
+load-lock separates **core capability** (daemon + protocol + CLI, fully
+harness-agnostic) from **per-harness integration** (tools, policy
+instruction injection, compaction restore, idle wakeup, lifecycle help).
+Status labels mean exactly this:
+
+- **Implemented + live-verified** — deployed on this machine and exercised
+  end-to-end against the real harness.
+- **Implemented + contract-tested** — adapter shipped; behavior tested
+  against the harness's documented hook/tool JSON contracts
+  (`src/test/hook.test.ts`, `src/test/mcp.test.ts`), but the harness itself
+  was not installed during verification.
+- **Proposed / fallback** — research-verified harness capabilities only; no
+  adapter shipped beyond the generic MCP path.
+
+## Core (all harnesses)
+
+| Capability | Status |
+| --- | --- |
+| Machine-wide pool, atomic acquire, FIFO offers, claim tokens, expiry → paused → rejoin | Implemented + tested (`core.test` 14, `daemon.test` 8) |
+| Idempotent acquire/release, duplicate suppression, weighted head-block | Implemented + tested |
+| Automatic cleanup: start deadline, tracked pgid process death, untracked lease, heartbeats, PID-reuse defense | Implemented + tested with real processes |
+| Daemon restart: journal reconciliation, idempotent late release, ephemeral queues | Implemented + tested |
+| Config via tools, CAS versions, persisted history with author+reason | Implemented + tested |
+| Resource inspection incl. cgroup v2/v1 CPU+memory limits and pressure | Implemented + tested |
+| CLI: acquire/claim/release/run/wait/status/configure/doctor/recover/install | Implemented + tested + demoed |
+
+## Per-harness integration
+
+| Harness | MCP tools | Policy injection | Compaction restore | Idle wakeup | Async push into context | Cleanup fidelity | Overall |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| **OpenCode** (v2) | Native plugin, `load_lock_*` (better than MCP) | Context hook every model call | Yes (hook re-fires per model call) | Yes — `session.synthetic` at execution boundary (live-verified; never interrupts in-flight shell) | Yes (live-verified) | Full: `run_with_permit` tracked jobs + session heartbeats | **Implemented + live-verified** |
+| **Claude Code** | MCP `mcp__load-lock__*` (user scope) | `SessionStart` hook plain-stdout context | Yes (SessionStart matcher `compact`) | Yes — `Stop` hook decision-block + async `await-offer` (`asyncRewake`) | Yes, via asyncRewake (contract-tested) | Full via MCP `run_with_permit` + server heartbeats | **Implemented + contract-tested** |
+| **Codex CLI** | MCP `mcp__load-lock__*` (config.toml) | `SessionStart` + `SubagentStart` additionalContext; `~/.codex/AGENTS.md` | Yes (SessionStart matcher `compact`) | Yes — `Stop` hook `decision:"block"` continuation | Partial: async background hooks do NOT start a new turn (documented limitation); stop-hook covers turn boundaries | Full via MCP `run_with_permit` + server heartbeats | **Implemented + contract-tested** (hooks need `/hooks` trust review) |
+| **Gemini CLI** | Yes (`settings.json` mcpServers) | `GEMINI.md` global (config `context.fileName`) | Via global GEMINI.md (always loaded) | No hook mechanism exists | No | Via MCP `run_with_permit` only | Proposed (MCP fallback) |
+| **GitHub Copilot CLI** | Yes (`copilot mcp add`) | AGENTS.md/GEMINI.md discovery + custom instructions | Via global instructions file | Hooks reported in ecosystem content but **not verified in official docs** — treat as unavailable | Unverified | Via MCP `run_with_permit` only | Proposed (MCP fallback) |
+| **Cursor** | Yes (`.cursor/mcp.json` + global) | `.cursor/rules/*.md` Always rules | Rules re-apply (Always) | `stop` hook exists but **beta** with a less-documented JSON contract — not shipped | Beta/unverified | Via MCP `run_with_permit` only | Proposed (MCP fallback; hook tier possible later) |
+| **Cline** | Yes (`cline_mcp_settings.json`) | `.clinerules/` + `~/.cline/rules` | Rules always loaded | No hooks | No | Via MCP `run_with_permit` only | Proposed (MCP fallback) |
+| **Roo Code** | Yes (Roo MCP settings) | `.roo/` rule dirs | Rules always loaded | No hooks | No | Via MCP `run_with_permit` only | Proposed (MCP fallback) |
+| **Goose** | Yes (`~/.config/goose/config.yaml`) | `.goosehints` (global + project) | Hints always loaded | No hooks | No | Via MCP `run_with_permit` only | Proposed (MCP fallback) |
+| **Aider** | **No MCP support** | CONVENTIONS.md / `.aider.conf.yml` | Read each run | N/A | N/A | CLI-only: same-shell `load-lock acquire ... && cmd; load-lock release ...` (manual) | Proposed (manual CLI tier) |
+
+## How each integration tier works
+
+### Tier 1 — OpenCode (native plugin, live-verified)
+
+Global plugin (`load-lock install --harness opencode`) registers:
+- `load_lock_*` tools with session-bound agent identity and cwd,
+- the policy brief injected into system context on **every** model call
+  (survives compaction by construction),
+- a `load-lock` skill with the full agent guide,
+- daemon event watcher → `ctx.session.synthetic` offer messages with the
+  real claim token, delivered at execution boundaries,
+- per-session heartbeats.
+
+Verified live on opencode v2.0.29: plugin load, policy visible to the model,
+tool round-trip (acquire → queued → wakeup → claim → release), execution-
+boundary delivery without interrupting a running `sleep`, skill visible,
+and graceful handling of a deliberately missed offer (paused → cancel).
+
+### Tier 2 — Claude Code / Codex CLI (hooks + MCP, contract-tested)
+
+`load-lock install --harness claude-code|codex` configures the MCP server
+(user scope) plus hooks:
+
+- **SessionStart** → policy brief + machine summary as developer context
+  (matchers include `compact` so it re-fires after auto-compaction).
+- **SubagentStart** (Codex) → same for spawned subagents.
+- **Stop** → if the daemon has an offer whose entry cwd matches the session
+  cwd, the hook continues the session with a claim instruction (decision
+  block). Honors `stop_hook_active` to avoid loops; silent otherwise.
+- **await-offer** (Claude Code, `async: true, asyncRewake: true`) → watches
+  daemon events; on a matching offer exits 2 with a message that wakes an
+  idle Claude. The token is deliberately NOT in that message (stderr may be
+  shown); the agent claims via `pending`/`claim`.
+
+Contract tests cover all hook stdin/stdout shapes against the documented
+harness contracts. Live verification pending a machine with the harness
+installed. Codex requires the user to trust the hooks once via `/hooks`
+(the installer prints this).
+
+### Tier 3 — MCP-only fallback (Gemini CLI, Copilot CLI, Cursor, Cline, Roo Code, Goose)
+
+The MCP server itself carries the policy in its `instructions`, every tool
+result surfaces pending offers (tool-boundary delivery), and
+`inspect_machine`/`get_config`/`configure` work unchanged. Where the harness
+supports global instruction files (GEMINI.md / AGENTS.md / rules / hints),
+`load-lock install --harness generic` prints a snippet to add. Missing:
+idle wakeup and automatic context re-injection — queued agents discover
+offers at their next tool call or via a bounded `wait`. This is the honest
+fallback; we do not pretend these harnesses got push notifications.
+
+### Tier 4 — Aider (manual CLI)
+
+No MCP/hooks; nothing to install. Agents (or humans) use the CLI directly in
+the shell: `load-lock acquire ... && load-lock run -- <cmd>` handles
+acquire→run→release in one command line.
+
+## Session identity per harness
+
+| Harness | Identity | Notes |
+| --- | --- | --- |
+| OpenCode | plugin context `sessionID` (also MCP `_meta` when used) | automatic |
+| Claude Code | hooks get `session_id`; MCP tools take explicit `agent_id` | policy instructs agents to pass it |
+| Codex | hooks get `session_id`; MCP tools take explicit `agent_id` | same |
+| Tier 3 | explicit `agent_id` argument | falls back to per-server-process id |
+
+## Verified vs proposed — summary counts
+
+- Live-verified: OpenCode (full adapter, including wakeup).
+- Contract-tested: Claude Code, Codex CLI hook/MCP contracts.
+- Core daemon/protocol/CLI: 32 automated tests + scripted 3-worktree demo
+  (three independent agent processes, real git worktrees, one pool).
+- Proposed (researched capabilities, generic adapter only): Gemini CLI,
+  Copilot CLI, Cursor, Cline, Roo Code, Goose, Aider.

package/docs/OPERATIONS.md

@@ -0,0 +1,126 @@
+# Operating load-lock
+
+## Install
+
+Requirements: Node 20+, Linux (macOS works with the limitations noted below;
+Windows would need a named-pipe adapter — not implemented).
+
+```sh
+npm install -g @aron98/load-lock    # or: npm install -g ./aron98-load-lock-<ver>.tgz
+load-lock install --harness opencode
+load-lock install --harness claude-code
+load-lock install --harness codex
+load-lock install --harness generic   # prints MCP snippets for other harnesses
+```
+
+What each installer does (all merges are non-destructive; uninstall removes
+exactly the entries it added):
+
+- **opencode** — writes a plugin stub to
+  `~/.config/opencode/plugins/load-lock/` (npm-installed against the global
+  package), registers it in `~/.config/opencode/opencode.json`.
+- **claude-code** — adds `mcpServers.load-lock` to `~/.claude.json`; hooks
+  (`SessionStart`, `Stop`, async `await-offer`) to `~/.claude/settings.json`;
+  a marked section to `~/.claude/CLAUDE.md`; copies the skill to
+  `~/.claude/skills/load-lock/`.
+- **codex** — writes `~/.codex/hooks.json` (`SessionStart`, `SubagentStart`,
+  `Stop`), appends `[mcp_servers.load-lock]` to `~/.codex/config.toml` if
+  absent, adds a marked section to `~/.codex/AGENTS.md`. **Then run `/hooks`
+  inside Codex once to trust the hooks.**
+- **generic** — prints MCP stdio config snippets (Gemini CLI, Cursor,
+  Cline/Roo, Goose) plus a suggested instructions-file section.
+
+`load-lock uninstall --harness <harness>` reverses any of these.
+
+## The daemon
+
+- State dir: `~/.local/state/load-lock` (override `LOAD_LOCK_STATE_DIR`).
+- Socket: `<state dir>/daemon.sock` (override `LOAD_LOCK_SOCKET`).
+- **Auto-spawns** on first client connection; no service unit needed.
+- Files: `config.json` (settings + history), `journal.json` (held permits),
+  `daemon.json` (pid), `spawn.lock` (bootstrap race guard).
+
+```sh
+load-lock service status   # hello + pid
+load-lock service start    # ensure running (idempotent)
+load-lock service stop     # SIGTERM; next tool call respawns
+```
+
+## Configuration
+
+All configuration is agent-editable through tools (no file editing for
+ordinary use) — MCP `configure` / plugin `load_lock_configure` /
+`load-lock configure`. Updates are compare-and-swap on a version number
+(`expected_version` prevents silent overwrites), validated, persisted with
+author + reason, and appended to a visible history (last 50 changes).
+
+```sh
+load-lock configure --capacity 2 --reason "host has 16 cores" --author ops
+load-lock configure --offer-timeout-ms 60000 --reason "model turns can be slow" --author agent
+load-lock get-config
+```
+
+Defaults: one pool `heavy` capacity 1 · offer window 30s · blocking wait 5s ·
+start deadline 120s · untracked lease 15min. Valid ranges:
+offer window 1s–10min, wait 0–10min, start deadline 1s–1h, lease 10s–24h.
+
+Semantics of changes:
+
+- **Capacity increase** — queued requests are admitted immediately (FIFO
+  offers); outstanding offers keep their reservations.
+- **Capacity decrease** — current holders finish untouched; new admissions
+  are delayed until usage fits.
+
+`inspect_machine` reports logical cores, cgroup v2/v1 CPU quota and memory
+limits (containers respected — we never assume 2 cores means 2 jobs),
+available memory, and current load/memory pressure with an advisory
+suggestion. Agents are expected to consult it before proposing capacity.
+
+## Diagnostics & recovery
+
+```sh
+load-lock doctor            # state dir, socket, daemon reachability, effective cores, pressure
+load-lock status            # human view: usage, holders w/ phase+pid, offers, queue, paused
+load-lock pending           # your own offers/queue entries (JSON)
+load-lock events --follow   # durable event log (grants, offers, releases, reclaims...)
+load-lock recover list      # holder diagnostics: tracked? alive? age, long-hold flags
+load-lock recover force-release --id <request-id>   # admin release (prints holder/job info)
+```
+
+Recovery policy summary:
+
+- Held permits with a tracked live process are **never** revoked for being
+  old — long holds are flagged in diagnostics, nothing more.
+- A tracked permit auto-releases when its process (or process group) is
+  confirmed dead — including background children that outlived the shell.
+- A claimed-but-never-started permit is reclaimed after the start deadline.
+- An untracked (`mark_started`) permit lives under a heartbeat lease; if the
+  owning agent (MCP server / plugin / CLI heartbeat) disappears, it is
+  reclaimed after the lease. Residual risk of overlap with an unobserved
+  surviving process is documented — use `attach_pid`/`run_with_permit`
+  whenever possible for real guarantees.
+- After a daemon restart, `journal.json` reconciles held permits against
+  actual process liveness (dead ⇒ released, alive ⇒ kept with same tokens).
+  Queued/offered requests are not journaled — agents re-acquire; this is
+  intentional and safe.
+
+## Troubleshooting
+
+| Symptom | Check / fix |
+| --- | --- |
+| Tools hang | `load-lock doctor`. Daemon down? It auto-spawns; if the socket file is stale it is detected and replaced automatically. |
+| `offer_expired` on claim | Claim window elapsed (default 30s) — the request is paused; `rejoin` it and claim promptly. Consider a longer `--offer-timeout-ms`. |
+| Agent got "undefined" wakeup / no offer | Offers match the cwd recorded at acquire time; verify with `load-lock pending`. Claude Code/Codex wakeups require cwd match between hook session and acquire call. |
+| Capacity seems stuck | `status` + `recover list`: look for untracked leases (`[untracked, leased]`), long holds, or dead holders awaiting sweep (runs every 5s). Use `force-release` with the printed request id. |
+| Codex hooks never fire | Run `/hooks` in Codex and trust the load-lock entries; check `[features] hooks` is not disabled. |
+| Claude Code doesn't wake when idle | The async `await-offer` hook must be in `~/.claude/settings.json` with `async: true, asyncRewake: true` — verify with `load-lock doctor` / inspect the file. |
+| Config change lost | Configuration is CAS-versioned: fetch `get_config`, retry with the fresh `version` on `version_conflict`. |
+| After OS reboot | Nothing to do: state dir persists config; daemon respawns on first use; journal reconciliation releases permits whose processes died. |
+
+## macOS / Windows notes
+
+- macOS: no cgroup limits; process-liveness checks fall back from
+  `/proc/<pid>/stat` start times to `kill(pid, 0)` (weaker PID-reuse
+  defense — document and prefer `run_with_permit`). Everything else works.
+- Windows: Unix-domain sockets are not used; a named-pipe transport adapter
+  would be required (planned, not implemented).