@prohost/cli 0.8.3 → 0.10.0

package/dist/agent/command.js

@@ -16,6 +16,8 @@ import { acquireRunLock } from './lock.js';
 import { PairError, runPair } from './pair.js';
 import { CredentialsMissingError, ensureWorkspace, loadCredentials, prohostHome, tryLoadCredentials, } from './credentials.js';
 import { DEFAULT_EXEC_TIMEOUT_MS, DEFAULT_IDLE_TIMEOUT_MS, runAgentHarness } from './run.js';
+import { MAX_CONCURRENCY } from './scheduler.js';
+import { ReposFlagError, isCheckout, parseReposFlag } from './worktrees.js';
 import { announceUpgradeIfAvailable } from '../upgrade.js';
 function flagString(flags, name) {
     const value = flags[name];
@@ -119,6 +121,55 @@ function parseIdleTimeoutSeconds(flags) {
     }
     return parsed;
 }
+/** Returned by {@link parseConcurrency} for a value that isn't a run count. */
+export const INVALID_CONCURRENCY = Symbol('invalid-concurrency');
+/**
+ * Read `--concurrency`. Pure, like {@link parseSeconds}, and strict for the
+ * same reason: `--concurrency` with nothing after it arrives as `true`, and
+ * treating that as absent would leave someone believing their agent runs four
+ * things at once while it runs one.
+ */
+export function parseConcurrency(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'string' || !/^\d+$/.test(raw.trim()))
+        return INVALID_CONCURRENCY;
+    const count = Number(raw);
+    return count >= 1 && count <= MAX_CONCURRENCY ? count : INVALID_CONCURRENCY;
+}
+/**
+ * What `--concurrency` and `--repos` asked for, or `null` after explaining why not.
+ *
+ * `installing` decides how a `--repos` path that is not a git checkout is
+ * treated — see {@link parseReposFlag}. `agent run` only warns about it.
+ */
+function parseParallelFlags(flags, installing) {
+    const concurrency = parseConcurrency(flags.concurrency);
+    if (concurrency === INVALID_CONCURRENCY) {
+        process.stderr.write(`--concurrency must be a whole number from 1 to ${MAX_CONCURRENCY}.\n`);
+        return null;
+    }
+    if (flags.repos === undefined)
+        return { concurrency };
+    const raw = flagString(flags, 'repos');
+    if (!raw) {
+        process.stderr.write('--repos needs a comma-separated list of git checkouts, e.g. --repos ~/code/app\n');
+        return null;
+    }
+    try {
+        const repos = parseReposFlag(raw, { requireCheckouts: installing });
+        for (const repo of repos.filter((entry) => !isCheckout(entry))) {
+            process.stderr.write(`! --repos: ${repo} is not a git checkout right now. Runs will be told it is read-only until it is.\n`);
+        }
+        return { concurrency, repos };
+    }
+    catch (err) {
+        if (!(err instanceof ReposFlagError))
+            throw err;
+        process.stderr.write(`✗ ${err.message}\n`);
+        return null;
+    }
+}
 /**
  * Environment the daemon must be given explicitly.
  *
@@ -210,6 +261,10 @@ async function installDaemonCommand(flags) {
     const idleTimeoutSeconds = parseIdleTimeoutSeconds(flags);
     if (idleTimeoutSeconds === INVALID_DURATION)
         return 1;
+    // Same reasoning: a bad value here would crash-loop the daemon, not print.
+    const parallel = parseParallelFlags(flags, true);
+    if (!parallel)
+        return 1;
     // Absolute, and created now. A supervisor does not inherit the installing
     // shell's current directory, so a relative `--workdir .` copied verbatim into
     // the plist names a directory that either doesn't exist or isn't the one the
@@ -235,6 +290,8 @@ async function installDaemonCommand(flags) {
         url: flagString(flags, 'url'),
         allowUnverified: flags['allow-unverified'] === true,
         safeTools: flags['safe-tools'] === true || flags['no-skip-permissions'] === true,
+        concurrency: parallel.concurrency,
+        repos: parallel.repos,
     };
     const spec = {
         label: launchdLabel(prohostHome()),
@@ -332,6 +389,9 @@ async function runCommand(flags) {
     const parsedIdleTimeout = parseIdleTimeoutSeconds(flags);
     if (parsedIdleTimeout === INVALID_DURATION)
         return 1;
+    const parallel = parseParallelFlags(flags, false);
+    if (!parallel)
+        return 1;
     // One harness per home: two would both execute every run.
     const lock = acquireRunLock();
     if (!lock.ok) {
@@ -340,8 +400,8 @@ async function runCommand(flags) {
             '`prohost agent uninstall-daemon` — or give this agent its own $PROHOST_HOME.\n');
         return 1;
     }
-    // First signal stops accepting work and lets the in-flight run finish
-    // reporting itself (so the server doesn't wait on a run we abandoned); a
+    // First signal stops accepting work and lets the in-flight runs finish
+    // reporting themselves (so the server doesn't wait on a run we abandoned); a
     // second one means the operator wants out now.
     const controller = new AbortController();
     const onSig = () => {
@@ -364,6 +424,8 @@ async function runCommand(flags) {
             url: flagString(flags, 'url') ?? process.env.PROHOST_WS_URL,
             machine: flagString(flags, 'machine'),
             cwd: requestedWorkdir(flags),
+            concurrency: parallel.concurrency,
+            repos: parallel.repos,
             timeoutMs: parsedTimeout === undefined ? DEFAULT_EXEC_TIMEOUT_MS : parsedTimeout * 1000,
             idleTimeoutMs: parsedIdleTimeout === undefined ? DEFAULT_IDLE_TIMEOUT_MS : parsedIdleTimeout * 1000,
             dryRun: flags['dry-run'] === true,

package/dist/agent/daemon.d.ts

@@ -90,6 +90,10 @@ export interface HarnessInvocation {
     allowUnverified?: boolean;
     /** Gate tools behind permission prompts (the `--safe-tools` opt-out). */
     safeTools?: boolean;
