@nledford/omp-coord 0.0.0-stage → 0.2.0

package/.omp-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "omp-coord",
+  "owner": { "name": "Nathaniel Ledford" },
+  "metadata": { "description": "Coordination for several omp sessions on one machine" },
+  "plugins": [
+    {
+      "name": "omp-coord",
+      "source": "./",
+      "description": "Shared subagent caps, build and test queues, claims, pause, a decision log and messages across omp sessions working in one project on one machine.",
+      "version": "0.2.0",
+      "author": { "name": "Nathaniel Ledford" },
+      "homepage": "https://github.com/nledford/omp-coord",
+      "repository": "https://github.com/nledford/omp-coord",
+      "license": "MIT",
+      "keywords": ["agents", "coordination", "queues", "subagents"],
+      "category": "productivity"
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+Notable changes to omp-coord, newest first. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) as described in [docs/versioning.md](docs/versioning.md).
+
+Add each user-visible change under Unreleased as it lands, in one of: Added, Changed, Deprecated, Removed, Fixed, Security. Mark a change that breaks the contract with **Breaking:** and say what to do about it.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-26
+
+### Added
+
+- Each release is published as the npm package `@nledford/omp-coord` to GitHub Packages; see [docs/install.md](docs/install.md).
+
+### Changed
+
+- **Breaking:** the package is now named `@nledford/omp-coord`, so omp lists and upgrades a git or package install under that name (`omp plugin upgrade @nledford/omp-coord`). Marketplace installs keep `omp-coord@omp-coord`.
+
+### Fixed
+
+- In a container whose first process never reaps orphans, a job stopped by its time limit no longer holds its slot for the whole 10-second grace period: exited processes left in its process group no longer count as running.
+
+## [0.1.0] - 2026-10-26
+
+### Added
+
+- Shared subagent caps across omp sessions in one project, with pools, exempt agent types, limits on agents started by subagents, and a fair line: a refused session gets the next free slot, held for it for a few minutes.
+- Build and test queues: `omp-coord run <queue> -- <command>` waits for a slot. Queues can be ordered `fifo`, `fair-share` or `priority`, with lanes, aging, duplicate keys (refuse or supersede), and time limits. The extension rewrites agents' bash commands that match `queue` rules, and refuses those that match `refuse` rules.
+- Messages between sessions and to another session's subagent (`coord_send`, `/coord send`, `B/<agent id>`).
+- Claims on branches, worktrees and PRs (`coord_claim`, `/coord claim`): other sessions' agents are refused git and gh commands that would change a claimed one.
+- Pause and resume for a whole scope (`/coord pause`, `omp-coord pause`).
+- Lower agent caps and queue slots while the machine's load average is high (`loadCaps`, `loadSlots`).
+- A block of ports and a scratch folder per session and per agent (`resources`, `coord_resources`, `OMP_COORD_PORTS`, `OMP_COORD_SCRATCH`).
+- A shared decision log (`coord_note`, `/coord note`, `omp-coord note`).
+- Reports from the event log: `omp-coord interrupted` (agents a crashed or closed session left mid-run) and `omp-coord stats`; `omp-coord doctor [--fix]`.
+- An SQLite event log per scope, with retention.
+- Packaging as an omp plugin, with a marketplace catalog; queued commands run on omp's own Bun.
+
+[Unreleased]: https://github.com/nledford/omp-coord/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/nledford/omp-coord/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/nledford/omp-coord/releases/tag/v0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# omp-coord
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [omp](https://github.com/can1357/oh-my-pi) plugin, plus a small command-line runner, that lets several omp sessions on one machine, working in the same project, share one set of agent caps and build/test queues, and talk to each other.
+
+- **Shared agent caps.** Subagents count against pools (for example 8 `work` and 2 `short` slots) shared by every session in the project. A spawn over the cap is refused through omp's spawn check, so the cap does not depend on agents remembering to take and free slots.
+- **A fair line.** A refused session joins the line; the next free slot is held for it, and it is told so.
+- **Subagents start only reviewers.** "No nested worker agents" is enforced rather than asked for.
+- **Build and test queues.** `omp-coord run <queue> -- <command>` waits for one of the queue's slots, then runs the command, within an optional time limit. Agents' matching bash commands are rewritten to go through it.
+- **Messages, claims, pause.** Sessions message each other and each other's subagents, claim branches, worktrees and PRs against other sessions' git commands, and pause the whole project at once.
+- **Load-aware limits, ports and scratch folders, a decision log, reports** of waits, refusals and agents a crash left mid-run, and an SQLite event log.
+
+Each session gets a letter and shows `coord B · work 5/8 · short 1/2` in omp's footer. Here session B's agents hold both `work` slots, so session A's spawn is refused, A goes first in line, and `/coord` shows the board:
+
+![omp with omp-coord: a spawn refused because both work slots are in use, and the /coord board showing session A first in line](docs/images/spawn-refused.png)
+
+## Quick start
+
+```sh
+omp plugin install "git+ssh://git@github.com/nledford/omp-coord.git"
+```
+
+Then put a `.omp-coord.json` in the project's top folder:
+
+```json
+{
+  "scope": "my-project",
+  "agents": { "pools": { "work": { "cap": 6 } }, "exempt": ["reviewer"] },
+  "queues": { "build": { "slots": 2, "order": "fair-share" } },
+  "commands": [{ "pattern": "(^|\\s)npm run build\\b", "action": "queue", "queue": "build" }]
+}
+```
+
+Every omp session started in that folder or below now shares 6 agent slots, and agents' `npm run build` waits for one of 2 build slots. `/coord` shows the board; `omp-coord doctor` checks the setup. A fuller example: [`examples/omp-coord.json`](examples/omp-coord.json).
+
+## Documentation
+
+| | |
+|---|---|
+| [Install](docs/install.md) | Plugin install over SSH or the marketplace, updating, the `omp-coord` command. |
+| [Configuration](docs/configuration.md) | Every `.omp-coord.json` field. |
+| [Agent slots](docs/agent-slots.md) | How caps, the line, holds and nested agents work. |
+| [Queues](docs/queues.md) | `omp-coord run`, order, lanes, time limits, agents' commands. |
+| [Working across sessions](docs/coordination.md) | Messages, claims, pause, the decision log, ports, crash recovery. |
+| [Commands](docs/commands.md) | `/coord`, agent tools, CLI, environment variables. |
+| [Event log](docs/event-log.md) | The SQLite tables and events, with example queries. |
+| [Versioning](docs/versioning.md) | What the version promises; cutting a release. |
+
+[CHANGELOG.md](CHANGELOG.md) lists what each release changed.
+
+## Limits
+
+- The cap is an agreement between sessions, not a security boundary: if the shared board cannot be read, spawns are let through with an error notice.
+- Sessions of one scope should read the same `.omp-coord.json`. Two different files under one scope (for example one per worktree) make sessions disagree.
+- Claims match command text: a guard against mistakes, not a lock.
+- A message is put into the other session's conversation as written. Text an agent copies into a message from an untrusted source reaches the other session too.
+- `/tan` clones are subagents to omp, so they take slots from the default pool and fall under the rules for agents started by subagents.
+- On one machine only: sessions find each other through a shared folder, not the network.
+
+## Develop
+
+```sh
+just install
+just fmt     # format with Biome
+just check   # typecheck, lint, tests, version files agreeing
+just         # every workflow
+```
+
+Code layout and conventions: [AGENTS.md](AGENTS.md). License: [MIT](LICENSE).

package/docs/README.md

@@ -0,0 +1,20 @@
+# omp-coord documentation
+
+Setting up:
+
+- [Install](install.md): plugin install, updating, the `omp-coord` command.
+- [Configuration](configuration.md): every `.omp-coord.json` field.
+
+How it works:
+
+- [Agent slots and the line](agent-slots.md): caps, holds, revivals, agents started by subagents.
+- [Build and test queues](queues.md): `omp-coord run`, order, lanes, time limits, agents' commands.
+- [Working across sessions](coordination.md): messages, claims, pause, the decision log, ports, crash recovery.
+
+Reference:
+
+- [Commands](commands.md): `/coord`, the agent tools, `omp-coord`, environment variables.
+- [State and event log](event-log.md): the SQLite tables, event types, example queries.
+- [Versioning and releases](versioning.md): what the version promises, and how releases are cut.
+
+Contributing: [AGENTS.md](../AGENTS.md) covers the code layout and conventions.

package/docs/agent-slots.md

@@ -0,0 +1,38 @@
+# Agent slots and the line
+
+Subagents count against pools of slots (for example 8 `work` and 2 `short`) shared by every session in the scope. Pools, caps and agent types are set under `agents` in the [configuration](configuration.md).
+
+## How slots are counted
+
+| Event | Effect |
+|---|---|
+| omp's spawn check approves a subagent | It takes a slot at once (`starting`). |
+| The subagent's run starts (`agent_start`) | The slot becomes `running`. |
+| The subagent's run ends (`agent_end`: finished, failed or killed) | The slot frees. An idle or parked agent holds no slot. |
+| An idle agent is revived (`write agent://…`) | It takes a slot again, even over the cap. omp does not run the spawn check for revivals, and running agents are never stopped; new spawns are refused until the total is under the cap. |
+| An approved spawn never starts | Its slot frees after `agents.startTimeoutSeconds`. |
+| A session exits or its process dies | All its slots and its place in line go, within about 10 seconds. |
+
+## The line
+
+A spawn over the cap is refused, and the session joins the line for that pool. When a slot frees, it is held for the session refused first (default 5 minutes, `agents.holdMinutes`) and that session is told so; other sessions' spawns are refused meanwhile. A session that does not use its held slot in time loses it to the next in line.
+
+The refusal, as the refused session sees it (here both `work` slots are in use by session B):
+
+![A spawn refused with "FULL: 2/2 work slots are in use across all sessions", and the /coord board showing session A first in line for work](images/spawn-refused.png)
+
+When one of B's agents ends, the slot is held for A, which is woken with a notice and starts the refused agent:
+
+![The omp-coord notice "A work slot is free and held for this session until 09:47 AM", followed by the restarted agent finishing](images/slot-held.png)
+
+omp gives the spawn check 30 seconds and then lets the spawn through, so the extension never waits inside it: it refuses at once and holds the next free slot instead. If the shared board cannot be read, spawns are let through with an error notice: the cap is an agreement between sessions, not a security boundary.
+
+While the machine's 1-minute load average is above a pool's `loadCaps` threshold, the lower cap applies. Running agents are never stopped; new ones wait until the total is under the lower cap.
+
+## Agents started by subagents
+
+A subagent may start only the agent types listed under `agents.nested.allow` (by default the exempt types, such as reviewers), at most `agents.nested.maxRunningPerParent` at a time, outside the caps. Everything else is refused, so "no nested worker agents" is enforced rather than asked for.
+
+## Exempt agents
+
+Agent types under `agents.exempt` never take a slot. They still start while the scope is paused.

package/docs/commands.md

@@ -0,0 +1,46 @@
+# Command reference
+
+## In omp
+
+| Command | Does |
+|---|---|
+| `/coord` | Sessions, slots, the line, claims, queues, the latest decisions; marks a paused scope and sessions reading a different config file. |
+| `/coord send <letter\|B/agent\|all> <text>` | Message other sessions or one of their subagents. |
+| `/coord pause [reason]`, `/coord resume` | Stop and restart new agents and queued jobs in every session. |
+| `/coord claim <branch\|worktree\|pr> <target> [note]`, `/coord release <kind> <target>` | Claim or release. |
+| `/coord note <text>`, `/coord notes [n]` | Write to and read the decision log. |
+| `/coord stats [days]`, `/coord interrupted [hours]` | Reports from the event log. |
+
+## Agent tools
+
+| Tool | Does |
+|---|---|
+| `coord_status` | The same overview as `/coord`. |
+| `coord_send` | Message another session or one of its subagents (main session only). |
+| `coord_claim`, `coord_release` | Claim or release a branch, worktree or PR. |
+| `coord_note` | Add to the decision log. |
+| `coord_resources` | The calling agent's own ports and scratch folder. |
+| `coord_job_priority` | Reorder this session's waiting jobs. |
+
+## `omp-coord`
+
+```sh
+omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command> [args…]
+omp-coord status | stats [days] | interrupted [hours] | notes [count] | note <text…>
+omp-coord pause [reason…] | resume | doctor [--fix]
+```
+
+`run` is described under [queues](queues.md). The others act on the scope whose `.omp-coord.json` is found from the current folder.
+
+Exit codes: `0` success, the command's own for `run`, `75` a job not run, `124` a job stopped by its time limit, `2` a usage or configuration error.
+
+## Environment
+
+| Variable | Set by | Meaning |
+|---|---|---|
+| `OMP_COORD_CONFIG` | you | The config file to use instead of searching from the current folder. |
+| `OMP_COORD_STATE_DIR` | you | The state folder instead of `~/.omp/run/omp-coord` (use a scratch folder for tests). |
+| `OMP_COORD_SESSION` | the extension | The session that owns jobs started from its agents' commands. |
+| `OMP_COORD_PORTS` | the extension | The session's port block, e.g. `18700-18799`, when `resources.ports` is set. |
+| `OMP_COORD_SCRATCH` | the extension | The session's scratch folder, when `resources.scratch` is set. |
+| `OMP_COORD_JOB`, `OMP_COORD_QUEUE` | `omp-coord run` | The running job's id and queue, for nested runs. |

package/docs/configuration.md

@@ -0,0 +1,31 @@
+# Configuration
+
+`.omp-coord.json`, in the project's top folder (see [`examples/omp-coord.json`](../examples/omp-coord.json)). Sessions find it in their folder or a parent folder, or through `OMP_COORD_CONFIG`. Every session of a scope should read the same file: each applies the caps and timeouts of the file it found, and `/coord` marks sessions that read a different one.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `scope` | required | Sessions coordinate only with sessions of the same scope. Letters, digits, `.`, `_`, `-`. |
+| `agents.pools` | `{ "work": { "cap": 8 } }` | Pools of slots: `cap`, `agentTypes` (omp agent definition names) that use the pool, and `loadCaps`: `[{ "above": 150, "cap": 4 }]` lowers the cap while the 1-minute load average is above 150. |
+| `agents.defaultPool` | first pool | Pool for agent types no pool lists. |
+| `agents.exempt` | `[]` | Agent types that never take a slot (read-only reviewers). |
+| `agents.nested.allow` | `agents.exempt` | Agent types a subagent may start. |
+| `agents.nested.maxRunningPerParent` | `1` | How many of those one subagent may run at once. |
+| `agents.holdMinutes` | `5` | How long a freed slot stays held for the session first in line. |
+| `agents.startTimeoutSeconds` | `120` | How long an approved spawn may take to start before its slot frees. |
+| `messages.perMinute` | `10` | Messages one session may send per minute. It slows two sessions that keep answering each other; it does not stop them. Each delivered message starts a turn in an idle session. |
+| `commands` | `[]` | Rules for agents' bash commands, first match wins: `{ "pattern": "<regex>", "action": "refuse", "reason": "…" }`, or `{ "pattern", "action": "queue", "queue": "<name>", "lane"? }`. The user's own `!` commands are not affected. |
+| `queues.<name>.slots` | required | How many jobs of this queue run at once, across all processes in the scope. Queue names use letters, digits, `.`, `_`, `-`. |
+| `queues.<name>.order` | `"fifo"` | `"fifo"`, `"fair-share"` or `"priority"` (see [queues](queues.md#order)). |
+| `queues.<name>.lanes` | `["normal"]` | Lane names, first served first; the last is the default. |
+| `queues.<name>.agingMinutes` | none | Waiting this long adds 1 to a job's priority. |
+| `queues.<name>.onDuplicate` | `"refuse"` | `"refuse"` or `"supersede"` a waiting job with the same key. |
+| `queues.<name>.timeoutMinutes` | none | Stop a job's command after this long: SIGTERM to its process group, then SIGKILL to whatever of it is left 10 s later; it exits 124. `--timeout` overrides it per job. |
+| `queues.<name>.loadSlots` | `[]` | `[{ "above": 150, "slots": 1 }]`: fewer slots under load; `0` holds the queue. |
+| `resources.ports` | none | `{ "from", "to", "perSession", "perAgent" (10) }`: each session gets a block of `perSession` ports, each agent a block of `perAgent` from its session's. |
+| `resources.scratch` | none | Root of the scratch folders: `<scratch>/<letter>` per session, `<scratch>/<letter>/<agent id>` per agent. Relative to the config file. |
+| `history.retentionDays` | `30` | Events and decision-log notes older than this are deleted. |
+| `history.maxEvents` | `100000` | The event log keeps at most this many of the newest events. |
+
+Agent type names are matched lowercased against omp's agent definition names (`task`, `scout`, `reviewer`, `security-reviewer`, `sonic`, or your own).
+
+A file with a mistake turns omp-coord off in that session, with an error that names the field, e.g. `omp-coord is off: /repo/.omp-coord.json: queues.build.slots must be a whole number of at least 1`. `omp-coord doctor` reports the same.

package/docs/coordination.md

@@ -0,0 +1,41 @@
+# Working across sessions
+
+Each session gets a letter (A, B, …) and shows `coord B · work 5/8 · short 1/2` in the footer. A session that exits or crashes leaves the board within about 10 seconds. Commands and tools are listed in the [command reference](commands.md).
+
+## Messages
+
+`coord_send` (or `/coord send B …`) delivers a message into the other session's conversation at its next step, waking it when idle; `all` reaches every other session, and `B/<agent id>` one of session B's subagents. Messages arrive as `[omp-coord] Message from omp session A …`, marked as coming from another session rather than from the user. A message for a subagent that is not running goes to its main session, which can pass it on with `write agent://<id>`.
+
+Messages are rate-limited (`messages.perMinute`), and each delivered message starts a turn in an idle session. Text an agent copies into a message from an untrusted source reaches the other session as written.
+
+## Claims
+
+A session claims a branch, worktree or PR (`coord_claim`, `/coord claim`); other sessions' agents are refused git and gh commands that would change it until it is released or the session ends.
+
+**Claims are a guard against mistakes, not a lock.** They match command text:
+
+- a git command that changes a claimed worktree: run in it, after `cd` into it, or with `git -C`. A worktree nested inside a claimed checkout is its own.
+- a git command that changes a branch named in it: push (including force-push with `+`), checkout, rebase, reset, …. Commit messages do not count.
+- a gh command that changes a claimed PR: `gh pr edit`, `comment`, `merge`, … with the number or URL anywhere outside `--body` and `--title`, and `gh api` writes to `pulls/N` or `issues/N`.
+
+Reading commands always pass, and so does anything written to dodge the patterns.
+
+## Pause and drain
+
+`/coord pause [reason]` or `omp-coord pause` stops every new agent and queued job in the scope while running work finishes; `resume` lifts it. Exempt agents still start.
+
+**Pausing keeps everyone's place.** A slot held for a session when the pause starts stays held, and on resume each held slot gets its full hold time again.
+
+## Decision log
+
+`coord_note`, `/coord note` and `omp-coord note` record a decision every session sees in `/coord` and `coord_status`, numbered and with its author. `/coord notes` and `omp-coord notes` list them. Notes are kept like events (`history.retentionDays`).
+
+## Ports and scratch folders
+
+With `resources.ports`, each session gets its own block of ports, in `OMP_COORD_PORTS` (e.g. `18700-18799`) for every command its agents run; with `resources.scratch`, its own folder in `OMP_COORD_SCRATCH`. An agent that needs ports or a folder of its own (a server, a control port) calls `coord_resources` and gets a share of its session's, the same one each time. A session started when every block was taken gets no ports and is told so.
+
+## After a crash
+
+`/coord interrupted` (or `omp-coord interrupted`, which first drops sessions whose process is gone) lists, per session that left, the agents that were mid-run and the folder the session ran in. omp keeps their transcripts; revive each from a session in that folder with `write agent://<id>`.
+
+`/coord stats` sums waits, refusals, peaks and job outcomes per day; `omp-coord doctor` checks the scope's health, and `doctor --fix` drops sessions and jobs whose process is gone.

package/docs/event-log.md

@@ -0,0 +1,47 @@
+# State and event log
+
+Kept in `~/.omp/run/omp-coord/` (owner-only; `OMP_COORD_STATE_DIR` overrides): one SQLite database per scope, `<scope>.db`, and one Unix socket per live session and per queued job. A session or job is gone when nothing listens on its socket, which a reused PID cannot fake.
+
+The database is meant to be read by other tools. The schema version is in `PRAGMA user_version`; a database with a different schema is refused rather than misread.
+
+## Current state
+
+These tables are rebuilt as sessions come and go; their layout is not part of the [versioned contract](versioning.md).
+
+| Table | Rows |
+|---|---|
+| `sessions` | Live sessions: `id`, `label` (A, B…), `pid`, `cwd`, `socket`, `started_at`, `config_hash` (of the `.omp-coord.json` it read), `ports_from`/`ports_to`. |
+| `slots` | Agent slots held: `session_id`, `agent_id`, `parent_id`, `agent_type`, `pool` (null outside the caps), `state` (`starting` or `running`), `since`. |
+| `tickets` | The line: `session_id`, `pool`, `since`, `hold_until` (set while a slot is held for it), `notified`. |
+| `messages` | Messages not yet delivered. |
+| `jobs` | Queued and running build/test jobs: `id`, `queue`, `owner` (session id, or null outside omp), `lane`, `priority`, `key`, `command`, `pid`, `state` (`waiting`, `running`, `superseded`), `since`, `started_at`. |
+| `claims` | `kind` (`branch`, `worktree`, `pr`), `target`, `session_id`, `agent_id`, `note`, `since`. |
+| `pause` | One row while the scope is paused: `by_session` (null from a terminal), `reason`, `since`. |
+| `agent_ports` | Port blocks agents took: `session_id`, `agent_id`, `from_port`, `to_port`. |
+| `machine_load` | The latest load average any session or runner measured, and when. |
+
+## Event log and decision log
+
+`events` is an append-only log: `at` (ms since epoch), `type`, `session_id` (null for jobs from outside omp), `label`, and `data` (JSON). Types:
+
+- Sessions and agents: `session_joined`, `session_left`, `spawn_approved`, `spawn_refused` (with `position`, `used`, `cap`, or `nested` and `reason`), `run_started` (with `revived`), `run_ended` (with `ranMs`), `start_expired`, `hold_granted`, `hold_used` and `hold_expired` (with `waitedMs` since the first refusal), `message_sent` (recipients and length, never the text).
+- Jobs: `job_queued` (with `queue`, `lane`, `priority`, `key`), `job_refused` (with `reason`), `job_started` (with `waitedMs`), `job_ended` (with `exitCode`, `ranMs`, and `timedOut` when the time limit stopped it), `job_withdrawn` (left the line before starting), `job_superseded`, `job_lost` (its runner died), `job_reprioritized`.
+- Control: `paused` (with `reason`), `resumed` (with `pausedMs`), `claimed`, `released`, `claim_refused` (with `holder`), `note_added` (note number and length).
+
+`notes` is the decision log: `id`, `at`, `label`, `author`, `text`.
+
+Retention: events and notes older than `history.retentionDays`, and all but the newest `history.maxEvents` events, are deleted when a session starts and then at most once an hour. All times are milliseconds since the epoch.
+
+## Queries
+
+```sh
+db=~/.omp/run/omp-coord/my-project.db   # <scope>.db
+# Agent slots held right now, per session
+sqlite3 -column -header "$db" "select s.label, sl.pool, count(*) n from slots sl join sessions s on s.id = sl.session_id group by 1, 2"
+# How long sessions waited for a slot (minutes), per day
+sqlite3 -column -header "$db" "select date(at/1000,'unixepoch','localtime') day, label, count(*) holds, round(max(json_extract(data,'$.waitedMs'))/60000.0,1) max_wait_min from events where type='hold_used' group by 1, 2"
+# Refusals per hour
+sqlite3 -column -header "$db" "select strftime('%Y-%m-%d %H:00',at/1000,'unixepoch','localtime') hour, count(*) refused from events where type='spawn_refused' group by 1"
+# Build waits per queue and day: jobs, average and longest wait (minutes)
+sqlite3 -column -header "$db" "select date(at/1000,'unixepoch','localtime') day, json_extract(data,'$.queue') queue, count(*) jobs, round(avg(json_extract(data,'$.waitedMs'))/60000.0,1) avg_wait, round(max(json_extract(data,'$.waitedMs'))/60000.0,1) max_wait from events where type='job_started' group by 1, 2"
+```

package/docs/install.md

@@ -0,0 +1,53 @@
+# Install
+
+Requires omp 18.12 or later. No dependencies at runtime: the extension and the runner use the Bun built into omp.
+
+## From GitHub Packages
+
+Each release is published as the npm package `@nledford/omp-coord` to GitHub Packages. It is private like the repository, and GitHub Packages asks for a token even for public packages, so each machine needs one-time setup: a token that can read packages, and the `@nledford` scope pointed at GitHub's registry in `~/.npmrc`.
+
+```sh
+gh auth refresh --scopes read:packages      # once: let the GitHub CLI's token read packages
+cat >> ~/.npmrc <<EOF
+@nledford:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=$(gh auth token)
+EOF
+```
+
+Then install a release, or the newest one:
+
+```sh
+omp plugin install @nledford/omp-coord@0.2.0
+omp plugin install @nledford/omp-coord
+```
+
+## From GitHub
+
+Over SSH. The repository is private for now, and the `github:` shorthand and HTTPS URLs fail without credentials; `github:nledford/omp-coord` works once it is public:
+
+```sh
+omp plugin install "git+ssh://git@github.com/nledford/omp-coord.git"
+```
+
+Or through omp's marketplace, which this repository also serves:
+
+```sh
+omp plugin marketplace add git@github.com:nledford/omp-coord.git
+omp plugin install omp-coord@omp-coord
+```
+
+## Updating
+
+`omp plugin upgrade @nledford/omp-coord` moves a package or git URL install to the newest release or commit; `omp plugin upgrade omp-coord@omp-coord` moves a marketplace install once a release has raised the catalog's version. Bun remembers the commit a git URL resolved to, so installing a git URL again can bring back an older commit; to pin a release over git, add its tag: `…/omp-coord.git#v0.2.0`. [CHANGELOG.md](../CHANGELOG.md) lists what each release changed.
+
+## From a checkout
+
+Link it instead: `omp plugin install /path/to/omp-coord`, or load it for one run with `omp -e /path/to/omp-coord/src/index.ts`.
+
+## The `omp-coord` command
+
+For scripts and terminals: `bun link` in the checkout puts it on `PATH` (`~/.bun/bin`). Without Bun, call it through omp: `BUN_BE_BUN=1 omp /path/to/omp-coord/src/adapters/cli/cli.ts <subcommand>`.
+
+## Turning it on in a project
+
+The extension stays inactive in a session unless it finds a `.omp-coord.json` in the session's folder or a parent folder (so every worktree below a checkout uses the checkout's file), or the file named by `OMP_COORD_CONFIG`. See [configuration](configuration.md). Run `omp-coord doctor` in the project to check the setup.

package/docs/queues.md

@@ -0,0 +1,52 @@
+# Build and test queues
+
+`omp-coord run <queue> -- <command>` waits for one of the queue's slots, shared by everything on this machine in the same scope, then runs the command. `just` recipes, scripts and terminals call it; agents' matching bash commands are rewritten to go through it. Queues are set under `queues` in the [configuration](configuration.md).
+
+```sh
+omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command> [args…]
+```
+
+## Running a job
+
+`run` waits for a slot of `<queue>`, runs the command with the terminal's input and output, and exits with the command's exit code. Ctrl-C while waiting leaves the line; while running, it is passed to the command.
+
+The command runs in its own process group and session, so a time limit stops everything it started: SIGTERM to the group, then SIGKILL to whatever is left 10 seconds later. The command has no controlling terminal: it reads and writes the terminal through its input and output, but prompts that open `/dev/tty` (sudo, ssh or gpg passphrases, git credential prompts) fail, and Ctrl-Z stops only the runner.
+
+- **Exit codes**: the command's own, `75` when the job was not run (a refused or superseded duplicate), `124` when its time limit stopped it, `2` for a usage or configuration error.
+- **Owner**: jobs belong to the omp session in `OMP_COORD_SESSION` (set by the extension, so commands an agent runs inherit it) or `--owner`; otherwise to no session ("outside omp").
+- **Duplicates**: jobs with the same `--key` (for example `"<checkout> ci"`) are duplicates. One that duplicates a running job is refused; one that duplicates a waiting job is refused or, with `onDuplicate: "supersede"`, replaces it in its place in line.
+
+## Order
+
+Per queue:
+
+- `fifo`: oldest first.
+- `fair-share`: owners take turns (the one served longest ago goes next), and within one owner higher `priority` goes first, so priority never lets a session jump another.
+- `priority`: higher priority first across everyone.
+
+With `agingMinutes`, each that many minutes of waiting adds 1 to a job's priority, so no job waits forever behind others *in its lane*.
+
+**Lanes**: `--lane` picks one of the queue's `lanes`; earlier lanes go first. Without it, the job goes in the last lane. Lanes are strict: steady front-lane traffic keeps the normal lane waiting.
+
+Agents reorder their own session's waiting jobs with `coord_job_priority`. Priorities run from -1,000,000 to 1,000,000. While the load average is above a queue's `loadSlots` threshold, fewer jobs start.
+
+## Nested runs
+
+The running command gets `OMP_COORD_JOB` (its job id) and `OMP_COORD_QUEUE`. An `omp-coord run` on the same queue from inside that command runs at once, since it already holds that queue's slot (otherwise a one-slot queue would wait for itself). It stays in the outer job's process group, so the outer time limit stops it too. So a script can queue itself:
+
+```sh
+# At the top of a script that needs a heavy slot: re-run this script inside one.
+[ "${OMP_COORD_QUEUE:-}" = heavy ] || exec omp-coord run heavy --key "$PWD ci" -- "$0" "$@"
+```
+
+## When runners die
+
+A runner that dies (crash, `kill -9`) loses its slot within about 10 seconds: every runner listens on a Unix socket, and the others drop jobs whose socket stops answering. The command it started is not stopped: after `kill -9` of the runner it keeps running outside the queue. Stop runners with Ctrl-C or `kill` (SIGTERM), which pass the signal on.
+
+A command that puts its work in the background (`cargo test &`) holds the slot only until the shell exits, so the background work runs unqueued.
+
+## Agents' commands
+
+When an agent's bash command matches a `queue` rule under `commands`, the extension rewrites it to run `omp-coord run <queue> --owner <session> -- sh -c '<command>'` with omp's own binary as Bun (`BUN_BE_BUN=1`), so it needs no separate Bun install. The waiting happens inside the bash call, which counts against the bash tool's timeout: agents should run long jobs as background (`async`) bash calls. The rewritten command runs in `sh`, so shell variables the agent set earlier without exporting them are not visible to it.
+
+A command matching a `refuse` rule is refused with the rule's reason.

package/docs/versioning.md

@@ -0,0 +1,43 @@
+# Versioning and releases
+
+Releases follow [Semantic Versioning](https://semver.org/) and are tagged `vX.Y.Z`; [CHANGELOG.md](../CHANGELOG.md) lists what each one changed.
+
+## The contract
+
+The version covers:
+
+- the `.omp-coord.json` fields, their defaults and what they accept ([configuration](configuration.md));
+- the `omp-coord` subcommands, flags and exit codes (75, 124, 2) ([commands](commands.md));
+- the agent tools (`coord_*`) and their parameters, and the `/coord` commands;
+- the environment variables it sets or reads (`OMP_COORD_*`);
+- the event types and fields in the event log, and the decision log ([event log](event-log.md));
+- the minimum omp version;
+- the package name (`@nledford/omp-coord`) and the marketplace plugin name (`omp-coord@omp-coord`) that install and upgrade it.
+
+Not covered: the wording of messages and reports, the other state tables (rebuilt as sessions come and go), and anything under `src/` that the above does not expose.
+
+## Which number moves
+
+| Change | Before 1.0.0 | From 1.0.0 |
+|---|---|---|
+| Breaks the contract: a removed or renamed field, flag, tool or event; a narrower accepted value; a changed default or exit code; a higher minimum omp version | minor (0.3.4 → 0.4.0) | major |
+| Adds to it without breaking: a new field, flag, tool, event or event field | patch (0.3.4 → 0.3.5) | minor |
+| Fixes behavior to match the documentation | patch | patch |
+
+1.0.0 comes when the contract is declared stable, after real use in a project. Until then, read the changelog before upgrading across a minor version.
+
+There are no prereleases (`-rc.1` and the like): the marketplace catalog follows `main`, and omp would move every marketplace install onto one.
+
+## Cutting a release
+
+From `main`, with a clean work tree, not behind `origin/main`:
+
+```sh
+just release-plan              # commits and changelog since the last release; the next version for each kind of change
+just release fix               # or feature, breaking, or an exact version such as 1.0.0
+just release-publish           # asks, then pushes main and the tag; CI checks it and creates the GitHub release
+```
+
+`just release` refuses an empty Unreleased section in the changelog, sets the version in `package.json` and the marketplace catalog, dates the changelog, runs the checks, then commits `Release vX.Y.Z` and tags it, all locally. If anything fails before the commit, the files are put back. The version changes only in release commits, because omp upgrades marketplace installs only when the catalog's version goes up.
+
+The release workflow checks that the tag is on `main` and matches the version files and the changelog, runs the checks on macOS, and creates the GitHub release with the changelog entry as its notes.

package/examples/omp-coord.json

@@ -0,0 +1,44 @@
+{
+  "scope": "my-project",
+  "agents": {
+    "pools": {
+      "work": { "cap": 6, "loadCaps": [{ "above": 12, "cap": 3 }] },
+      "short": { "cap": 2, "agentTypes": ["scout"] }
+    },
+    "exempt": ["reviewer", "security-reviewer"],
+    "nested": { "allow": ["reviewer"], "maxRunningPerParent": 1 },
+    "holdMinutes": 5
+  },
+  "queues": {
+    "build": {
+      "slots": 2,
+      "order": "fair-share",
+      "lanes": ["urgent", "normal"],
+      "agingMinutes": 15,
+      "timeoutMinutes": 60,
+      "onDuplicate": "supersede",
+      "loadSlots": [{ "above": 12, "slots": 1 }]
+    },
+    "test": { "slots": 3, "order": "fair-share", "agingMinutes": 10, "timeoutMinutes": 30 }
+  },
+  "commands": [
+    { "pattern": "(^|[;&|(\\s])(npm|pnpm|yarn|bun)\\s+(run\\s+)?test\\b", "action": "queue", "queue": "test" },
+    { "pattern": "(^|[;&|(\\s])(npm|pnpm|yarn|bun)\\s+run\\s+build\\b", "action": "queue", "queue": "build" },
+    {
+      "pattern": "(^|[;&|(\\s])pkill\\b",
+      "action": "refuse",
+      "reason": "pkill can stop other agents' processes; stop only the process you started, by its PID"
+    },
+    {
+      "pattern": "(^|[;&|(\\s])git\\s+(-C\\s+\\S+\\s+)?stash\\b",
+      "action": "refuse",
+      "reason": "stashes are shared by all worktrees: commit to a throwaway branch instead"
+    }
+  ],
+  "resources": {
+    "ports": { "from": 20000, "to": 20999, "perSession": 200, "perAgent": 10 },
+    "scratch": ".omp-coord-scratch"
+  },
+  "messages": { "perMinute": 10 },
+  "history": { "retentionDays": 30, "maxEvents": 100000 }
+}