@nledford/omp-coord 0.2.1 → 0.2.3

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.1",
+      "version": "0.2.3",
       "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.3] - 2026-10-27
+
+### Added
+
+- `tagAgentCommands` (off by default): each queued job records the agent whose command queued it, and the queue lines in `/coord` and `omp-coord status` read `session A/WaveImport`; `status --json` has `agent` on each job and the `job_queued` event carries it. With it on, the extension starts every agent bash command with `export OMP_COORD_AGENT=<agent id>;`, which `omp-coord run` reads; leave it off if you use omp's `bash.patterns` rules or another extension that rewrites bash commands. A board made by an older omp-coord gains the new column when this version opens it; while any session of the scope still runs an older omp-coord, its saves drop the recorded agents (display only).
+
+### Changed
+
+- A queue line shows the job's key (for example `rebase-2204 ci`) instead of its command when the job has one; the command still shows when it doesn't, and `status --json` keeps both.
+
+## [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
@@ -46,7 +63,9 @@ 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.1...HEAD
+[Unreleased]: https://github.com/nledford/omp-coord/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/nledford/omp-coord/compare/v0.2.2...v0.2.3
+[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

@@ -46,7 +46,7 @@ Every omp session started in that folder or below now shares 6 agent slots, and
 | [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`, `agent` (omp's id of the agent whose command queued it, `"Main"` for the main agent; `null` when `tagAgentCommands` is off, for a job started outside an agent's bash call, and while any session of the scope runs an omp-coord older than 0.2.3, whose saves drop it), `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
@@ -43,4 +102,5 @@ Exit codes: `0` success, the command's own for `run`, `75` a job not run, `124`
 | `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_AGENT` | the extension, with `tagAgentCommands` | The agent whose command this is (`Main` for the main agent); `omp-coord run` records it on the job. |
 | `OMP_COORD_JOB`, `OMP_COORD_QUEUE` | `omp-coord run` | The running job's id and queue, for nested runs. |

package/docs/configuration.md

@@ -21,6 +21,7 @@
 | `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. |
+| `tagAgentCommands` | `false` | Start each agent bash command with `export OMP_COORD_AGENT=<agent id>;`, so each queued job records the agent that queued it (queue lines read `session A/<agent>`). Leave it off when you use omp's `bash.patterns` allow or deny rules (a rewritten command no longer matches them) or another extension that rewrites bash commands (the last rewrite wins). |
 | `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. |

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/event-log.md

@@ -14,7 +14,7 @@ These tables are rebuilt as sessions come and go; their layout is not part of th
 | `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`. |
+| `jobs` | Queued and running build/test jobs: `id`, `queue`, `owner` (session id, or null outside omp), `lane`, `priority`, `key`, `command`, `agent` (null when not recorded), `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`. |
@@ -25,7 +25,7 @@ These tables are rebuilt as sessions come and go; their layout is not part of th
 `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`.
+- Jobs: `job_queued` (with `queue`, `lane`, `priority`, `key`, and `agent` when recorded), `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`.

package/docs/queues.md

@@ -49,4 +49,6 @@ A command that puts its work in the background (`cargo test &`) holds the slot o
 
 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.
 
+With `tagAgentCommands` on, the extension also starts every agent bash command with `export OMP_COORD_AGENT=<agent id>;`, and `omp-coord run` records that agent on the job: queue lines read `session A/WaveImport` instead of only `session A`. It is off by default because the rewritten command no longer matches omp's `bash.patterns` rules (they must match the whole command) and replaces any other extension's rewrite of the same call.
+
 A command matching a `refuse` rule is refused with the rule's reason.

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,6 +1,6 @@
 {
   "name": "@nledford/omp-coord",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "files": [
     "src",
     "docs",

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.
@@ -22,11 +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;
@@ -36,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))),
@@ -210,6 +249,8 @@ async function run(args: string[]): Promise<number> {
         id,
         queue,
         owner: values.owner || process.env.OMP_COORD_SESSION || null,
+        // set per command by the extension's bash hook
+        ...(process.env.OMP_COORD_AGENT ? { agent: process.env.OMP_COORD_AGENT } : {}),
         ...(values.lane === undefined ? {} : { lane: values.lane }),
         priority,
         ...(values.key === undefined ? {} : { key: values.key }),

package/src/adapters/omp/extension.ts

@@ -16,11 +16,19 @@ import { join, resolve } from "node:path";
 import { Coordinator } from "../../app/coordinator.ts";
 import type { Listener } from "../../app/ports.ts";
 import { type Config, ConfigError, findConfigFile, loadConfig } from "../../config.ts";
-import { decideCommand } from "../../domain/commands.ts";
+import { decideCommand, withAgent } 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";
 
@@ -182,7 +190,12 @@ export default function ompCoord(pi: ExtensionAPI): void {
       config: rt.config.source,
     });
     if (decision.kind === "refuse") return { block: true, reason: `omp-coord: ${decision.reason}` };
-    if (decision.kind === "queue") return { input: { ...event.input, command: decision.command } };
+    const run = decision.kind === "queue" ? decision.command : command;
+    // Every agent of a session shares the omp process's environment, so the agent's id can reach `omp-coord run` (and
+    // the queue lines) only through the command itself; opt-in (`tagAgentCommands`), since the rewrite defeats omp's
+    // bash.patterns rules and other extensions' rewrites. Off, the hook changes only queued commands, as before.
+    if (rt.config.tagAgentCommands) return { input: { ...event.input, command: withAgent(ctx.agent.id, run) } };
+    if (decision.kind === "queue") return { input: { ...event.input, command: run } };
     return undefined;
   });
 
