@nledford/omp-coord 0.2.3 → 0.3.0

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

package/CHANGELOG.md

@@ -6,6 +6,19 @@ Add each user-visible change under Unreleased as it lands, in one of: Added, Cha
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-27
+
+### Changed
+
+- **Breaking:** while a session is the only one in its scope, spawns past the cap now wait their turn instead of being refused (`agents.queueSpawns`, on by default): the extension keeps omp's per-session spawn queue (`task.maxConcurrency`) at what the caps allow the session, so you can start as many agents as you need and those past the cap start by themselves as slots free. With other sessions in the scope, or while paused, spawns over the cap are refused and the session joins the line, as before. A `task.maxConcurrency` you set stays the ceiling; the override is never saved and is cleared when the session ends. Set `agents.queueSpawns: false` to keep refusals always. See [agent slots](docs/agent-slots.md#spawns-wait-their-turn).
+- `coord_status` and `/coord` say whether this session's spawns wait in omp's queue right now, and if not, why (another session, paused, or every slot taken by agents outside the queue).
+
+### Fixed
+
+- With `tagAgentCommands` on, a command that already starts with `export OMP_COORD_AGENT=…;` (an agent repeating an earlier, rewritten call it saw in the conversation) gets exactly one prefix for the agent running it, instead of one more each time.
+- A release whose tag push GitHub delivers twice, or a release run again, no longer fails: release runs for one tag wait for each other, npm's current "already exists" (409) answer counts as already published once npm lists that version, and a GitHub release that exists already is left as it is.
+- With `tagAgentCommands` on, a copied prefix no longer ends up inside a queued job's own command.
+
 ## [0.2.3] - 2026-10-27
 
 ### Added
@@ -63,7 +76,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.3...HEAD
+[Unreleased]: https://github.com/nledford/omp-coord/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/nledford/omp-coord/compare/v0.2.3...v0.3.0
 [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

package/README.md

@@ -7,7 +7,7 @@
 
 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.
+- **Shared agent caps.** Subagents count against pools (for example 8 `work` and 2 `short` slots) shared by every session in the project. While a session is alone, spawns past the cap wait in omp's own queue and start by themselves as slots free; with other sessions, a spawn over the cap is refused through omp's spawn check and the session joins a fair line. 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.

package/docs/agent-slots.md

@@ -13,9 +13,22 @@ Subagents count against pools of slots (for example 8 `work` and 2 `short`) shar
 | 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. |
 
+## Spawns wait their turn
+
+With `agents.queueSpawns` (on by default), while a session is the only one in its scope, the extension keeps omp's own per-session spawn queue, the `task.maxConcurrency` setting, at the number of the session's spawns the caps let run now: its top-level agents already running or starting, the default pool's free slots, and one held for it there. Start as many agents as you need: omp starts the ones that fit and keeps the rest waiting in its queue, each starting as one of the session's agents ends. A value you set yourself for `task.maxConcurrency` stays the ceiling (it is read when the session starts). The value is a runtime override, never saved, and it is cleared when the session ends.
+
+When a second session joins the scope, or the scope is paused, the override is cleared and spawns over the cap are refused as described under The line below. omp re-reads its queue size only when the session asks for a spawn or one of its runs ends, and a spawn waiting in omp's queue never reaches the spawn check, so it would never join the line: across sessions, only refusals keep the line fair.
+
+Limits:
+
+- omp's queue holds every agent the main session starts, so a reviewer started by the main session waits its turn too, and an agent of another pool (for example `short`) starts only when a default-pool slot is free as well. Subagents read the same setting, so a worker's own reviewers queue under the same number; with `agents.nested.maxRunningPerParent` at 1 that never delays them. An eval workpool sizes itself from the same setting while its own workers take slots, so while a workpool's workers run the override is cleared and the spawn check decides.
+- Agents started outside omp's queue (revived with `write agent://…`, eval `agent()` and workpool workers) take slots the queue doesn't count. When one of them ends, waiting spawns start at the session's next spawn or run end, not at once. If they fill every slot, the override is cleared and spawns over the cap are refused.
+- A spawn approved but never started holds its slot until `agents.startTimeoutSeconds` runs out. If that leaves no free slot, the spawns waiting in omp's queue reach the spawn check one after another and are refused, until the slot is given back.
+- omp re-reads the setting only when the session asks for a spawn or one of its runs ends: when a second session joins, spawns already waiting in omp's queue reach the spawn check at that next moment.
+
 ## 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.
+A spawn over the cap that reaches the spawn check 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):
 