+    /** Runs allowed at once; omitted for the default of one. */
+    concurrency?: number;
+    /** Absolute checkouts each conversation gets its own worktree of. */
+    repos?: string[];
 }
 export declare function harnessArguments(invocation: HarnessInvocation): string[];
 /** Default log destination — alongside the credential and the run ledger. */

package/dist/agent/daemon.js

@@ -192,6 +192,10 @@ export function harnessArguments(invocation) {
         args.push('--allow-unverified');
     if (invocation.safeTools)
         args.push('--safe-tools');
+    if (invocation.concurrency !== undefined)
+        args.push('--concurrency', String(invocation.concurrency));
+    if (invocation.repos && invocation.repos.length > 0)
+        args.push('--repos', invocation.repos.join(','));
     return args;
 }
 /** Default log destination — alongside the credential and the run ledger. */

package/dist/agent/prompt.d.ts

@@ -72,6 +72,33 @@ export interface PromptContext {
      * hour" is advice about how to work, not a request to hurry.
      */
     idleTimeoutMs?: number;
+    /**
+     * Other runs may be executing on this machine at the same moment
+     * (`--concurrency` above 1).
+     *
+     * Said because it changes what is safe: an agent that believes it has the
+     * machine to itself switches branches in a shared checkout and writes
+     * `scratch.json` into the working directory, and the run beside it does the
+     * same. Unset, the prompt is byte-for-byte what it was.
+     */
+    parallel?: boolean;
+    /**
+     * Git checkouts private to this run's conversation (`--repos`).
+     *
+     * Named with the checkout they were made from, because the agent's own
+     * standing instructions usually name *that* path — and the point of this
+     * block is to move it off it.
+     */
+    checkouts?: Array<{
+        name: string;
+        path: string;
+        source: string;
+    }>;
+    /** `--repos` entries no private checkout could be made of, and why. */
+    checkoutFailures?: Array<{
+        source: string;
+        reason: string;
+    }>;
 }
 /** Build the stdin prompt for one run. */
 export declare function buildPrompt(run: AgentRunRequest, context: PromptContext): string;

