@nledford/omp-coord 0.2.0 → 0.2.2

package/.omp-plugin/marketplace.json

@@ -7,7 +7,7 @@
       "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",
+      "version": "0.2.2",
       "author": { "name": "Nathaniel Ledford" },
       "homepage": "https://github.com/nledford/omp-coord",
       "repository": "https://github.com/nledford/omp-coord",

package/CHANGELOG.md

@@ -6,6 +6,23 @@ Add each user-visible change under Unreleased as it lands, in one of: Added, Cha
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-10-27
+
+### Added
+
+- `omp-coord status --json` prints the board as one JSON object for scripts (scope, sessions, pools, line, agents, claims, queues with their running and waiting jobs, latest notes, load; times in epoch milliseconds). With a board that cannot be read it prints nothing to stdout and exits non-zero. The fields are documented in [docs/commands.md](docs/commands.md).
+- A list of the running agents with their type, parent, pool, state and age: `/coord agents`, `omp-coord status --agents`, and `agents` in `status --json`.
+
+## [0.2.1] - 2026-10-26
+
+### Added
+
+- Releases are published to npmjs.com as `@nledford/omp-coord`, with provenance: `omp plugin install @nledford/omp-coord` needs no token or `.npmrc`.
+
+### Fixed
+
+- On Linux, where `/proc` cannot be read (some hardened containers), a timed-out job now falls back to signalling its process group instead of failing.
+
 ## [0.2.0] - 2026-10-26
 
 ### Added
@@ -36,6 +53,8 @@ Add each user-visible change under Unreleased as it lands, in one of: Added, Cha
 - 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