@@ -25,7 +38,7 @@ When one of B's agents ends, the slot is held for A, which is woken with a notic
 
 ![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.
+omp gives the spawn check 30 seconds and then lets the spawn through, so the extension never waits inside it: spawns wait in omp's queue before the check while the session is alone (above), and one that reaches it over the cap is refused at once, with the next free slot held. 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.
 

package/docs/configuration.md

@@ -12,6 +12,7 @@
 | `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. |
+| `agents.queueSpawns` | `true` | While the session is the only one in the scope, keep omp's per-session spawn queue (`task.maxConcurrency`) at what the caps allow it, so spawns past the cap wait and start by themselves instead of being refused ([agent slots](agent-slots.md#spawns-wait-their-turn)); with other sessions, or paused, spawns over the cap are refused as before. A `task.maxConcurrency` you set yourself stays the ceiling. `false` keeps the refusals always. |
 | `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, `.`, `_`, `-`. |

package/docs/versioning.md

@@ -31,14 +31,22 @@ There are no prereleases (`-rc.1` and the like): the marketplace catalog follows
 
 ## Cutting a release
 
-From `main`, with a clean work tree, not behind `origin/main`:
+Start on `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 fix               # or feature, breaking, or an exact version such as 1.0.0: a release-vX.Y.Z branch and commit
+just release-pr                # (on that branch) pushes it and opens its pull request; merge it once CI passes
+git switch main && git pull    # main now holds the release
+just release-publish           # asks, then tags the release on main and pushes only the tag; CI 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.
+`main` and the release tags are protected by repository rulesets: `main` changes only by pull request with CI passing, never by force or deletion, and a `vX.Y.Z` tag, once pushed, can't be moved or deleted. So a release reaches `main` by its own pull request, and only the tag is pushed directly. Any merge method works.
 
-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.
+`just release` refuses an empty Unreleased section in the changelog, then creates the `release-vX.Y.Z` branch, sets the version in `package.json` and the marketplace catalog, dates the changelog, runs the checks and commits `Release vX.Y.Z`, all locally. If anything fails, the files are put back and you stay on (or return to) `main` with no branch left. The version changes only in release commits, because omp upgrades marketplace installs only when the catalog's version goes up.
+
+`just release-publish` tags the commit on `main` that added the dated changelog section of the new version (the merge, squash or rebased commit), even if other pull requests merged after it, and refuses if `origin` already has that tag. A push that failed can be run again.
+
+Once the release PR is merged, marketplace installs (which follow `main`) can see the new version before the tag and the GitHub release exist, so run `just release-publish` right after merging.
+
+The release workflow checks that the tag is on `main` and matches the version files and the changelog, runs the checks on macOS, publishes the packages and creates the GitHub release with the changelog entry as its notes. If it fails for a passing reason (a registry or runner hiccup), re-run it: it skips what is already published. If the tagged code itself is broken, the version is used up (tags can't move): fix it and release the next patch version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nledford/omp-coord",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "files": [
     "src",
     "docs",

package/src/adapters/omp/api.ts

@@ -66,6 +66,8 @@ export interface ZodString {
 
 export interface ExtensionAPI {
   on<K extends keyof Events>(event: K, handler: Events[K]): void;
+  /** The host session; `settings` is the scope omp's typed setting handles take. */
+  pi?: { settings?: unknown };
   setLabel(label: string): void;
   registerTool<P>(tool: {
     name: string;

package/src/adapters/omp/extension.ts

@@ -16,7 +16,8 @@ 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, withAgent } from "../../domain/commands.ts";
+import { spawnAllowance } from "../../domain/agents.ts";
+import { decideCommand, withAgent, withoutAgentExports } from "../../domain/commands.ts";
 import type { Claim } from "../../domain/model.ts";
 import { osLoad } from "../os/load.ts";
 import { BoardStore, stateDir } from "../sqlite/store.ts";
@@ -31,6 +32,7 @@ import {
 } from "../text/report.ts";
 import { startBeacon, unixLiveness } from "../unix/beacon.ts";
 import type { ExtensionAPI, ExtensionContext, Timer, ToolResult } from "./api.ts";
+import { loadSettingHandle, type SpawnQueue, spawnQueue } from "./spawn-queue.ts";
 
 /**
  * How agents' queued commands start the runner: the omp binary itself runs the CLI adapter as Bun
@@ -60,6 +62,12 @@ interface Runtime {
   ticks: number;
   footer: string | undefined;
   pruning: boolean;
+  /** Drives omp's spawn queue (`agents.queueSpawns`); undefined when off or unavailable. */
+  queue: SpawnQueue | undefined;
+  /** Whether spawns past the cap wait in omp's queue, or why not; shown in coord_status and /coord. */
+  queueNote: string;
+  /** Agents first started by an eval spawn (workpool workers): their later runs are marked "eval" too. */
+  evalAgents: Set<string>;
 }
 
 interface Shared {
@@ -68,13 +76,17 @@ interface Shared {
   inactive: string;
   /** Each subagent's binding, by agent id: a message for that subagent is sent through it. */
   bindings: Map<string, ExtensionAPI>;
+  /** Main-session bindings that shut down, so a `start` for one that awaited across its own shutdown gives up. */
+  shutDown: WeakSet<ExtensionAPI>;
 }
 
 /** Shared by every copy of this module in the process (omp re-imports extensions for isolated subagents). */
 const shared: Shared = (() => {
   const store = globalThis as { [key: symbol]: Shared | undefined };
   const key = Symbol.for("omp-coord.runtime");
-  store[key] ??= { runtime: undefined, inactive: NO_CONFIG, bindings: new Map() };
+  store[key] ??= { runtime: undefined, inactive: NO_CONFIG, bindings: new Map(), shutDown: new WeakSet() };
+  // a copy made by an older version of this module in the same process has no set yet
+  store[key].shutDown ??= new WeakSet();
   return store[key];
 })();
 
@@ -99,23 +111,24 @@ export default function ompCoord(pi: ExtensionAPI): void {
       if (shared.bindings.get(ctx.agent.id) === pi) shared.bindings.delete(ctx.agent.id);
       return;
     }
+    shared.shutDown.add(pi);
     if (shared.runtime?.pi === pi) stop(shared.runtime);
   });
 
   pi.on("before_subagent_spawn", (event, ctx) => {
     const rt = shared.runtime;
     if (!rt) return undefined;
+    let decision: ReturnType<Coordinator["requestSpawn"]>;
     try {
-      const decision = rt.coordinator.requestSpawn({
+      decision = rt.coordinator.requestSpawn({
         sessionId: rt.sessionId,
         parentAgentId: ctx.agent.id,
         parentIsSubagent: ctx.agent.kind === "sub",
         agentType: event.agent.toLowerCase(),
         ...(event.spawnKey === undefined ? {} : { spawnKey: event.spawnKey }),
+        ...(event.invocationKind === undefined ? {} : { invocationKind: event.invocationKind }),
       });
-      if (decision.allowed) return undefined;
-      notify(rt, `omp-coord refused ${event.agent} from ${ctx.agent.id}: ${decision.reason}`, "warning");
-      return { block: true, reason: `omp-coord: ${decision.reason}` };
+      if (event.invocationKind === "eval" && event.spawnKey !== undefined) rt.evalAgents.add(event.spawnKey);
     } catch (error) {
       // The cap is a shared agreement, not a security boundary: a broken board must not stop all work.
       notify(
@@ -125,6 +138,11 @@ export default function ompCoord(pi: ExtensionAPI): void {
       );
       return undefined;
     }
+    // outside the decision: a failure here must never turn a refusal into a start
+    refreshQueue(rt);
+    if (decision.allowed) return undefined;
+    notify(rt, `omp-coord refused ${event.agent} from ${ctx.agent.id}: ${decision.reason}`, "warning");
+    return { block: true, reason: `omp-coord: ${decision.reason}` };
   });
 
   pi.on("agent_start", (_event, ctx) => {
@@ -138,7 +156,9 @@ export default function ompCoord(pi: ExtensionAPI): void {
         parentId,
         parentIsSubagent: parentId !== "Main",
         agentType: ctx.agent.name.toLowerCase(),
+        evalWorker: rt.evalAgents.has(ctx.agent.id),
       });
+      refreshQueue(rt);
       if (count && count.used > count.cap) {
         notify(
           rt,
@@ -152,9 +172,10 @@ export default function ompCoord(pi: ExtensionAPI): void {
   pi.on("agent_end", (_event, ctx) => {
     const rt = shared.runtime;
     if (!rt || !isTrackedSubagent(ctx)) return;
-    guarded(rt, "free an agent slot", () =>
-      rt.coordinator.agentEnded({ sessionId: rt.sessionId, agentId: ctx.agent.id }),
-    );
+    guarded(rt, "free an agent slot", () => {
+      rt.coordinator.agentEnded({ sessionId: rt.sessionId, agentId: ctx.agent.id });
+      refreshQueue(rt);
+    });
   });
 
   pi.on("tool_call", (event, ctx) => {
@@ -184,13 +205,15 @@ export default function ompCoord(pi: ExtensionAPI): void {
       notify(rt, `omp-coord could not check claims: ${describe(error)}`, "error");
     }
 
-    const decision = decideCommand(rt.config.commands, command, {
+    // a copied `export OMP_COORD_AGENT=…;` would otherwise end up inside a queued job's own command
+    const own = rt.config.tagAgentCommands ? withoutAgentExports(command) : command;
+    const decision = decideCommand(rt.config.commands, own, {
       ...RUNNER,
       owner: rt.sessionId,
       config: rt.config.source,
     });
     if (decision.kind === "refuse") return { block: true, reason: `omp-coord: ${decision.reason}` };
-    const run = decision.kind === "queue" ? decision.command : command;
+    const run = decision.kind === "queue" ? decision.command : own;
     // 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.
@@ -427,6 +450,8 @@ export default function ompCoord(pi: ExtensionAPI): void {
 }
 
 async function start(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  // a binding started again after an earlier shutdown starts fresh
+  shared.shutDown.delete(pi);
   const configPath = findConfigFile(ctx.cwd);
   if (!configPath) return;
   let config: Config;
@@ -438,6 +463,19 @@ async function start(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
     return;
   }
 
+  // whether spawns past the cap wait in omp's queue, and why not, for the session-start notice
+  let queue: SpawnQueue | undefined;
+  let queueNote = "Spawns past the cap are refused (agents.queueSpawns is off).";
+  if (config.agents.queueSpawns) {
+    const handle = await loadSettingHandle();
+    // this session ended (switched or reloaded) while the handle loaded: don't join the board for it
+    if (shared.shutDown.has(pi)) return;
+    const scope = pi.pi?.settings;
+    queue = typeof handle === "string" ? undefined : spawnQueue(handle, scope);
+    queueNote = queue
+      ? "While this is the only session, spawns past the cap wait in omp's queue and start as slots free; with others, they are refused and this session holds a place in line."
+      : `Spawns past the cap are refused: ${typeof handle === "string" ? handle : "omp gave the extension no settings scope"}.`;
+  }
   let joined: Pick<Runtime, "store" | "coordinator" | "listener" | "sessionId" | "label">;
   try {
     joined = openSession(config, ctx.cwd);
@@ -447,7 +485,19 @@ async function start(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
     return;
   }
 
-  const rt: Runtime = { config, ...joined, pi, ctx, timer: undefined, ticks: 0, footer: undefined, pruning: false };
+  const rt: Runtime = {
+    config,
+    ...joined,
+    pi,
+    ctx,
+    timer: undefined,
+    ticks: 0,
+    footer: undefined,
+    pruning: false,
+    queue,
+    queueNote,
+    evalAgents: new Set(),
+  };
   shared.runtime = rt;
   // Commands this session's agents run (e.g. a `just` recipe calling `omp-coord run`) see these.
   process.env.OMP_COORD_SESSION = rt.sessionId;
@@ -456,6 +506,7 @@ async function start(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
   const scratch = scratchFor(rt);
   if (scratch) process.env.OMP_COORD_SCRATCH = scratch;
   rt.timer = ctx.setInterval(() => tick(rt), TICK_MS);
+  refreshQueue(rt);
   await prune(rt);
 
   const board = rt.coordinator.board();
@@ -468,7 +519,8 @@ async function start(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
       (others.length
         ? `Other sessions: ${others.map(s => `${s.label} (${s.cwd})`).join(", ")}. Agent caps are shared with them.`
         : "No other session is active.") +
-      pausedNote,
+      pausedNote +
+      ` ${queueNote}`,
     "info",
   );
   if (differing.length) {
@@ -522,8 +574,18 @@ function scratchFor(rt: Runtime, agentId?: string): string | undefined {
   return dir;
 }
 
+/** Sets omp's spawn queue to what the caps allow this session now (a no-op when the queue isn't driven). */
+function refreshQueue(rt: Runtime): void {
+  if (!rt.queue) return;
+  const queue = rt.queue;
+  guarded(rt, "size omp's spawn queue", () =>
+    queue.apply(spawnAllowance(rt.coordinator.board(), rt.config.agents, rt.sessionId, Date.now())),
+  );
+}
+
 function stop(rt: Runtime): void {
   shared.runtime = undefined;
+  rt.queue?.release();
   for (const key of ["OMP_COORD_SESSION", "OMP_COORD_PORTS", "OMP_COORD_SCRATCH"]) delete process.env[key];
   rt.ctx.clearTimer(rt.timer);
   try {
@@ -540,6 +602,7 @@ async function tick(rt: Runtime): Promise<void> {
   const now = Date.now();
   const { label, inbox, holds, board } = rt.coordinator.tick(identity(rt.sessionId, rt.ctx.cwd, rt.listener));
   rt.label = label;
+  rt.queue?.apply(spawnAllowance(board, rt.config.agents, rt.sessionId, now));
 
   for (const m of inbox) {
     const body =
@@ -588,7 +651,14 @@ function sendFrom(rt: Runtime, to: string, body: string): ToolResult {
 }
 
 function statusText(rt: Runtime): string {
-  return formatStatus(rt.coordinator.board(), rt.config, rt.sessionId, Date.now());
+  const board = rt.coordinator.board();
+  // whether this session's spawns wait in omp's queue right now, and why not
+  const queueLine = !rt.queue
+    ? rt.queueNote
+    : spawnAllowance(board, rt.config.agents, rt.sessionId, Date.now()) !== undefined
+      ? "Spawns past the cap wait in omp's queue and start as slots free (this is the only session)."
+      : `Spawns over the cap are refused and put this session in line (${board.pause ? "the scope is paused" : board.sessions.length > 1 ? "other sessions are in the scope" : board.slots.some(x => x.sessionId === rt.sessionId && x.unqueued === "eval") ? "a workpool's workers are running" : "no slot is free for a new spawn"}).`;
+  return `${formatStatus(board, rt.config, rt.sessionId, Date.now())}\n${queueLine}`;
 }
 
 function deliver(binding: ExtensionAPI, content: string): void {

package/src/adapters/omp/omp-host.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The one module of omp's own that the extension imports at run time (see spawn-queue.ts). omp supplies it to
+ * extensions by rewriting the import as it loads them; it is not a package dependency, so its type is declared here.
+ */
+declare module "@oh-my-pi/pi-coding-agent/config/registry" {
+  import type { SettingHandle } from "./spawn-queue.ts";
+  export function lookup(id: string): SettingHandle | undefined;
+}

package/src/adapters/omp/spawn-queue.ts

@@ -0,0 +1,77 @@
+/**
+ * Keeps omp's own per-session spawn queue (the `task.maxConcurrency` setting) at the number of this session's spawns
+ * the caps let run now (`spawnAllowance`), so spawns past it wait in omp's queue and start as places free, instead of
+ * reaching the spawn check and being refused.
+ *
+ * Driven only while the session is alone in its scope and not paused (see `spawnAllowance`); otherwise the override is
+ * cleared and spawns over the cap are refused at the spawn check. omp re-reads the setting only when the session asks
+ * for a spawn or one of its runs ends, so a changed value takes effect then.
+ *
+ * The setting is changed by a runtime override (never persisted) and cleared when the session stops. A value the user
+ * set is a ceiling the override never exceeds; it is read when the session starts, so a change to it takes effect in
+ * the next session (while the override is in place it hides the setting's other layers). If omp's settings registry can't be loaded (an omp without it), nothing
+ * changes and spawns are refused as before.
+ */
+
+/** The slice of omp's typed setting handle used here (`@oh-my-pi/pi-coding-agent/config/registry`). */
+export interface SettingHandle {
+  get(scope: unknown): unknown;
+  override(scope: unknown, value: number | undefined): void;
+  clearOverride(scope: unknown): void;
+  isConfigured(scope: unknown): boolean;
+}
+
+export interface SpawnQueue {
+  /**
+   * Sets the queue's size to `allowance`, capped by the user's own value, writing only when it changes; `undefined`
+   * gives the queue back to the user's own value, leaving spawns to the spawn check.
+   */
+  apply(allowance: number | undefined): void;
+  /** Removes the override, giving the session back the user's own value. */
+  release(): void;
+}
+
+export const SETTING_ID = "task.maxConcurrency";
+
+/** A queue driver over `handle` in `scope`; `undefined` when either is missing. */
+export function spawnQueue(handle: SettingHandle | undefined, scope: unknown): SpawnQueue | undefined {
+  if (!handle || scope === undefined) return undefined;
+  // the user's own value, read before the first override: a positive number is a ceiling; 0 (unlimited) or unset is none
+  const own = handle.isConfigured(scope) ? Number(handle.get(scope)) : 0;
+  const ceiling = Number.isFinite(own) && own > 0 ? Math.trunc(own) : Number.POSITIVE_INFINITY;
+  let last: number | undefined;
+  return {
+    apply(allowance) {
+      if (allowance === undefined) {
+        this.release();
+        return;
+      }
+      // never 0: omp reads 0 as unlimited
+      const value = Math.max(1, Math.min(Math.trunc(allowance), ceiling));
+      if (value === last) return;
+      handle.override(scope, value);
+      last = value;
+    },
+    release() {
+      if (last === undefined) return;
+      handle.clearOverride(scope);
+      last = undefined;
+    },
+  };
+}
+
+/** omp's handle for the setting, or why there is none (this omp has no settings registry to load it from). */
+export async function loadSettingHandle(): Promise<SettingHandle | string> {
+  try {
+    // Dynamic on purpose: the host's registry exists only inside an omp that has it. A static import would fail the
+    // whole extension's load in an older omp, in the CLI and in tests, where this module is loaded without omp. The
+    // specifier stays a literal: omp maps host packages onto its bundled copies by rewriting the specifiers in an
+    // extension's source as it loads it, and a specifier held in a variable is missed (seen live: "Cannot find package").
+    const registry: { lookup?: (id: string) => SettingHandle | undefined } = await import(
+      "@oh-my-pi/pi-coding-agent/config/registry"
+    );
+    return registry.lookup?.(SETTING_ID) ?? `omp's settings registry has no ${SETTING_ID}`;
+  } catch (error) {
+    return `omp's settings registry can't be loaded (${error instanceof Error ? error.message : String(error)})`;
+  }
+}