package/dist/agent/prompt.js

@@ -7,6 +7,26 @@
  * agent that would otherwise narrate its reasoning returns something sendable.
  */
 import { NO_REPLY_TOKEN } from './contract.js';
+/**
+ * What the agent is told about sharing the machine and where its checkouts are.
+ *
+ * Empty when neither `--concurrency` nor `--repos` is in play.
+ */
+function isolationLines(context) {
+    const lines = [];
+    const checkouts = context.checkouts ?? [];
+    const failures = context.checkoutFailures ?? [];
+    if (context.parallel) {
+        lines.push('- Other conversations may be running on this machine right now, as other', '  processes of you, in this same working directory. Give any scratch file', '  a name unique to this run, and do not assume a file or a git branch', '  you did not create in this conversation is yours to change.');
+    }
+    if (checkouts.length > 0) {
+        lines.push('- This conversation has its own git checkouts. Do all repository work', '  in them, and nowhere else:', ...checkouts.map((checkout) => `    ${checkout.name}: ${checkout.path}`), '  They are worktrees private to this conversation and they persist', '  between your runs here, so a branch or an uncommitted change you find', '  in one is your own earlier work in this thread. Wherever your other', '  instructions name one of these as the place to work, use the path', '  above instead:', ...checkouts.map((checkout) => `    ${checkout.source}`), '  Never switch branches, commit, or edit files in those originals —', '  other runs read them. Do not run `git worktree add` yourself.');
+    }
+    if (failures.length > 0) {
+        lines.push('- A private checkout could not be prepared for:', ...failures.map((failure) => `    ${failure.source} (${failure.reason})`), '  Treat that repository as read-only for this run: do not switch', '  branches, commit, or edit files in it, and say so if the request', '  needed a change there.');
+    }
+    return lines;
+}
 /**
  * Say the run's budget in a unit a reader thinks in.
  *
@@ -259,7 +279,7 @@ export function buildPrompt(run, context) {
     // not buried under the tool advice: how long the agent has changes how it
     // should approach the work, so it has to be read before any of the "go and
     // look" bullets below.
-    ...timeBudgetLines(context.timeoutMs, context.idleTimeoutMs), 
+    ...timeBudgetLines(context.timeoutMs, context.idleTimeoutMs), ...isolationLines(context), 
     // Claude Code lazy-loads part of its catalog — WebSearch/WebFetch among
     // them — so a run that inspects its loaded tools concludes it cannot
     // browse and says so to a customer, when one ToolSearch call away it

package/dist/agent/run.d.ts

@@ -10,9 +10,12 @@
  *
  * Two deliberate safety properties:
  *
- * * **Runs are serialized.** One local agent, one run at a time; concurrent
- *   frames queue. Agents hold working directories and rate limits, and running
- *   several at once is a good way to corrupt both.
+ * * **Runs are serialized by default.** One local agent, one run at a time;
+ *   concurrent frames queue. Agents hold working directories and rate limits,
+ *   and running several at once is a good way to corrupt both. `--concurrency`
+ *   raises the limit for runs in *different* conversations only — two turns of
+ *   one conversation never overlap (see `scheduler.ts`) — and `--repos` gives
+ *   each conversation its own git checkouts to do it in (see `worktrees.ts`).
  * * **Runs are deduped on ``run_id``.** Webhook deliveries retry, and each
  *   attempt is mirrored to this socket. Without dedupe a retry would execute
  *   the command a second time and post a second reply.
@@ -59,6 +62,15 @@ export declare const DEFAULT_EXEC_TIMEOUT_MS = 0;
  * tokens and their agent's availability indefinitely.
  */
 export declare const DEFAULT_IDLE_TIMEOUT_MS = 900000;