@@ -334,7 +347,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 +362,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/sqlite/store.ts

@@ -77,6 +77,7 @@ CREATE TABLE jobs (
   priority   INTEGER NOT NULL,
   key        TEXT,
   command    TEXT NOT NULL,
+  agent      TEXT,
   socket     TEXT NOT NULL,
   pid        INTEGER NOT NULL,
   state      TEXT NOT NULL CHECK (state IN ('waiting', 'running', 'superseded')),
@@ -229,7 +230,10 @@ export class BoardStore implements BoardRepository {
 
   #migrate(): void {
     const version = this.#db.query<{ user_version: number }, []>("PRAGMA user_version").get()?.user_version ?? 0;
-    if (version === SCHEMA_VERSION) return;
+    if (version === SCHEMA_VERSION) {
+      this.#addColumns();
+      return;
+    }
     if (version !== 0) {
       throw new Error(
         `the board database has schema ${version}, but this omp-coord reads schema ${SCHEMA_VERSION}; update omp-coord`,
@@ -239,6 +243,20 @@ export class BoardStore implements BoardRepository {
     this.#db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
   }
 
+  /**
+   * Nullable columns added after schema 1 was released, without a version bump: a board made by an older omp-coord
+   * gets them here, and an older omp-coord still running (an omp session not yet restarted) keeps reading and
+   * writing the board, ignoring them (its saves write null there, which readers show as unknown).
+   */
+  #addColumns(): void {
+    const has = (table: string, column: string) =>
+      this.#db
+        .query<{ name: string }, []>(`PRAGMA table_info(${table})`)
+        .all()
+        .some(c => c.name === column);
+    if (!has("jobs", "agent")) this.#db.exec("ALTER TABLE jobs ADD COLUMN agent TEXT");
+  }
+
   #maybePruneEvents(now: number): void {
     const last = Number(
       this.#db.query<{ value: string }, []>("SELECT value FROM meta WHERE key = 'events_pruned_at'").get()?.value ?? 0,
@@ -337,6 +355,7 @@ export class BoardStore implements BoardRepository {
             priority: number;
             key: string | null;
             command: string;
+            agent: string | null;
             socket: string;
             pid: number;
             state: "waiting" | "running" | "superseded";
@@ -354,6 +373,7 @@ export class BoardStore implements BoardRepository {
           priority: r.priority,
           key: r.key ?? undefined,
           command: r.command,
+          agent: r.agent ?? undefined,
           socket: r.socket,
           pid: r.pid,
           state: r.state,
@@ -455,7 +475,7 @@ export class BoardStore implements BoardRepository {
     const sent = db.query("INSERT INTO sent (session_id, at) VALUES (?, ?)");
     for (const x of board.sent) sent.run(x.sessionId, x.at);
     const job = db.query(
-      "INSERT INTO jobs (id, queue, owner, lane, priority, key, command, socket, pid, state, since, started_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+      "INSERT INTO jobs (id, queue, owner, lane, priority, key, command, agent, socket, pid, state, since, started_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
     );
     for (const j of board.jobs) {
       job.run(
@@ -466,6 +486,7 @@ export class BoardStore implements BoardRepository {
         j.priority,
         j.key ?? null,
         j.command,
+        j.agent ?? null,
         j.socket,
         j.pid,
         j.state,

package/src/adapters/text/report.ts

@@ -5,7 +5,8 @@ import { capOf, used } from "../../domain/agents.ts";
 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 { type AgentPolicy, type Board, type Job, 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):",
@@ -94,8 +126,13 @@ export function formatStatus(board: Board, config: Config, me: string, now: numb
 /** One block per queue: running jobs, then waiting jobs in the order they will start. */
 export function formatQueues(board: Board, queues: Queues, now: number): string[] {
   const lines: string[] = [];
-  const who = (owner: string | null) =>
-    owner === null ? "outside omp" : `session ${labelOf(board, owner) ?? "(ended)"}`;
+  // whose job: the session, and the agent when recorded ("session A/WaveImport")
+  const who = (j: Job) =>
+    (j.owner === null ? "outside omp" : `session ${labelOf(board, j.owner) ?? "(ended)"}`) +
+    (j.agent ? `/${j.agent}` : "");
+  // what it is: the job's key ("<checkout> <recipe> <args>") reads better than the command's full path; the command
+  // when there is no key
+  const what = (j: Job) => j.key || j.command;
   for (const [name, q] of Object.entries(queues)) {
     const running = board.jobs.filter(j => j.queue === name && j.state === "running");
     const waiting = orderWaiting(q, name, board, now);
@@ -103,14 +140,14 @@ export function formatQueues(board: Board, queues: Queues, now: number): string[
     const lowered = slots < q.slots && !board.pause ? ` (lowered from ${q.slots} under load)` : "";
     lines.push(`  ${name} (${q.order}): ${running.length}/${slots} running${lowered}, ${waiting.length} waiting`);
     for (const j of running)
-      lines.push(`    running  ${j.id}  ${who(j.owner)}  ${minutes(now - (j.startedAt ?? now))}  ${j.command}`);
+      lines.push(`    running  ${j.id}  ${who(j)}  ${minutes(now - (j.startedAt ?? now))}  ${what(j)}`);
     for (const [i, j] of waiting.entries()) {
       const extras = [
         j.lane === q.lanes.at(-1) ? "" : `lane ${j.lane}`,
         j.priority ? `priority ${j.priority}` : "",
       ].filter(Boolean);
       lines.push(
-        `    #${i + 1}       ${j.id}  ${who(j.owner)}  waited ${minutes(now - j.since)}${extras.length ? ` (${extras.join(", ")})` : ""}  ${j.command}`,
+        `    #${i + 1}       ${j.id}  ${who(j)}  waited ${minutes(now - j.since)}${extras.length ? ` (${extras.join(", ")})` : ""}  ${what(j)}`,
       );
     }
   }

package/src/app/job-runner.ts

@@ -17,6 +17,8 @@ export interface JobSpec {
   id: string;
   queue: string;
   owner: string | null;
+  /** omp's id of the agent whose command this is, for display. */
+  agent?: string;
   lane?: string;
   priority: number;
   key?: string;

package/src/config.ts

@@ -26,6 +26,12 @@ export interface Config {
   commands: CommandRule[];
   /** Build and test queues, machine-wide within the scope. */
   queues: Queues;
+  /**
+   * Start each agent bash command with `export OMP_COORD_AGENT=<agent id>;` so queued jobs record whose they are.
+   * Off by default: the rewritten command no longer matches omp's `bash.patterns` rules and replaces other
+   * extensions' rewrites of the same call.
+   */
+  tagAgentCommands: boolean;
   /** Port ranges and scratch folders handed to sessions and their agents. */
   resources: { ports: PortPolicy | undefined; scratch: string | undefined };
   /** Retention of the event log and the decision log. */
@@ -185,6 +191,7 @@ export function parseConfig(raw: unknown, source: string, hash = "none"): Config
     },
     commands,
     queues,
+    tagAgentCommands: flag(root.tagAgentCommands ?? false, "tagAgentCommands", fail),
     resources: { ports, scratch },
     history: {
       maxAgeMs: count(history.retentionDays ?? 30, "history.retentionDays", fail) * 24 * 3_600_000,
@@ -205,6 +212,11 @@ function list(v: unknown, field: string, fail: Fail): unknown[] {
   return v;
 }
 
+function flag(v: unknown, field: string, fail: Fail): boolean {
+  if (typeof v !== "boolean") fail(field, "must be true or false");
+  return v as boolean;
+}
+
 function str(v: unknown, field: string, fail: Fail): string {
   if (typeof v !== "string" || v.trim() === "") return fail(field, "must be a non-empty string");
   return v;

package/src/domain/commands.ts

@@ -54,3 +54,12 @@ export function decideCommand(rules: CommandRule[], command: string, runner: Run
 function quote(word: string): string {
   return `'${word.replaceAll("'", `'\\''`)}'`;
 }
+
+/**
+ * The command with the id of the agent running it exported first, so a queued job records whose it is
+ * (`omp-coord run` reads `OMP_COORD_AGENT`). An export, not a `VAR=… cmd` prefix, so it reaches every command of a
+ * compound line; each agent's next command sets it again.
+ */
+export function withAgent(agentId: string, command: string): string {
+  return `export OMP_COORD_AGENT=${quote(agentId)}; ${command}`;
+}

package/src/domain/model.ts

@@ -158,6 +158,9 @@ export interface Job {
   queue: string;
   /** The omp session whose agent started it, or null (a terminal, a script). Fair share is per owner. */
   owner: string | null;
+  /** omp's id of the agent whose command queued it ("Main" for the main agent), or undefined (outside omp, or an
+   * older omp-coord that did not record it). For display only. */
+  agent: string | undefined;
   lane: string;
   priority: number;
   /** Jobs with the same key are duplicates (e.g. "<checkout> ci"). */

package/src/domain/overview.ts

@@ -0,0 +1,215 @@
+/**
+ * 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;
+  /** omp's id of the agent whose command queued it ("Main" for the main agent); null outside omp or when not recorded. */
+  agent: string | null;
+  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,
+    agent: j.agent ?? null,
+    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,
+    })),
+  };
+}

package/src/domain/queues.ts

@@ -43,6 +43,7 @@ export interface JobRequest {
   id: string;
   queue: string;
   owner: string | null;
+  agent?: string;
   lane?: string;
   priority: number;
   key?: string;
@@ -81,6 +82,7 @@ export function enqueueJob(board: Board, queues: Queues, req: JobRequest): Enque
     id: req.id,
     queue: req.queue,
     owner: req.owner,
+    agent: req.agent,
     lane,
     priority: req.priority,
     key: req.key,
@@ -97,6 +99,7 @@ export function enqueueJob(board: Board, queues: Queues, req: JobRequest): Enque
     lane,
     priority: req.priority,
     ...(req.key === undefined ? {} : { key: req.key }),
+    ...(req.agent === undefined ? {} : { agent: req.agent }),
   });
   schedule(board, queues, req.now);
   return { ok: true };