package/src/adapters/sqlite/store.ts

@@ -47,7 +47,8 @@ CREATE TABLE slots (
   agent_type TEXT NOT NULL,
   pool       TEXT,
   state      TEXT NOT NULL CHECK (state IN ('starting', 'running')),
-  since      INTEGER NOT NULL
+  since      INTEGER NOT NULL,
+  unqueued   TEXT CHECK (unqueued IN ('revived', 'eval'))
 ) STRICT;
 CREATE TABLE tickets (
   session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
@@ -255,6 +256,8 @@ export class BoardStore implements BoardRepository {
         .all()
         .some(c => c.name === column);
     if (!has("jobs", "agent")) this.#db.exec("ALTER TABLE jobs ADD COLUMN agent TEXT");
+    if (!has("slots", "unqueued"))
+      this.#db.exec("ALTER TABLE slots ADD COLUMN unqueued TEXT CHECK (unqueued IN ('revived', 'eval'))");
   }
 
   #maybePruneEvents(now: number): void {
@@ -304,6 +307,7 @@ export class BoardStore implements BoardRepository {
             pool: string | null;
             state: "starting" | "running";
             since: number;
+            unqueued: "revived" | "eval" | null;
           },
           []
         >("SELECT * FROM slots ORDER BY id")
@@ -316,6 +320,7 @@ export class BoardStore implements BoardRepository {
           pool: r.pool,
           state: r.state,
           since: r.since,
+          ...(r.unqueued ? { unqueued: r.unqueued } : {}),
         })),
       waitlist: db
         .query<{ session_id: string; pool: string; since: number; hold_until: number | null; notified: number }, []>(
@@ -462,10 +467,10 @@ export class BoardStore implements BoardRepository {
         s.ports?.to ?? null,
       );
     const slot = db.query(
-      "INSERT INTO slots (session_id, agent_id, parent_id, agent_type, pool, state, since) VALUES (?, ?, ?, ?, ?, ?, ?)",
+      "INSERT INTO slots (session_id, agent_id, parent_id, agent_type, pool, state, since, unqueued) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
     );
     for (const s of board.slots)
-      slot.run(s.sessionId, s.agentId ?? null, s.parentId, s.agentType, s.pool, s.state, s.since);
+      slot.run(s.sessionId, s.agentId ?? null, s.parentId, s.agentType, s.pool, s.state, s.since, s.unqueued ?? null);
     const ticket = db.query(
       "INSERT INTO tickets (session_id, pool, since, hold_until, notified) VALUES (?, ?, ?, ?, ?)",
     );

package/src/app/coordinator.ts

@@ -158,6 +158,7 @@ export class Coordinator {
     parentId: string;
     parentIsSubagent: boolean;
     agentType: string;
+    evalWorker?: boolean;
   }) {
     return this.repo.transact(b => agentStarted(b, this.config.agents, { ...a, now: this.clock.now() }));
   }