+[Unreleased]: https://github.com/nledford/omp-coord/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/nledford/omp-coord/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/nledford/omp-coord/compare/v0.2.0...v0.2.1
 [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/README.md

@@ -1,5 +1,10 @@
 # omp-coord
 
+[![CI](https://github.com/nledford/omp-coord/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/nledford/omp-coord/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@nledford/omp-coord)](https://www.npmjs.com/package/@nledford/omp-coord)
+[![omp](https://img.shields.io/badge/omp-%E2%89%A5%2018.12-blue)](https://github.com/can1357/oh-my-pi)
+[![License: MIT](https://img.shields.io/github/license/nledford/omp-coord)](LICENSE)
+
 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.
@@ -16,7 +21,7 @@ Each session gets a letter and shows `coord B · work 5/8 · short 1/2` in omp's
 ## Quick start
 
 ```sh
-omp plugin install "git+ssh://git@github.com/nledford/omp-coord.git"
+omp plugin install @nledford/omp-coord
 ```
 
 Then put a `.omp-coord.json` in the project's top folder:
@@ -36,12 +41,12 @@ Every omp session started in that folder or below now shares 6 agent slots, and
 
 | | |
 |---|---|
-| [Install](docs/install.md) | Plugin install over SSH or the marketplace, updating, the `omp-coord` command. |
+| [Install](docs/install.md) | From npm, GitHub, the marketplace or GitHub Packages; 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. |
+| [Commands](docs/commands.md) | `/coord`, agent tools, CLI (`status --json` for scripts), 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. |
 

package/docs/commands.md

@@ -5,6 +5,7 @@
 | Command | Does |
 |---|---|
 | `/coord` | Sessions, slots, the line, claims, queues, the latest decisions; marks a paused scope and sessions reading a different config file. |
+| `/coord agents` | The agents holding slots, one line each: session, id, type, parent (`Main` or an agent id), pool or `outside the caps`, state and age. Use it to see who runs, and what type each is, before messaging them. |
 | `/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. |
@@ -26,12 +27,70 @@
 
 ```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 status [--agents | --json] | 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.
 
+### `status`
+
+`omp-coord status` prints the same overview as `/coord`. `--agents` prints only the running agents, as `/coord agents` does:
+
+```text
+Agents (3):
+  A  Fixer        task      parent Main   pool work         running  5 min
+  A  Fixer.Check  reviewer  parent Fixer  outside the caps  running  4 min
+  B  Other        task      parent Main   pool work         running  2 min
+```
+
+Each line is the session letter, the agent's id (`(no id yet)` for an approved spawn omp gave no key for), its type, its parent, its pool, its state (`running`, or `starting` until its first run is seen) and how long ago it took its slot.
+
+`--json` prints the board as one JSON object on stdout, for scripts. It is built whole before anything is written: if the board cannot be read, nothing goes to stdout, the error goes to stderr, and the exit code is not `0` (`2` for a usage or configuration error, `1` otherwise). `--json` and `--agents` do not combine.
+
+Every time is milliseconds since the epoch (`Date.now()`); a session is its letter, or `null` when there is none (a job started outside omp, or by a session that has ended). Fields are never omitted: a missing value is `null`, a list is `[]`. Removing or renaming a field is a breaking change ([versioning](versioning.md)); new fields may appear.
+
+| Field | Meaning |
+|---|---|
+| `generatedAt` | When the object was built. |
+| `scope` | `{ name, source }`: the scope and the config file it was read from. |
+| `paused` | `null`, or `{ by, byId, reason, since }`: `by` is the pausing session's letter, `byId` its id; both are `null` for a pause from a terminal, and only `by` once that session has ended. |
+| `load` | The load average the limits act on, or `null` without a fresh reading. |
+| `sessions[]` | `letter`, `id`, `folder`, `pid`, `since`, `agents` (`{ pools: { <pool>: slots held }, outsideCaps }`), `ports` (`{ from, to }` or `null`), `differentConfig` (read another config file than this scope's). By letter. |
+| `pools[]` | `name`, `used`, `cap` (now: lowered under load, `0` while paused), `configuredCap`. |
+| `line[]` | Sessions waiting for a slot: `pool`, `session`, `position` (from 1), `since`, `heldUntil` (`null` unless a freed slot is held for it). |
+| `agents[]` | One per agent holding a slot, by session letter then `since`: `id` (`null` for a spawn with no key and no first run yet), `type`, `parent` (`Main` or an agent id), `session`, `pool` (`null`: outside the caps), `state` (`starting` or `running`), `since`. |
+| `claims[]` | `kind` (`branch`, `worktree`, `pr`), `target`, `session`, `agent`, `note`, `since`. |
+| `queues[]` | `name`, `order`, `slots` (now), `configuredSlots`, `running[]` and `waiting[]` (in the order they will start), each job: `id`, `session`, `owner` (the owning session's id, or `null` outside omp), `lane`, `priority`, `key` (or `null`), `command`, `state`, `queuedAt`, `startedAt` (`null` while waiting), `position` (from 1 while waiting, `null` while running). |
+| `notes[]` | The latest three decisions, oldest first: `id`, `at`, `session` (the letter when it was written, kept after that session ends; `null` outside omp), `author`, `text`. |
+
+```json
+{
+  "generatedAt": 1793000000000,
+  "scope": { "name": "demo", "source": "/work/demo/.omp-coord.json" },
+  "paused": null,
+  "load": 3.5,
+  "sessions": [
+    { "letter": "A", "id": "7f3c…", "folder": "/work/demo", "pid": 4210, "since": 1792999000000,
+      "agents": { "pools": { "work": 1 }, "outsideCaps": 1 }, "ports": null, "differentConfig": false }
+  ],
+  "pools": [{ "name": "work", "used": 1, "cap": 2, "configuredCap": 2 }],
+  "line": [],
+  "agents": [
+    { "id": "Fixer", "type": "task", "parent": "Main", "session": "A", "pool": "work", "state": "running", "since": 1792999300000 },
+    { "id": "Fixer.Check", "type": "reviewer", "parent": "Fixer", "session": "A", "pool": null, "state": "running", "since": 1792999400000 }
+  ],
+  "claims": [],
+  "queues": [
+    { "name": "heavy", "order": "fifo", "slots": 1, "configuredSlots": 1,
+      "running": [{ "id": "a1b2c3d4", "session": "A", "owner": "7f3c…", "lane": "normal", "priority": 0, "key": "demo ci",
+                    "command": "cargo test", "state": "running", "queuedAt": 1792999500000, "startedAt": 1792999500000, "position": null }],
+      "waiting": [] }
+  ],
+  "notes": []
+}
+```
+
 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

package/docs/coordination.md

@@ -38,4 +38,4 @@ With `resources.ports`, each session gets its own block of ports, in `OMP_COORD_
 
 `/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.
+`/coord agents` (or `omp-coord status --agents`) lists who runs: each agent's session, id, type, parent, pool and age, so a message to `B/<agent id>` goes to the agent you mean. `/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/install.md

@@ -2,43 +2,50 @@
 
 Requires omp 18.12 or later. No dependencies at runtime: the extension and the runner use the Bun built into omp.
 
-## From GitHub Packages
+## From npm
+
+```sh
+omp plugin install @nledford/omp-coord
+omp plugin install @nledford/omp-coord@0.2.0   # a given release
+```
+
+Releases are published to npmjs.com from the release workflow, with [provenance](https://docs.npmjs.com/generating-provenance-statements) that ties each package to the commit and workflow that built it (from 0.2.1 on). A machine set up for GitHub Packages (below) maps the `@nledford` scope to GitHub, so this command installs from there instead.
 
-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`.
+## From GitHub
 
 ```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
+omp plugin install github:nledford/omp-coord
 ```
 
-Then install a release, or the newest one:
+Or through omp's marketplace, which this repository also serves:
 
 ```sh
-omp plugin install @nledford/omp-coord@0.2.0
-omp plugin install @nledford/omp-coord
+omp plugin marketplace add nledford/omp-coord
+omp plugin install omp-coord@omp-coord
 ```
 
-## From GitHub
+## From GitHub Packages
 
-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:
+Each release is also published to GitHub Packages. GitHub Packages asks for a token to install any npm package, public ones included, 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
-omp plugin install "git+ssh://git@github.com/nledford/omp-coord.git"
+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
 ```
 
-Or through omp's marketplace, which this repository also serves:
+Then install a release, or the newest one:
 
 ```sh
-omp plugin marketplace add git@github.com:nledford/omp-coord.git
-omp plugin install omp-coord@omp-coord
+omp plugin install @nledford/omp-coord@0.2.0
+omp plugin install @nledford/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.
+`omp plugin upgrade @nledford/omp-coord` moves a package or git 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 install resolved to, so installing from git again can bring back an older commit; to pin a release, add its tag: `github:nledford/omp-coord#v0.2.0`. [CHANGELOG.md](../CHANGELOG.md) lists what each release changed.
 
 ## From a checkout
 

package/docs/versioning.md

@@ -8,6 +8,7 @@ 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 fields of `omp-coord status --json` ([commands](commands.md#status));
 - 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));

package/package.json

@@ -1,9 +1,6 @@
 {
   "name": "@nledford/omp-coord",
-  "version": "0.2.0",
-  "publishConfig": {
-    "registry": "https://npm.pkg.github.com"
-  },
+  "version": "0.2.2",
   "files": [
     "src",
     "docs",
@@ -16,7 +13,7 @@
   "author": "Nathaniel Ledford",
   "repository": {
     "type": "git",
-    "url": "https://github.com/nledford/omp-coord.git"
+    "url": "git+https://github.com/nledford/omp-coord.git"
   },
   "keywords": [
     "omp",

package/src/adapters/cli/cli.ts

@@ -4,7 +4,7 @@
  * terminals, or agents' bash calls (which the extension rewrites to go through here), and reports on the scope.
  *
  *   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 status [--agents | --json] | stats [days] | interrupted [hours] | notes [count] | note <text…>
  *   omp-coord pause [reason…] | resume | doctor [--fix]
  *
  * `run` waits for a slot, runs the command with the terminal's stdin/stdout/stderr, and exits with its exit code.
@@ -14,7 +14,7 @@
  * 2 a usage or configuration error.
  */
 import { randomBytes } from "node:crypto";
-import { mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { mkdirSync, readdirSync, statSync } from "node:fs";
 import { constants, userInfo } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
@@ -22,10 +22,19 @@ import { Coordinator } from "../../app/coordinator.ts";
 import { doctor } from "../../app/doctor.ts";
 import { EXIT_TIMED_OUT, runJob } from "../../app/job-runner.ts";
 import { type Config, ConfigError, findConfigFile, loadConfig } from "../../config.ts";
+import { statusView } from "../../domain/overview.ts";
 import { MAX_PRIORITY } from "../../domain/queues.ts";
 import { osLoad } from "../os/load.ts";
+import { groupRunning } from "../os/process-group.ts";
 import { BoardStore, stateDir } from "../sqlite/store.ts";
-import { formatFindings, formatInterrupted, formatNotes, formatStats, formatStatus } from "../text/report.ts";
+import {
+  formatAgents,
+  formatFindings,
+  formatInterrupted,
+  formatNotes,
+  formatStats,
+  formatStatus,
+} from "../text/report.ts";
 import { startBeacon, unixLiveness } from "../unix/beacon.ts";
 
 const EXIT_USAGE = 2;
@@ -35,18 +44,49 @@ const DAY = 86_400_000;
 
 const USAGE = `usage:
   omp-coord run <queue> [--lane L] [--priority N] [--key K] [--owner SESSION] [--timeout 90m] -- <command…>
-  omp-coord status | stats [days] | interrupted [hours] | notes [count] | note <text…>
+  omp-coord status [--agents | --json] | stats [days] | interrupted [hours] | notes [count] | note <text…>
   omp-coord pause [reason…] | resume | doctor [--fix]`;
 
 class UsageError extends Error {}
 
+/**
+ * `status` prints the board as text; `--agents` lists only the running agents; `--json` prints one JSON object. The
+ * output is built whole before anything is written, so a board that cannot be read leaves stdout empty.
+ */
+function status(args: string[]): Promise<number> {
+  let flags: ReturnType<typeof parseStatusFlags>;
+  try {
+    flags = parseStatusFlags(args);
+  } catch (error) {
+    throw new UsageError(`omp-coord status: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const { agents, json } = flags.values;
+  if (flags.positionals.length > 0 || (agents && json))
+    throw new UsageError("omp-coord status: give no arguments, or one of --agents and --json");
+  return withScope(({ config, coordinator }) => {
+    const board = coordinator.board();
+    const now = Date.now();
+    if (json) return print(JSON.stringify(statusView(board, config, now), null, 2));
+    return print(agents ? formatAgents(board, now) : formatStatus(board, config, "", now));
+  });
+}
+
+function parseStatusFlags(args: string[]) {
+  return parseArgs({
+    args,
+    allowPositionals: true,
+    strict: true,
+    options: { agents: { type: "boolean" }, json: { type: "boolean" } },
+  });
+}
+
 async function main(argv: string[]): Promise<number> {
   const [sub, ...rest] = argv;
   switch (sub) {
     case "run":
       return run(rest);
     case "status":
-      return withScope(({ config, coordinator }) => print(formatStatus(coordinator.board(), config, "", Date.now())));
+      return status(rest);
     case "stats":
       return withScope(({ coordinator }) =>
         print(formatStats(coordinator.stats(wholeNumber(rest[0], 7, "days") * DAY))),
@@ -309,32 +349,6 @@ function signalNumber(signal: NodeJS.Signals): number {
   return constants.signals[signal] ?? 1;
 }
 
-/**
- * Whether process group `pgid` still has a member that has not exited. A signal to the group succeeds while it holds
- * only zombies, which is what an exited command's children become in a container whose first process never reaps
- * orphans; on Linux, /proc tells them apart. Elsewhere (macOS has no /proc; launchd reaps orphans) the signal decides.
- */
-function groupRunning(pgid: number): boolean {
-  try {
-    process.kill(-pgid, 0);
-  } catch {
-    return false;
-  }
-  if (process.platform !== "linux") return true;
-  for (const entry of readdirSync("/proc")) {
-    if (!/^\d+$/.test(entry)) continue;
-    try {
-      // /proc/<pid>/stat: "pid (comm) state ppid pgrp …"; comm may contain spaces and parentheses.
-      const stat = readFileSync(`/proc/${entry}/stat`, "utf8");
-      const [state, , pgrp] = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
-      if (Number(pgrp) === pgid && state !== "Z") return true;
-    } catch {
-      // The process ended while being read.
-    }
-  }
-  return false;
-}
-
 if (import.meta.main) {
   try {
     process.exitCode = await main(Bun.argv.slice(2));

package/src/adapters/omp/extension.ts

@@ -20,7 +20,15 @@ import { decideCommand } from "../../domain/commands.ts";
 import type { Claim } from "../../domain/model.ts";
 import { osLoad } from "../os/load.ts";
 import { BoardStore, stateDir } from "../sqlite/store.ts";
-import { clock, formatFooter, formatInterrupted, formatNotes, formatStats, formatStatus } from "../text/report.ts";
+import {
+  clock,
+  formatAgents,
+  formatFooter,
+  formatInterrupted,
+  formatNotes,
+  formatStats,
+  formatStatus,
+} from "../text/report.ts";
 import { startBeacon, unixLiveness } from "../unix/beacon.ts";
 import type { ExtensionAPI, ExtensionContext, Timer, ToolResult } from "./api.ts";
 
@@ -334,7 +342,7 @@ export default function ompCoord(pi: ExtensionAPI): void {
 
   pi.registerCommand("coord", {
     description:
-      "Coordination with other omp sessions: `/coord` status; `send <letter|B/agent|all> <text>`; `pause [reason]`, `resume`; " +
+      "Coordination with other omp sessions: `/coord` status; `agents`; `send <letter|B/agent|all> <text>`; `pause [reason]`, `resume`; " +
       "`claim <branch|worktree|pr> <target> [note]`, `release <kind> <target>`; `note <text>`, `notes [n]`; `stats [days]`; `interrupted [hours]`",
     async handler(args, ctx) {
       const rt = shared.runtime;
@@ -349,6 +357,8 @@ export default function ompCoord(pi: ExtensionAPI): void {
         switch (sub) {
           case "":
             return ctx.ui.notify(statusText(rt), "info");
+          case "agents":
+            return ctx.ui.notify(formatAgents(rt.coordinator.board(), Date.now()), "info");
           case "send": {
             const m = /^(\S+)\s+([\s\S]+)$/.exec(tail);
             return say(

package/src/adapters/os/process-group.ts

@@ -0,0 +1,44 @@
+/**
+ * Whether a process group still has a member that has not exited, for stopping a timed-out job's whole group.
+ *
+ * A signal to the group succeeds while it holds only zombies, which is what an exited command's children become in a
+ * container whose first process never reaps orphans. On Linux, /proc tells them apart. Elsewhere (macOS has no /proc;
+ * launchd reaps orphans), or when /proc cannot be read, the signal decides.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+
+/** The state and process group of a process, from the text of `/proc/<pid>/stat`. */
+export function parseProcStat(stat: string): { state: string; pgrp: number } | undefined {
+  // "pid (comm) state ppid pgrp …": comm may contain spaces and parentheses, so fields start after the last ")".
+  const close = stat.lastIndexOf(")");
+  if (close === -1) return undefined;
+  const [state, , pgrp] = stat.slice(close + 2).split(" ");
+  const group = Number(pgrp);
+  return state && Number.isInteger(group) ? { state, pgrp: group } : undefined;
+}
+
+export function groupRunning(pgid: number): boolean {
+  try {
+    process.kill(-pgid, 0);
+  } catch {
+    return false;
+  }
+  if (process.platform !== "linux") return true;
+  let pids: string[];
+  try {
+    pids = readdirSync("/proc").filter(entry => /^\d+$/.test(entry));
+  } catch {
+    return true;
+  }
+  for (const pid of pids) {
+    let stat: string;
+    try {
+      stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    } catch {
+      continue; // ended while being read, or hidden
+    }
+    const p = parseProcStat(stat);
+    if (p?.pgrp === pgid && p.state !== "Z") return true;
+  }
+  return false;
+}

package/src/adapters/text/report.ts

@@ -6,6 +6,7 @@ import { pauseReason } from "../../domain/control.ts";
 import type { DayStats, InterruptedSession } from "../../domain/history.ts";
 import { currentLoad } from "../../domain/limits.ts";
 import { type AgentPolicy, type Board, labelOf, type Note } from "../../domain/model.ts";
+import { agentList, LATEST_NOTES } from "../../domain/overview.ts";
 import { orderWaiting, type Queues, slotsOf } from "../../domain/queues.ts";
 
 export function clock(ms: number): string {
@@ -14,6 +15,37 @@ export function clock(ms: number): string {
 
 const minutes = (ms: number) => `${Math.round(ms / 60_000)} min`;
 
+/** `45 s`, `12 min`, `2 h 5 min`. */
+function age(ms: number): string {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  if (seconds < 60) return `${seconds} s`;
+  const mins = Math.floor(seconds / 60);
+  return mins < 60 ? `${mins} min` : `${Math.floor(mins / 60)} h ${mins % 60} min`;
+}
+
+/**
+ * The agents holding slots, one line each: session letter, id, type, parent, pool, state and how long ago the slot was
+ * taken. A starting agent's id is the spawn key omp gave, or `(no id yet)`.
+ */
+export function formatAgents(board: Board, now: number): string {
+  const agents = agentList(board);
+  if (agents.length === 0) return "No agents are running.";
+  const rows = agents.map(a => [
+    a.session ?? "?",
+    a.id ?? "(no id yet)",
+    a.type,
+    `parent ${a.parent}`,
+    a.pool === null ? "outside the caps" : `pool ${a.pool}`,
+    a.state,
+    age(now - a.since),
+  ]);
+  const widths = rows[0]?.map((_, c) => Math.max(...rows.map(r => (r[c] as string).length))) ?? [];
+  return [
+    `Agents (${agents.length}):`,
+    ...rows.map(r => `  ${r.map((cell, c) => (c === r.length - 1 ? cell : cell.padEnd(widths[c] ?? 0))).join("  ")}`),
+  ].join("\n");
+}
+
 /** Everything on the board, from the view of session `me` ("" outside omp). */
 export function formatStatus(board: Board, config: Config, me: string, now: number): string {
   const policy = config.agents;
@@ -80,7 +112,7 @@ export function formatStatus(board: Board, config: Config, me: string, now: numb
   const queueLines = formatQueues(board, config.queues, now);
   if (queueLines.length) lines.push("Build and test queues:", ...queueLines);
 
-  const recent = board.notes.slice(-3);
+  const recent = board.notes.slice(-LATEST_NOTES);
   if (recent.length)
     lines.push(
       "Latest decisions (all: notes):",

package/src/domain/overview.ts

@@ -0,0 +1,212 @@
+/**
+ * The board as plain data for readers: `omp-coord status --json` prints a `StatusView`, and the text reports format
+ * its `agents`. Pure: callers pass `now` and the policies. Every time is milliseconds since the epoch; a session is
+ * named by its letter, or null when there is none (a job started outside omp, or by a session that has ended).
+ *
+ * The field names are part of the contract (docs/commands.md, docs/versioning.md): rename or remove one only as a
+ * breaking change.
+ */
+import { capOf, used } from "./agents.ts";
+import { currentLoad } from "./limits.ts";
+import { type AgentPolicy, type Board, labelOf } from "./model.ts";
+import { orderWaiting, type Queues, slotsOf } from "./queues.ts";
+
+/** What the view needs of the scope's configuration. `Config` satisfies it. */
+export interface ScopeConfig {
+  scope: string;
+  /** The config file the scope was read from. */
+  source: string;
+  /** Hash of that file; sessions that read another one are flagged. */
+  hash: string;
+  agents: AgentPolicy;
+  queues: Queues;
+}
+
+/** How many of the latest notes the view carries. */
+export const LATEST_NOTES = 3;
+
+export interface AgentView {
+  /** omp's agent id; null for an approved spawn whose first run has not started and that omp gave no key for. */
+  id: string | null;
+  type: string;
+  /** `Main` or the id of the subagent that started it. */
+  parent: string;
+  /** Letter of the session it runs in. */
+  session: string | null;
+  /** The pool holding its slot; null outside the caps (exempt types and nested reviewers). */
+  pool: string | null;
+  /** `starting`: approved, first run not seen yet. */
+  state: "starting" | "running";
+  /** When it took its slot. */
+  since: number;
+}
+
+export interface JobView {
+  id: string;
+  /** Letter of the session whose agent started it; null outside omp or once that session ended. */
+  session: string | null;
+  /** The owning session's id; null outside omp. */
+  owner: string | null;
+  lane: string;
+  priority: number;
+  key: string | null;
+  command: string;
+  state: "running" | "waiting";
+  /** When it joined the line (a superseding job keeps the place of the one it replaced). */
+  queuedAt: number;
+  /** When it started; null while waiting. */
+  startedAt: number | null;
+  /** Place in line, from 1, in the order jobs will start; null while running. */
+  position: number | null;
+}
+
+export interface StatusView {
+  /** When the view was built. */
+  generatedAt: number;
+  scope: { name: string; source: string };
+  /** `by` is the pausing session's letter; null from a terminal, or once that session ended (`byId` tells which). */
+  paused: { by: string | null; byId: string | null; reason: string; since: number } | null;
+  /** The load average the limits act on; null without a fresh reading. */
+  load: number | null;
+  sessions: {
+    letter: string;
+    id: string;
+    folder: string;
+    pid: number;
+    since: number;
+    /** Slots held per configured pool, and agents outside the caps. */
+    agents: { pools: Record<string, number>; outsideCaps: number };
+    ports: { from: number; to: number } | null;
+    /** Whether it read a different config file than this scope's. */
+    differentConfig: boolean;
+  }[];
+  pools: { name: string; used: number; cap: number; configuredCap: number }[];
+  /** Sessions waiting for a slot, per pool, first in line first. */
+  line: { pool: string; session: string | null; position: number; since: number; heldUntil: number | null }[];
+  agents: AgentView[];
+  claims: {
+    kind: string;
+    target: string;
+    session: string | null;
+    agent: string;
+    note: string;
+    since: number;
+  }[];
+  queues: {
+    name: string;
+    order: string;
+    /** Slots now: lowered under load, 0 while paused. */
+    slots: number;
+    configuredSlots: number;
+    running: JobView[];
+    waiting: JobView[];
+  }[];
+  /** The latest notes, oldest first. `session` is the letter when the note was written, kept after that session ends. */
+  notes: { id: number; at: number; session: string | null; author: string; text: string }[];
+}
+
+/** Every agent holding a slot, by session letter then start. */
+export function agentList(board: Board): AgentView[] {
+  return board.slots
+    .map(s => ({
+      id: s.agentId ?? null,
+      type: s.agentType,
+      parent: s.parentId,
+      session: labelOf(board, s.sessionId) ?? null,
+      pool: s.pool,
+      state: s.state,
+      since: s.since,
+    }))
+    .sort(
+      (a, b) =>
+        (a.session ?? "").localeCompare(b.session ?? "") || a.since - b.since || (a.id ?? "").localeCompare(b.id ?? ""),
+    );
+}
+
+export function statusView(board: Board, config: ScopeConfig, now: number): StatusView {
+  const policy = config.agents;
+  const letter = (sessionId: string | null) => (sessionId === null ? null : (labelOf(board, sessionId) ?? null));
+  const pools = Object.keys(policy.pools);
+
+  const job = (j: Board["jobs"][number], position: number | null): JobView => ({
+    id: j.id,
+    session: letter(j.owner),
+    owner: j.owner,
+    lane: j.lane,
+    priority: j.priority,
+    key: j.key ?? null,
+    command: j.command,
+    state: position === null ? "running" : "waiting",
+    queuedAt: j.since,
+    startedAt: j.startedAt ?? null,
+    position,
+  });
+
+  const paused = board.pause;
+  return {
+    generatedAt: now,
+    scope: { name: config.scope, source: config.source },
+    paused: paused ? { by: letter(paused.by), byId: paused.by, reason: paused.reason, since: paused.since } : null,
+    load: currentLoad(board, now) ?? null,
+    sessions: [...board.sessions]
+      .sort((a, b) => a.label.localeCompare(b.label))
+      .map(s => {
+        const held = board.slots.filter(x => x.sessionId === s.id);
+        return {
+          letter: s.label,
+          id: s.id,
+          folder: s.cwd,
+          pid: s.pid,
+          since: s.startedAt,
+          agents: {
+            pools: Object.fromEntries(pools.map(p => [p, held.filter(x => x.pool === p).length])),
+            outsideCaps: held.filter(x => x.pool === null).length,
+          },
+          ports: s.ports ? { from: s.ports.from, to: s.ports.to } : null,
+          differentConfig: s.configHash !== config.hash,
+        };
+      }),
+    pools: pools.map(name => ({
+      name,
+      used: used(board, name),
+      cap: capOf(board, policy, name, now),
+      configuredCap: policy.pools[name]?.cap ?? 0,
+    })),
+    line: pools.flatMap(pool =>
+      board.waitlist
+        .filter(t => t.pool === pool)
+        .sort((a, b) => a.since - b.since)
+        .map((t, i) => ({
+          pool,
+          session: letter(t.sessionId),
+          position: i + 1,
+          since: t.since,
+          heldUntil: t.holdUntil ?? null,
+        })),
+    ),
+    agents: agentList(board),
+    claims: board.claims.map(c => ({
+      kind: c.kind,
+      target: c.target,
+      session: letter(c.sessionId),
+      agent: c.agentId,
+      note: c.note,
+      since: c.since,
+    })),
+    queues: Object.entries(config.queues).map(([name, q]) => ({
+      name,
+      order: q.order,
+      slots: slotsOf(board, q, now),
+      configuredSlots: q.slots,
+      running: board.jobs.filter(j => j.queue === name && j.state === "running").map(j => job(j, null)),
+      waiting: orderWaiting(q, name, board, now).map((j, i) => job(j, i + 1)),
+    })),
+    notes: board.notes.slice(-LATEST_NOTES).map(n => ({
+      id: n.id,
+      at: n.at,
+      session: n.label,
+      author: n.author,
+      text: n.text,
+    })),
+  };
+}