+/**
+ * Set to `1` in the environment of every agent command this harness starts.
+ *
+ * Lets instructions the agent reads from disk tell a paired run — someone is
+ * waiting in a thread, and the run holds one of this agent's few slots — from
+ * the same file being read anywhere else. ProhostAI's own pull-request protocol
+ * uses it to stop a run from sitting on CI after the PR is open.
+ */
+export declare const PAIRED_RUN_ENV_VAR = "PROHOST_PAIRED_RUN";
 export interface AgentRunOptions {
     /** Shell command that runs the agent, e.g. ``claude -p``. */
     exec: string;
@@ -95,6 +107,17 @@ export interface AgentRunOptions {
      * ``$PROHOST_HOME/workspace`` — see {@link workspacePath} for why not "here".
      */
     cwd?: string;
+    /**
+     * How many runs may execute at once. Defaults to 1 — one run at a time, as
+     * before. Above 1, runs in different conversations overlap; runs in the same
+     * conversation still wait for each other.
+     */
+    concurrency?: number;
+    /**
+     * Git checkouts the agent works on (absolute paths). When set, every
+     * conversation gets a private worktree of each — see `worktrees.ts`.
+     */
+    repos?: string[];
     onLine?: (line: string) => void;
     webSocketCtor?: typeof WebSocket;
     fetchImpl?: typeof fetch;
@@ -186,6 +209,8 @@ interface PreparedMcp {
     mcpWired: boolean;
     /** A fail-closed preparation error. When set, the agent is never spawned. */
     error?: string;
+    /** The account this run was resolved onto; hand it back when the run ends. */
+    accountLabel?: string;
 }
 /**
  * Prepare a fresh Codex MCP override immediately before each invocation.

package/dist/agent/run.js

@@ -10,9 +10,12 @@
  *
  * Two deliberate safety properties:
  *
- * * **Runs are serialized.** One local agent, one run at a time; concurrent
- *   frames queue. Agents hold working directories and rate limits, and running
- *   several at once is a good way to corrupt both.
+ * * **Runs are serialized by default.** One local agent, one run at a time;
+ *   concurrent frames queue. Agents hold working directories and rate limits,
+ *   and running several at once is a good way to corrupt both. `--concurrency`
+ *   raises the limit for runs in *different* conversations only — two turns of
+ *   one conversation never overlap (see `scheduler.ts`) — and `--repos` gives
+ *   each conversation its own git checkouts to do it in (see `worktrees.ts`).
  * * **Runs are deduped on ``run_id``.** Webhook deliveries retry, and each
  *   attempt is mirrored to this socket. Without dedupe a retry would execute
  *   the command a second time and post a second reply.
@@ -40,9 +43,11 @@ import { HeartbeatLoop } from './heartbeat.js';
 import { buildPrompt, replyFromStdout } from './prompt.js';
 import { NO_CAPABILITIES, capabilityProbe } from './capabilities.js';
 import { RunStore } from './runstore.js';
+import { MAX_CONCURRENCY, RunScheduler } from './scheduler.js';
 import { RUNTIME_STATUS_FEATURE, RuntimeStatusReporter, claudeQuotaProvider, codexConfiguredModel, codexQuotaProvider, modelFromExec, parseVersion, readCodexObservation, } from './runtime_status.js';
 import { SessionStore, sessionKeyFor } from './sessionstore.js';
 import { verifySignature } from './signature.js';
+import { RUN_REPOS_ENV_VAR, WorktreeManager } from './worktrees.js';
 import { isWebhookEvent } from '../forward.js';
 import { DEFAULT_WS_URL } from '../listen.js';
 import { ServerLiveness, enableTcpKeepAlive, seconds, terminateSocket } from '../liveness.js';
@@ -89,6 +94,15 @@ const RECONNECT_MAX_DELAY_MS = 30_000;
  * would hang with neither `open` nor `close` to move the loop along.
  */
 const HANDSHAKE_TIMEOUT_MS = 30_000;
+/**
+ * Set to `1` in the environment of every agent command this harness starts.
+ *
+ * Lets instructions the agent reads from disk tell a paired run — someone is
+ * waiting in a thread, and the run holds one of this agent's few slots — from
+ * the same file being read anywhere else. ProhostAI's own pull-request protocol
+ * uses it to stop a run from sitting on CI after the PR is open.
+ */
+export const PAIRED_RUN_ENV_VAR = 'PROHOST_PAIRED_RUN';
 /** Ack status codes reported back over the socket for each frame. */
 const ACK_ACCEPTED = 200;
 const ACK_IGNORED = 204;
@@ -228,6 +242,16 @@ function resolveWorkdir(options, log) {
         return undefined;
     }
 }
+/**
+ * The lane a run waits on: runs sharing one never overlap.
+ *
+ * The session key, because a session is exactly what two overlapping turns of
+ * one conversation would corrupt. A run with no surface resumes nothing and
+ * shares nothing, so it gets a lane of its own.
+ */
+function laneFor(run) {
+    return sessionKeyFor(run) ?? `run:${run.run_id}`;
+}
 /**
  * Assemble the per-process runtime: workspace, session ledger, and the
  * brain-specific MCP preparation used immediately before each run.
@@ -330,7 +354,11 @@ function buildRuntime(options, log) {
         if (!resolved.ok)
             return { mcpWired: false, error: resolved.error };
         const prepared = prepareMcp();
-        return { ...prepared, execEnv: { ...account.spawnEnv(), ...prepared.execEnv } };
+        return {
+            ...prepared,
+            execEnv: { ...account.spawnEnv(), ...prepared.execEnv },
+            accountLabel: resolved.record.label,
+        };
     };
     log(`${timestamp()} ⚙ account: ${account.label()}`);
     return {
@@ -579,7 +607,9 @@ async function runTurn(run, prompt, options, runtime, mcp, control, log,
  * Where the streaming brain's tool-call events go, if anywhere. Only the
  * Claude Code reader produces any; absent, they are simply never collected.
  */
-toolEvents) {
+toolEvents, 
+/** Harness-set variables for this run's command, over the brain's own. */
+runEnv) {
     // `--timeout` is a ceiling on the run, not on each attempt: the retry below
     // must not let one run take twice what the operator allowed. Both attempts
     // share one deadline, which costs the retry nothing in practice — a rejected
@@ -667,7 +697,7 @@ toolEvents) {
             timeoutMs: capped ? Math.max(1, remainingMs()) : 0,
             idleTimeoutMs: idleMs,
             cwd: runtime.workdir,
-            env: mcp.execEnv,
+            env: { ...mcp.execEnv, ...runEnv },
             spawnImpl: options.spawnImpl,
             cancelSignal: control.signal,
             onStdout: reader
@@ -842,11 +872,18 @@ toolEvents) {
  * Every path except a dry run — including every failure — calls the completion
  * endpoint before returning.
  */
-async function handleRun(run, options, runtime, api, log, sleep, control) {
+async function handleRun(run, options, runtime, api, log, sleep, control, isolation, 
+/** Prepared by the caller, which also hands the run's account back. */
+mcp) {
     const label = `run ${run.run_id.slice(0, 12)}`;
     const surface = run.conversation_id ?? run.kind ?? 'no conversation';
     log(`${timestamp()} ▶ ${label} started (${surface})`);
-    const mcp = runtime.prepareMcp();
+    // Before anything is spawned: the prompt names these paths. A dry run makes
+    // no writes, and a worktree is one.
+    const checkouts = isolation.worktrees.enabled && !options.dryRun ? await isolation.worktrees.prepare(isolation.lane) : undefined;
+    for (const failure of checkouts?.failures ?? []) {
+        log(`    ! no private checkout of ${failure.source} for ${label} (${failure.reason})`);
+    }
     // Only worth asking when the tools it describes are wired into this run.
     const capabilities = mcp.mcpWired ? await runtime.capabilities() : NO_CAPABILITIES;
     const prompt = buildPrompt(run, {
@@ -865,6 +902,9 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         // The real numbers, not a vague "there is a limit" — see PromptContext.
         timeoutMs: options.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS,
         idleTimeoutMs: options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS,
+        parallel: isolation.parallel,
+        checkouts: checkouts?.checkouts,
+        checkoutFailures: checkouts?.failures,
     });
     // Tool-call narration for the thread. A dry run makes no writes, so it gets
     // no path and every event is dropped; so does a server that advertised none.
@@ -874,7 +914,10 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         log,
         label,
     });
-    const result = await runTurn(run, prompt, options, runtime, mcp, control, log, toolEvents);
+    const runEnv = { [PAIRED_RUN_ENV_VAR]: '1' };
+    if (checkouts && checkouts.checkouts.length > 0)
+        runEnv[RUN_REPOS_ENV_VAR] = checkouts.dir;
+    const result = await runTurn(run, prompt, options, runtime, mcp, control, log, toolEvents, runEnv);
     // Whatever the turn did, the timeline is whole BEFORE the reply is posted or
     // the run is closed — a completion that beats its own last tool row would
     // leave a `calling` row on a finished run. Never rejects, and after `stop`
@@ -1109,7 +1152,19 @@ export async function runAgentHarness(options) {
         }
         return true;
     };
