@aron98/load-lock 1.5.0 → 1.6.0

package/docs/ARCHITECTURE.md

@@ -99,8 +99,13 @@ 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,
+**Identity.** Per-agent identity is derived from the harness session
+(issues #49/#50): an explicit `agent_id` / `--agent` / `LOAD_LOCK_AGENT`
+wins, else a harness session id (OpenCode `sessionID`, Claude Code
+`CLAUDE_CODE_SESSION_ID`, hook `session_id`), else the stable harness
+ancestor process on Linux, so every wiring of one session (CLI, MCP
+server, hooks) acts as one agent (details in
+[COMPATIBILITY.md](COMPATIBILITY.md#session-identity-per-harness)); 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
@@ -118,10 +123,86 @@ same request ids (idempotent re-acquire keeps working), entries offered at
 crash time restart as queued and are re-offered with fresh tokens — so a
 restart no longer silently drops a queue position. The daemon auto-spawns on
 the next client connection, and a *self-ordered* restart (version handshake:
-a newer client than the daemon) respawns with the same argv after persisting
-state — see the update lifecycle in
+a newer client than the daemon) persists state and respawns onto the newer
+client's copy (#53; same argv when that copy can't be validated) — see the update lifecycle in
 [OPERATIONS.md](OPERATIONS.md#update-lifecycle).
 
+**Persisted format compatibility (issue #51).** Several runtime copies may
+share one state dir, so a downgrade is possible: a newer daemon dies and an
+older client starts its older copy, which must then load files the newer one
+wrote. `config.json` carries a top-level `formatVersion` (absent = 0, the
+pre-versioning format); the journal stays a bare JSON array (what every
+released daemon reads) with `formatVersion` stamped on each entry. The
+promise, in both directions:
+
+- Format changes are **additive**. A reader never rejects a file because its
+  `formatVersion` is higher than its own; it uses what it understands.
+- Unknown fields are **never dropped destructively**: top-level and
+  `config`/pool/guidance fields of `config.json` survive a rewrite (e.g. a
+  `configure`), and unknown fields on a journal entry are written back while
+  that entry lives. Each writer stamps its *own* `formatVersion`, so readers
+  must treat fields from a newer format as possibly stale.
+- Unknown journal entry kinds (a `state` this version doesn't know) and
+  malformed entries are **skipped**, never fatal; the count is reported in the
+  `daemon_recovered` event. A held entry with an unknown `phase` is kept as an
+  untracked permit with a fresh lease (capacity stays accounted; the lease
+  reclaims it if nobody heartbeats).
+- An incompatible change would use a **new file name**, never reinterpret
+  `config.json` / `journal.json`.
+
+## Three layers: daemon, runtime copies, harness wiring
+
+load-lock reaches a machine through many entry points (a skill, an MCP
+registration, a harness plugin, ACE, `npm i -g` + `load-lock install`), and
+users mix them across harnesses and over time. The design rule (issue #47):
+**any combination, installed in any order, gives one working budget.** It
+holds because load-lock is split into three layers with different
+multiplicity:
+
+| Layer | Per machine | What it is | Rule |
+| --- | --- | --- | --- |
+| **Daemon** | exactly 1 (one socket, one state dir) | the long-lived process that owns all state, started on demand by whichever client connects first (`src/shared/client.ts`) | the newest copy runs it |
+| **Runtime copies** | many | installed copies of the npm package: global npm/bun, the npx cache, OpenCode's plugin cache, a git checkout; the Claude Code plugin's launcher picks one of them | copies interoperate in both directions; none "owns" the daemon |
+| **Harness wiring** | ideally 1 per harness, possibly several | MCP registrations, hooks, policy text, skill copies, written by a plugin, ACE, `load-lock install` or by hand | duplicates are **harmless**, not merely discouraged |
+
+**Duplicates are harmless.** Each overlap is defused where the singleton
+lives, not by hoping the user cleans up:
+
+- *Hooks*: two wirings of the same hook (loose + plugin, two plugins, ACE)
+  both fire, but the daemon's `hook_once` lets only the first act — one
+  policy injection, one Stop continuation, one idle watcher per session
+  (see "Duplicate hook wiring is harmless" below).
+- *MCP servers*: two registrations in one session (e.g. ACE's `mcp.json` +
+  the plugin's bundled server) are two processes with the **same**
+  session-derived identity (see Identity above), so an `acquire` through
+  one shows up in `pending` through the other. Both talk to the one daemon.
+- *Skill copies*: identical text; the skill only tells the agent how to
+  reach the daemon.
+
+Housekeeping is still offered: `load-lock setup` lists every integration
+per harness and, with `--yes`, converges each harness to one wiring at its
+highest rung (see [OPERATIONS.md](OPERATIONS.md#load-lock-setup-what-is-installed-where)).
+Correctness never depends on running it.
+
+**Compatibility promise between copies.** Because several copies of
+different versions talk to one daemon and one state dir:
+
+- every client envelope carries its version and package root; a strictly
+  newer client makes the daemon persist state and respawn onto that
+  client's copy (#52/#53, see "Runtime copies and the restart hint"
+  below), with one attempt per version;
+- the persisted files are versioned and additive in both directions, so
+  an older daemon started after a newer one died reads the newer files
+  safely (#51, "Persisted format compatibility" above);
+- newer client features degrade against an older daemon instead of
+  failing: hooks without `hook_once` act as before, `wait_for_completion`
+  falls back to an events-based poll.
+
+The **install ladder** built on top of this (skill → MCP server → harness
+plugin, plus `npm i -g` + `load-lock install`) is described in
+[OPERATIONS.md](OPERATIONS.md#the-install-ladder); which rung each harness
+reaches is in [COMPATIBILITY.md](COMPATIBILITY.md#rung-per-harness).
+
 ## Notification honesty
 
 A critical constraint discovered by research: **no harness reliably pushes
@@ -168,7 +249,8 @@ mechanisms, and labels exactly which apply per harness:
      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
+   - Claude Code (live-verified in Docker with the loose install; the
+     plugin's hooks are not yet live-verified, #63): 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 (live-verified in Docker): `Stop` hook with `decision: "block"`
@@ -191,8 +273,10 @@ 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.
+- **Claude Code**: `SessionStart` hook (re-fires after `compact`), from
+  either the `load-lock-plugin` plugin or the loose install; the loose
+  install adds a `~/.claude/CLAUDE.md` section + skill, the plugin ships
+  neither (full guide via the `agent_guide` MCP tool).
 - **Codex CLI**: `SessionStart` hook (matcher `compact`) + `SubagentStart`
   hook + `~/.codex/AGENTS.md` section (hooks require the interactive
   hook-trust review once; live-verified in Docker).
@@ -203,6 +287,21 @@ Policy is short (one brief, no repeated reminders), reinforced by tool
 names/descriptions, and never interrupts ordinary work with approval
 prompts.
 
+**Duplicate hook wiring is harmless (issue #54).** Loose hooks, a plugin
+and ACE wiring may all be installed at once, so one harness event can fire
+the same load-lock hook several times. The daemon is the singleton, so it
+drops duplicates: each hook handler first calls `hook_once` with the key
+`(harness, session_id, event, occurrence)`; only the first caller acts, the
+rest exit 0 silently. The occurrence separates legitimate repeats:
+SessionStart uses its `source` (a later `compact` re-injects the policy),
+Stop hooks (Claude Code, Codex, Cursor) use the offer token being delivered
+(each offer becomes at most one continuation per session). Keys expire on
+their own (default 60s) and are never persisted; the `await-offer` watcher
+instead *holds* its key for its connection's lifetime, so a session has at
+most one live watcher and the key frees when the watcher exits. Hooks fail
+open: no session id, a daemon without `hook_once` (`unknown method`), or
+any error means the hook acts exactly as before.
+
 ## Failure modes covered
 
 | Failure | Behavior |
@@ -217,6 +316,22 @@ prompts.
 | 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 |
 
+### Runtime copies and the restart hint
+
+`daemon.json` records the daemon's package root and version, and
+`runtimes.json` the copies seen via the handshake (#52). When a strictly
+newer client connects, the daemon respawns onto that client's copy (#53)
+if the envelope's `clientRoot` names a `@aron98/load-lock` package whose
+on-disk version equals the claimed `clientVersion` and which ships
+`dist/core/daemon-main.js`; otherwise it reruns its own argv. The
+`LOAD_LOCK_RESTARTED_FOR` marker keeps one restart per version either way.
+
+Security: the hint arrives over the daemon's socket, which only the same
+user can reach. Following it grants no privilege the client did not
+already have — that client could run the same file itself. The checks
+exist to avoid respawning onto garbage (wrong package, mismatched version,
+missing entry), not as a trust boundary.
+
 ## Extension points
 
 The protocol already carries weights (a request may ask for >1 units of

package/docs/COMPATIBILITY.md

@@ -46,6 +46,30 @@ Status labels mean exactly this:
 | **omac** (agent sandbox; verified with 0.11.0) | N/A — omac is a sandbox runtime, not a harness: the agent inside it uses whichever harness adapter applies (OpenCode, Claude Code, …) | via the inner harness | via the inner harness | via the inner harness | via the inner harness | Full for the sandbox grants: `load-lock uninstall --harness omac` removes exactly the entries install added (match-own-entries, empty sections pruned) | **Sandbox-profile grants installed + live-verified** (`install --harness omac`: `filesystem.allow_unix_dir` += state dir, `filesystem.read` += package tree when needed, `environment.allow_vars` += `LOAD_LOCK_*`) |
 | **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) |
 
+## Rung per harness
+
+The install ladder (OPERATIONS.md, "The install ladder") has rungs 0 = skill
+only, 1 = MCP server, 2 = harness plugin, plus the loose
+`npm i -g` + `load-lock install --harness <h>` wiring. **Rung 0 works
+everywhere** an agent can read the skill and run a shell: it only needs
+the CLI (on PATH or through the skill's pinned `npx`), so it is not
+repeated per row. `load-lock setup` reports the rung it finds per harness
+as `plugin`, `loose`, `MCP only`, `skill only` or `not installed`.
+
+| Harness | MCP server (1) | Plugin (2) | Loose `install` | Highest rung |
+| --- | --- | --- | --- | --- |
+| **OpenCode** | generic stdio registration works; the plugin's native `load_lock_*` tools are better | npm plugin `@aron98/load-lock` (also listed on ACE via `ace/opencode/`) — live-verified | `install --harness opencode` registers that same npm plugin | **plugin** |
+| **Claude Code** | ACE `ace/mcp` or a manual stdio registration | `load-lock-plugin` from this repo's marketplace — contract-tested, passes `claude plugin validate --strict`; not yet live-verified as a plugin (pending #63); ACE's skills-dir install unverified (#63/#66) | `install --harness claude-code`: MCP + hooks + `CLAUDE.md` section + skill — live-verified in Docker | **plugin** (loose gives the same capability) |
+| **Codex CLI** | `[mcp_servers]` entry in `~/.codex/config.toml` | none shipped | `install --harness codex`: MCP + hooks + `AGENTS.md` section — live-verified in Docker | **loose** |
+| **Cursor** | project `.cursor/mcp.json` | none shipped | `install --harness cursor --project <dir>`: MCP + stop hook + rule — contract-tested | **loose** |
+| **Gemini CLI, Copilot CLI, Cline, Roo Code, Goose** | the harness's MCP config | none shipped | `install --harness <h>`: MCP + instructions/rule file, no hooks — config-tested | **loose** (rung 1 plus a policy file; no idle wakeup) |
+| **omac** | n/a (sandbox, not a harness) | — | `install --harness omac`: sandbox-profile grants — live-verified | the inner harness's rung |
+| **Aider** | no MCP support | none | none | **0** (CLI only) |
+
+"Highest rung" is what `load-lock setup --yes` converges a harness to once
+it has some load-lock wiring (OPERATIONS.md, "Converging"). Mixing rungs in
+one harness is safe (ARCHITECTURE.md, "Three layers").
+
 ## How each integration tier works
 
 ### Tier 1 — OpenCode (native plugin, live-verified)
@@ -73,6 +97,23 @@ 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).
 
+#### ACE listing (opencode, issue #79)
+
+ACE ([TNG/ace](https://github.com/TNG/ace)) cannot detect the root
+`package.json` as an OpenCode plugin, because its entry point is the
+gitignored `dist/`. The OpenCode listing therefore comes from the dedicated
+folder `ace/opencode/`. It is a thin pointer: `index.js` re-exports
+`@aron98/load-lock`, and `package.json` (`load-lock-opencode`, private) pins
+that dependency to the release version through `scripts/check-pins.mjs`.
+ACE finds the folder through its npm-package heuristic (a `main` that exists
+in the git tree, plus `opencode` in the name or keywords). ACE marks every
+such detection as **"verify before registering"**, so that note is expected.
+`src/test/ace-opencode.test.ts` mirrors the heuristic (TNG/ace@b703410) and
+asserts that this repo yields exactly one OpenCode plugin, at `ace/opencode`.
+Users install the published package as usual (a `plugins` entry
+`@aron98/load-lock` in `opencode.json`), not the folder itself. The
+end-to-end ACE install is not yet live-verified (#66).
+
 #### Multiple copies of load-lock (opencode)
 
 `install --harness opencode` registers the **bare package name** in
@@ -97,12 +138,20 @@ Which copy is authoritative for what:
 - **The daemon's code** — whichever copy spawned it (usually the CLI copy,
   since auto-spawn and `service start` run from the CLI client code). The
   version handshake makes a daemon self-restart onto updated code when a
-  newer client contacts it — but the respawn reuses the daemon's original
-  argv, so it only picks up an update when its spawning copy was updated
-  *in place* (the normal global-upgrade case). A daemon spawned from a
-  different copy than the one you updated keeps running the old code until
-  `load-lock service restart` (since #38) or `service stop` + any command
-  re-spawns it from the new one.
+  newer client contacts it. Since #53 the respawn moves onto the newer
+  client's own copy (validated from its `clientRoot` hint), so a daemon
+  spawned from a different copy than the one you updated follows the
+  newer client. Clients older than #52 send no `clientRoot`; for them the
+  respawn reuses the daemon's original argv and only picks up an in-place
+  update of its spawning copy — `load-lock service restart` (since #38)
+  re-spawns it from the current CLI copy.
+- **npx-launched copies** (since #57) — skill / ACE / pinned MCP entries run
+  `npx -y @aron98/load-lock@<pin>`, which installs a copy under the npm
+  cache at `~/.npm/_npx/<hash>/node_modules/@aron98/load-lock/` (or under
+  `$npm_config_cache/_npx`; `%LocalAppData%\npm-cache\_npx` on Windows).
+  `doctor` lists these as `npx-cache`. They are owned by the pin that
+  launches them: `load-lock update` refuses to touch them and points at
+  bumping the pinned version (or the ACE artifact) instead.
 
 The mirror drift — a *newer* adapter copy (opencode refreshed its cache)
 with an *older* CLI on PATH — surfaces at adapter init (issue #38): the
@@ -135,6 +184,51 @@ observed live on this machine before the feature existed.
   idle Claude. The token is deliberately NOT in that message (stderr may be
   shown); the agent claims via `pending`/`claim`.
 
+**Tool names depend on the wiring.** A loose install (`load-lock install`)
+registers the MCP server as `load-lock`, so Claude Code exposes
+`mcp__load-lock__<tool>`. A plugin-bundled server is namespaced by plugin
+and server key, `mcp__plugin_<plugin>_<server>__<tool>` (per the Claude Code
+MCP docs), e.g. `mcp__plugin_load-lock-plugin_load-lock__claim` for the
+`load-lock-plugin` Claude Code plugin. Every text
+load-lock injects (policy brief, hook claim/wakeup messages, CLAUDE.md /
+AGENTS.md sections, skill) therefore names tools neutrally ("the load-lock
+`claim` tool") instead of hard-coding a prefix.
+
+**Claude Code plugin** (`/plugin install load-lock-plugin@load-lock`, see
+OPERATIONS "Claude Code plugin"): the same MCP server and hooks, bundled
+and run through the dependency-free launcher; no skill, the detailed guide
+comes from the `agent_guide` tool. Its manifest, hooks file and
+marketplace entry are contract-tested (`src/test/plugin.test.ts`) and pass
+`claude plugin validate --strict` (Claude Code 2.1.312), and the hook
+commands are tested the way the plugin invokes them. Hooks use shell form
+(one `command` string, `${CLAUDE_PLUGIN_ROOT}` quoted; #63).
+
+**Plugin live verification** (#63; Claude Code 2.1.312, 2026-10-29, Linux
+host): a real session with a throwaway `CLAUDE_CONFIG_DIR` and `HOME`,
+load-lock isolated by `LOAD_LOCK_STATE_DIR` / `LOAD_LOCK_SOCKET`, the
+plugin installed from this repo's marketplace with `claude plugin
+marketplace add <checkout>` + `claude plugin install
+load-lock-plugin@load-lock`, and the checkout's CLI first on `PATH`.
+Headless `claude -p` and an interactive pty session. Status: **plugin
+live-verified** for the checks marked observed:
+
+| Check | Result |
+| --- | --- |
+| Shell-form hooks run, launcher takes the PATH branch | Observed (`load-lock launcher: path 1.5.0` on every hook) |
+| SessionStart policy at startup | Observed (model quoted the isolated daemon's `load-lock now:` line) |
+| SessionStart policy after `/compact` | Observed (`SessionStart:compact` hook ran; model quoted the fresh `1/1` line where the startup brief said `0/1`) |
+| MCP tools named `mcp__plugin_load-lock-plugin_load-lock__<tool>` | Observed (all 19 tools listed under that prefix; server `plugin:load-lock-plugin:load-lock` connected) |
+| `agent_guide` tool | Observed (called; returned the guide) |
+| Stop offer continuation | Observed (headless: Stop hook returned `decision: block` with the offer token; model claimed and released) |
+| `await-offer` idle wakeup (`async` + `asyncRewake`) | Observed (interactive: session idle ~18s, offer arrived, the watcher's exit 2 woke the session with a task notification; model ran `pending` → `claim` → `release`) |
+| Daemon started by the plugin | Observed (fresh state dir; the daemon came up during session start with `CLAUDE_PLUGIN_ROOT` in its environment and `daemon.json` naming the PATH copy). Which plugin component spawned it first (hook or MCP server) was not determined. |
+| Session-derived identity | Observed for the plugin MCP server (requests carried agent `claude-code:<session id>` matching the session's transcript). That hooks read the same `session_id` from stdin was not separately inspected. |
+| Loose install + plugin together | Not observed (not run; covered by the #54 dedupe tests only) |
+| Launcher npx / known-copy branches inside a live session | Not observed (only the PATH branch ran) |
+
+The TUI labels the asyncRewake wake as "Stop hook blocking error from
+command SessionStart:startup"; the message text is the watcher's.
+
 Contract tests cover all hook stdin/stdout shapes against the documented
 harness contracts. Claude Code is additionally **live-verified** (in Docker,
 via `docker/run-claude-verify.sh` against the real `claude` CLI): SessionStart
@@ -267,7 +361,7 @@ without a dedicated installer.
 Idle policy: these harnesses get no push notifications, so the PRIMARY
 idle mechanism is the MCP `wait_for_turn` tool — a bounded, honest sleep
 until it is the caller's turn. Queued agents call
-`mcp__load-lock__wait_for_turn` (optionally with `timeout_ms`, default
+the load-lock `wait_for_turn` tool (optionally with `timeout_ms`, default
 600000, capped by the machine's `maxTurnWaitMs` config) and get a
 structured result on every path: `granted` (the offer was auto-claimed —
 `permit_token` included), `still_queued` (timeout, with queue position
@@ -333,7 +427,7 @@ UI** — where no UI surface exists, we say so rather than claim parity.
 | Harness | In-harness dashboard | Also available |
 | --- | --- | --- |
 | **OpenCode** | Native TUI panel: `/load-lock` opens `load-lock.dashboard` **in-window** as a side panel (also opened by clicking the sidebar widget; deliberately **not** bound to any key — issue #28: the old `gl` sequence swallowed plain `g` typing, and the candidate `ctrl+g` is the host's `session.first` default) with pools, holder cards, offer claim-window countdowns, queue, paused, event feed, `inspect_machine`; home-footer `lock 1/1` indicator on the home screen plus a clickable, health-colored `load-lock 0/3` widget in the session sidebar; `x` force-release behind select + confirm. Implemented as the package's `./tui` companion plugin (main plugin unchanged). Live-verified: opencode 2.0.29 (panel render, palette/slash command, confirm-gated force-release) and opencode 2.0.32 in a real pty (sidebar widget render, click-to-open, in-window presentation, plain `g` reaches the composer, `ctrl+g` not intercepted by load-lock). | `load-lock dashboard` (alias `top`) |
-| **Claude Code** | None in-app — Claude Code has no plugin UI surface. The model can report status via the `load_lock_status` MCP tool at tool boundaries, and each `SessionStart` hook injects a one-line machine summary. | `load-lock dashboard` (any terminal) |
+| **Claude Code** | None in-app — load-lock ships no in-app view for Claude Code: `load-lock-plugin` bundles the MCP server + hooks only, and the loose install adds no UI either. The model can report status via the load-lock `status` MCP tool at tool boundaries, and each `SessionStart` hook injects a one-line machine summary. | `load-lock dashboard` (any terminal) |
 | **Codex CLI** | None in-app — same reason. `load_lock_status` MCP tool; `SessionStart`/`SubagentStart` machine summary. | `load-lock dashboard` (alias `top`) |
 | **Gemini CLI** | None in-app (no hooks, no UI plugin surface). `load_lock_status` MCP tool at tool boundaries. | `load-lock dashboard` (alias `top`) |
 | **Copilot CLI, Cursor, Cline, Roo Code, Goose** | None in-app. MCP `status` tool where the MCP server is configured. | `load-lock dashboard` (alias `top`) |
@@ -348,14 +442,49 @@ reconnect, view-model shaping, frame rendering) is covered by
 
 ## Session identity per harness
 
+The daemon routes offers, `pending` and op-key duplicate suppression by agent
+id, so each harness session needs exactly one id, whichever wiring (CLI, MCP
+server, hook) made the call. The default identity of the CLI (issue #49) and
+of the MCP server (issue #50) comes from the shared resolver in
+`src/shared/identity.ts`, first match wins:
+
+1. explicit override: `--agent` (CLI), `agent_id` (MCP tools), or
+   `LOAD_LOCK_AGENT`;
+2. a harness session env var exported to the processes the harness spawns:
+   `CLAUDE_CODE_SESSION_ID` → `claude-code:<session_id>` (the same value hooks
+   receive as `session_id`; verified on Claude Code 2.1.x), and
+   `OPENCODE_SESSION_ID` → the bare `sessionID` (exported by OpenCode's bash
+   tool; verified on opencode 2.1.1). The bare id is exactly the native
+   plugin's agent id, so CLI calls from an OpenCode shell share the plugin's
+   identity;
+3. the stable harness ancestor process (Linux): walk up from the CLI's parent
+   past shells and launcher wrappers (`sh`/`bash`/`zsh`/…, `env`, `timeout`,
+   `npm`/`npx`, nested `load-lock`) to the first other ancestor, identified as
+   `proc:<pid>:<start time>` (pid-reuse safe via `/proc/<pid>/stat`), labelled
+   `<comm>:<pid>`. This covers harnesses without a verified env var (Codex,
+   Cursor, Gemini CLI, …), since one session = one long-lived harness process;
+4. otherwise (no harness ancestor, or no `/proc` — macOS/Windows without a
+   session env var) the legacy default: `cli:$USER@$HOSTNAME` for the CLI, a
+   random per-process `agt_…` id for the MCP server.
+
+So two MCP registrations in one session (plugin-bundled + standalone) share
+one id: an `acquire` through one shows in `pending` through the other, and
+both heartbeat the same id (idempotent). The CLI and the MCP server of one
+session share an id too when both see the same session env var or the same
+harness ancestor; whether a harness exports its session env var to MCP
+server processes is not verified for every harness.
+
+Labels stay human-readable: session-derived ids get a short holder label
+(`claude-code:ee690007`, `codex:12345`); explicit ids label themselves.
+
 | 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 |
-| Cursor | hooks get `conversation_id` (no `cwd` — `workspace_roots[0]` identifies the request); MCP tools take explicit `agent_id` | same |
+| OpenCode | plugin context `sessionID` (also MCP `_meta` when used); CLI via `OPENCODE_SESSION_ID` (same id) | automatic |
+| Claude Code | hooks get `session_id`; CLI and MCP server via `CLAUDE_CODE_SESSION_ID`, else the harness ancestor; MCP tools also take explicit `agent_id` | automatic; explicit `agent_id` still wins |
+| Codex | hooks get `session_id`; CLI and MCP server via harness ancestor process; MCP tools also take explicit `agent_id` | same |
+| Cursor | hooks get `conversation_id` (no `cwd` — `workspace_roots[0]` identifies the request); CLI and MCP server via harness ancestor process; MCP tools also take explicit `agent_id` | same |
 | omac (sandbox) | inner harness identity + `LOAD_LOCK_LABEL_PREFIX=omac` | dashboard shows holders as `omac:<label>` |
-| Tier 3 | explicit `agent_id` argument | falls back to per-server-process id |
+| Tier 3 | explicit `agent_id` argument; CLI and MCP server via harness ancestor process | MCP falls back to a per-server-process id only when no session is found |
 
 ## Platform matrix