package/src/config.ts

@@ -187,6 +187,7 @@ export function parseConfig(raw: unknown, source: string, hash = "none"): Config
       },
       holdMs: count(agents.holdMinutes ?? 5, "agents.holdMinutes", fail) * 60_000,
       startTimeoutMs: count(agents.startTimeoutSeconds ?? 120, "agents.startTimeoutSeconds", fail) * 1000,
+      queueSpawns: flag(agents.queueSpawns ?? true, "agents.queueSpawns", fail),
       messagesPerMinute: count(messages.perMinute ?? 10, "messages.perMinute", fail),
     },
     commands,

package/src/domain/agents.ts

@@ -35,6 +35,8 @@ export interface SpawnRequest {
   agentType: string;
   /** omp's spawn key: the new agent's id for `task`, eval `agent()` and workpools; only a label for some callers. */
   spawnKey?: string;
+  /** How omp starts it; "eval" (eval `agent()` and workpool workers) takes no place in omp's spawn queue. */
+  invocationKind?: string;
   now: number;
 }
 
@@ -123,6 +125,7 @@ function addStartingSlot(board: Board, req: SpawnRequest, pool: string | null):
     pool,
     state: "starting",
     since: req.now,
+    ...(req.invocationKind === "eval" ? { unqueued: "eval" as const } : {}),
   });
   emit(board, req.now, "spawn_approved", req.sessionId, {
     agentType: req.agentType,
@@ -146,6 +149,11 @@ export function agentStarted(
     parentId: string;
     parentIsSubagent: boolean;
     agentType: string;
+    /**
+     * A workpool worker's later run (its first run was an eval spawn): omp runs it outside the spawn check and the
+     * spawn queue, so its new slot is marked "eval", not "revived".
+     */
+    evalWorker?: boolean;
     now: number;
   },
 ): { pool: string; used: number; cap: number } | null {
@@ -185,6 +193,7 @@ export function agentStarted(
       pool: a.parentIsSubagent ? null : poolFor(policy, a.agentType),
       state: "running",
       since: a.now,
+      unqueued: a.evalWorker ? "eval" : "revived",
     };
     board.slots.push(slot);
   }
@@ -264,3 +273,33 @@ function listOr(items: string[]): string {
   if (items.length === 1) return items[0] as string;
   return `${items.slice(0, -1).join(", ")} or ${items.at(-1)}`;
 }
+
+/**
+ * How many of this session's own (main-agent) spawns may run at once right now, for omp's per-session spawn queue
+ * (`task.maxConcurrency`), or `undefined` when the queue must not be driven and spawns are left to the spawn check.
+ *
+ * Driven only while this session is alone in the scope, not paused, and runs no eval workpool workers. omp re-reads its queue size only when this
+ * session asks for a spawn or one of its runs ends, and a spawn parked in that queue never reaches the spawn check, so
+ * it never joins the line: with other sessions, a slot one of them frees could not be held for this session fairly.
+ * There the refusal and the line decide, as they always did.
+ *
+ * Alone, the allowance is this session's top-level agents that hold a place in omp's queue (running or starting, not
+ * `unqueued` ones: revived agents and workpool workers), plus the default pool's free slots and one held for it there. Other pools'
+ * free slots are left out: omp's queue doesn't know a waiting spawn's pool, so counting them would let a default-pool
+ * spawn through to a refusal. `undefined` too when that comes to 0 (every slot taken by agents outside omp's queue):
+ * omp reads 0 as unlimited, and a floor of 1 would let each waiting spawn through to a refusal in turn.
+ */
+export function spawnAllowance(board: Board, policy: AgentPolicy, sessionId: string, now: number): number | undefined {
+  if (board.pause || board.sessions.some(s => s.id !== sessionId)) return undefined;
+  // an eval workpool sizes itself from the same setting while its own workers take slots: one number can't size
+  // both queues, so while workers run the spawn check decides
+  if (board.slots.some(s => s.sessionId === sessionId && s.unqueued === "eval")) return undefined;
+  const pool = policy.defaultPool;
+  const queued = board.slots.filter(s => s.sessionId === sessionId && s.parentId === "Main" && !s.unqueued).length;
+  const held = board.waitlist.filter(
+    t => t.sessionId === sessionId && t.pool === pool && t.holdUntil !== undefined,
+  ).length;
+  const free = Math.max(0, capOf(board, policy, pool, now) - used(board, pool) - activeHolds(board, pool));
+  const allowance = queued + held + free;
+  return allowance > 0 ? allowance : undefined;
+}

package/src/domain/commands.ts

@@ -61,5 +61,20 @@ function quote(word: string): string {
  * 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}`;
+  return `export OMP_COORD_AGENT=${quote(agentId)}; ${withoutAgentExports(command)}`;
 }
+
+/** The command without the `export OMP_COORD_AGENT=…;` prefixes it starts with, if any. */
+export function withoutAgentExports(command: string): string {
+  return command.replace(LEADING_AGENT_EXPORTS, "");
+}
+
+/**
+ * The `export OMP_COORD_AGENT=…;` prefixes already at the start of a command. The rewritten command is what the
+ * conversation shows, so an agent that copies its earlier calls sends them back; without stripping, each call would
+ * add one more. A value is single-quoted as `quote` writes it (`'\''` for a quote inside) or a bare word of
+ * shell-safe characters only, so a hand-typed value holding `\;`, `|`, `>` or a substitution is never mistaken for
+ * a prefix and nothing of the command itself is dropped. Only spaces and tabs may surround the assignment: in bash a
+ * newline ends a command, so an `export` alone on its line is a command of its own, not part of a prefix.
+ */
+const LEADING_AGENT_EXPORTS = /^(?:\s*export[ \t]+OMP_COORD_AGENT=(?:'(?:[^']|'\\'')*'|[\w.@%+,:/=-]+)[ \t]*;)+\s*/;

package/src/domain/model.ts

@@ -22,6 +22,8 @@ export interface AgentPolicy {
   holdMs: number;
   /** How long an approved spawn may take to start its first run before its slot is given back. */
   startTimeoutMs: number;
+  /** Keep omp's per-session spawn queue (`task.maxConcurrency`) at what the caps allow, so spawns wait instead of being refused. */
+  queueSpawns: boolean;
   /** Messages one session may send per minute. */
   messagesPerMinute: number;
 }
@@ -94,6 +96,12 @@ export interface AgentSlot {
   /** `starting`: approved, first run not seen yet. `running`: in a run. */
   state: "starting" | "running";
   since: number;
+  /**
+   * Holds no place in omp's spawn queue, so `spawnAllowance` doesn't count it: started without a spawn this extension
+   * approved (revived with `write agent://…`, or running when this session joined), or a workpool worker (omp starts
+   * those outside the queue, as spawns of `invocationKind` "eval").
+   */
+  unqueued?: "revived" | "eval";
 }
 
 /** A session's place in line for a pool, after a refused spawn. */