-    let queue = Promise.resolve();
+    const concurrency = Math.min(MAX_CONCURRENCY, Math.max(1, Math.floor(options.concurrency ?? 1)));
+    const scheduler = new RunScheduler(concurrency);
+    const worktrees = new WorktreeManager({ repos: options.repos ?? [], env: options.env, log });
+    if (concurrency > 1) {
+        log(`${timestamp()} ⚙ up to ${concurrency} runs at once — runs in the same conversation still take turns` +
+            (worktrees.enabled
+                ? ''
+                : '. No --repos given: runs share every checkout on this machine, so name the ' +
+                    'repositories the agent edits to give each conversation its own'));
+    }
+    if (worktrees.enabled) {
+        log(`${timestamp()} ⚙ each conversation gets its own checkout of: ${(options.repos ?? []).join(', ')}`);
+    }
     let fatal;
     let attempt = 0;
     /** Stop tracking a run — it has reached a terminal state, one way or another. */
@@ -1195,7 +1250,7 @@ export async function runAgentHarness(options) {
     // Let an in-flight run finish reporting before we hand back metrics — and
     // any cancellation the heartbeat loop started and deliberately did not wait
     // for, so the harness never exits with a run half-closed.
-    await queue;
+    await scheduler.onIdle();
     status.detach();
     // Stopped first, so no further tick can start work after the wait below has
     // taken its snapshot of `background`.
@@ -1404,7 +1459,7 @@ export async function runAgentHarness(options) {
                     // completion. Retry only the completion: re-running the agent could
                     // repeat whatever it did with its credential the first time.
                     metrics.duplicates += 1;
-                    queue = queue.then(async () => {
+                    scheduler.submit(laneFor(run), async () => {
                         log(`${timestamp()} ↻ run ${run.run_id.slice(0, 12)} was started before but never reported; ` +
                             'reporting it now without re-running the agent');
                         const recovered = await completeWithRetry(api, previous.completion_path || run.completion_path, { ok: false, error: 'the harness restarted before this run was reported' }, log, sleep);
@@ -1434,9 +1489,11 @@ export async function runAgentHarness(options) {
                     },
                     onResolved: () => resolveAccepted(entry),
                 });
-                // Serialize execution but never block the socket reader: the ack and
-                // the heartbeat have to keep flowing while the agent thinks.
-                queue = queue.then(async () => {
+                // Queue execution but never block the socket reader: the ack and the
+                // heartbeat have to keep flowing while the agent thinks. The lane is
+                // what keeps two turns of one conversation from overlapping.
+                const lane = laneFor(run);
+                scheduler.submit(lane, async () => {
                     // Settled while it waited — cancelled, or closed server-side. Both
                     // were dealt with where they were decided; there is nothing to run
                     // and nothing left to report.
@@ -1465,17 +1522,32 @@ export async function runAgentHarness(options) {
                             entry.progress = activity;
                         },
                     };
-                    const outcome = await handleRun(run, options, runtime, api, log, sleep, control).catch((err) => {
+                    const isolation = { lane, parallel: concurrency > 1, worktrees };
+                    // Resolved here rather than inside `handleRun` so the account this
+                    // run is on can be handed back however the run ends.
+                    let mcp;
+                    try {
+                        mcp = runtime.prepareMcp();
+                    }
+                    catch (err) {
+                        // Fails the run closed, and — unlike a throw from here — still
+                        // reports it, so the server is not left waiting on it.
+                        mcp = { mcpWired: false, error: `could not prepare the run (${String(err)})` };
+                    }
+                    const outcome = await handleRun(run, options, runtime, api, log, sleep, control, isolation, mcp).catch((err) => {
                         log(`${timestamp()} ✗ run ${run.run_id} crashed the harness handler: ${String(err)}`);
                         return 'failed';
                     });
+                    if (mcp.accountLabel !== undefined)
+                        runtime.account?.finishSpawn(mcp.accountLabel);
                     // Held until here on purpose: heartbeats keep the row alive for the
                     // whole of `handleRun`, including the ten minutes of completion
                     // retries at the end of it.
                     release(run.run_id);
                     // An account picked mid-run was held back from the status frame
-                    // until this run (on the old account) was done; report it now.
-                    if (runtime.account?.changedSinceSpawn())
+                    // until this run (on the old account) was done; report it now. Asked
+                    // about *this* run's account: a newer run may already be on the pick.
+                    if (runtime.account?.changedSinceSpawn(mcp.accountLabel))
                         status.accountsChanged();
                     // Both terminal outcomes reached the completion endpoint; only then
                     // is the run settled and safe to skip on redelivery.

package/dist/agent/scheduler.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Which accepted runs execute now, and which wait.
+ *
+ * `agent run` used to chain every run onto one promise: one local agent, one
+ * run at a time. That is still the default, and with a limit of 1 this
+ * scheduler is exactly that chain — strict arrival order, nothing overlapping.
+ *
+ * `--concurrency N` lifts the limit without lifting the rule that actually
+ * protects an answer: **two runs on the same lane never overlap, and they start
+ * in the order they arrived.** A lane is a conversation (see `sessionKeyFor`).
+ * Each turn resumes the session the previous turn left, so running two turns of
+ * one thread side by side would have both resume the same session and the
+ * second answer without having seen the first. Runs on different lanes share
+ * nothing but the machine, and those are the ones allowed to overlap.
+ *
+ * Among the runs free to start, the oldest goes first. A lane that is busy does
+ * not hold up the lanes behind it — which is the whole point: a quick question
+ * in one thread no longer waits out a two-hour job in another.
+ */
+/** Most runs one harness will execute at once, whatever the flag says. */
+export declare const MAX_CONCURRENCY = 16;
+export declare class RunScheduler {
+    private readonly limit;
+    private readonly pending;
+    private readonly busy;
+    private waiters;
+    constructor(limit?: number);
+    /** How many tasks are executing right now. */
+    get active(): number;
+    /** How many tasks are waiting for a slot or for their lane. */
+    get queued(): number;
+    /**
+     * Queue a task on a lane. It starts as soon as a slot is free and no earlier
+     * task on the same lane is still running or waiting.
+     *
+     * The task must not reject: a rejection is swallowed so one broken run can
+     * never wedge its lane, but nothing reports it either — callers catch inside.
+     */
+    submit(lane: string, task: () => Promise<void>): void;
+    /** Resolves once nothing is executing and nothing is waiting. */
+    onIdle(): Promise<void>;
+    private pump;
+    private execute;
+}

package/dist/agent/scheduler.js

@@ -0,0 +1,93 @@
+/**
+ * Which accepted runs execute now, and which wait.
+ *
+ * `agent run` used to chain every run onto one promise: one local agent, one
+ * run at a time. That is still the default, and with a limit of 1 this
+ * scheduler is exactly that chain — strict arrival order, nothing overlapping.
+ *
+ * `--concurrency N` lifts the limit without lifting the rule that actually
+ * protects an answer: **two runs on the same lane never overlap, and they start
+ * in the order they arrived.** A lane is a conversation (see `sessionKeyFor`).
+ * Each turn resumes the session the previous turn left, so running two turns of
+ * one thread side by side would have both resume the same session and the
+ * second answer without having seen the first. Runs on different lanes share
+ * nothing but the machine, and those are the ones allowed to overlap.
+ *
+ * Among the runs free to start, the oldest goes first. A lane that is busy does
+ * not hold up the lanes behind it — which is the whole point: a quick question
+ * in one thread no longer waits out a two-hour job in another.
+ */
+/** Most runs one harness will execute at once, whatever the flag says. */
+export const MAX_CONCURRENCY = 16;
+export class RunScheduler {
+    limit;
+    pending = [];
+    busy = new Set();
+    waiters = [];
+    constructor(limit = 1) {
+        this.limit = limit;
+        if (!Number.isInteger(limit) || limit < 1) {
+            throw new RangeError(`concurrency must be a whole number of at least 1, got ${String(limit)}`);
+        }
+    }
+    /** How many tasks are executing right now. */
+    get active() {
+        return this.busy.size;
+    }
+    /** How many tasks are waiting for a slot or for their lane. */
+    get queued() {
+        return this.pending.length;
+    }
+    /**
+     * Queue a task on a lane. It starts as soon as a slot is free and no earlier
+     * task on the same lane is still running or waiting.
+     *
+     * The task must not reject: a rejection is swallowed so one broken run can
+     * never wedge its lane, but nothing reports it either — callers catch inside.
+     */
+    submit(lane, task) {
+        this.pending.push({ lane, task });
+        this.pump();
+    }
+    /** Resolves once nothing is executing and nothing is waiting. */
+    onIdle() {
+        if (this.busy.size === 0 && this.pending.length === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    pump() {
+        while (this.busy.size < this.limit) {
+            // First in arrival order whose lane is free. An earlier task on a busy
+            // lane is skipped, not waited for; a later task on that same lane is
+            // skipped with it, which is what keeps a lane in order.
+            const index = this.pending.findIndex((entry) => !this.busy.has(entry.lane));
+            if (index === -1)
+                break;
+            const [next] = this.pending.splice(index, 1);
+            if (!next)
+                break;
+            this.busy.add(next.lane);
+            void this.execute(next);
+        }
+        if (this.busy.size === 0 && this.pending.length === 0) {
+            const waiters = this.waiters;
+            this.waiters = [];
+            for (const resolve of waiters)
+                resolve();
+        }
+    }
+    async execute(entry) {
+        try {
+            await entry.task();
+        }
+        catch {
+            /* see `submit` — a task reports its own failure */
+        }
+        finally {
+            this.busy.delete(entry.lane);
+            this.pump();
+        }
+    }
+}