@lincoln504/pi-research 1.0.10 → 1.1.0

package/dist/thread-worker.mjs

@@ -1356,7 +1356,10 @@ function isTransientSocketError(error) {
   err.message.includes("Worker pool is shutting down") || // Poolifier throws this when pool.execute() is called while the pool is being
   // destroyed (e.g., during scheduler restart). Treat as transient — the pool will
   // be ready for new tasks once destruction completes and a new pool is initialized.
-  err.message.includes("Cannot execute a task on destroying pool") || err.message.includes("destroying pool"));
+  err.message.includes("Cannot execute a task on destroying pool") || err.message.includes("destroying pool") || // The leader answered 503 because it is shutting down after losing
+  // leadership. Retrying re-elects and reaches the new leader, so this is
+  // transient in exactly the same sense as a pool drain.
+  err.message.includes("Browser pool leader is draining"));
 }
 function isCloudflareBlockError(error) {
   if (!error || typeof error !== "object") return false;
@@ -1368,6 +1371,11 @@ function isTaskTimeoutError(error) {
   const err = error;
   return typeof err.message === "string" && (err.message.includes("timed out after") || err.message.includes("Search task timed out") || err.message.includes("Scrape task timed out") || err.message.includes("Health check timed out") || err.message.includes("[BrowserClient] Request to"));
 }
+function isServerDrainingError(error) {
+  if (!error || typeof error !== "object") return false;
+  const err = error;
+  return typeof err.message === "string" && err.message.includes("Browser pool leader is draining");
+}
 function isPoolShutdownError(error) {
   if (!error || typeof error !== "object") return false;
   const err = error;
@@ -1389,6 +1397,7 @@ var init_browser_error_utils = __esm({
       name: "BrowserPool",
       isTransientError: (error) => {
         if (isPoolShutdownError(error)) return false;
+        if (isServerDrainingError(error)) return false;
         if (isCloudflareBlockError(error)) return false;
         if (isTaskTimeoutError(error)) return false;
         return isTransientSocketError(error);
@@ -1404,6 +1413,7 @@ __export(scraper_utils_exports, {
   createJsMarkdownConverter: () => createJsMarkdownConverter,
   createNativeMarkdownConverter: () => createNativeMarkdownConverter,
   extractDomain: () => extractDomain,
+  formatErrorWithCause: () => formatErrorWithCause,
   getRandomUserAgent: () => getRandomUserAgent,
   getSsrfSafeDispatcher: () => getSsrfSafeDispatcher,
   isBenignScrapeFailure: () => isBenignScrapeFailure,
@@ -1535,6 +1545,34 @@ async function getSsrfSafeDispatcher() {
   }
   return cachedSsrfDispatcher;
 }
+function formatErrorWithCause(err) {
+  try {
+    const parts = [];
+    let current = err;
+    for (let depth = 0; current !== null && current !== void 0 && depth < 5; depth++) {
+      let segment;
+      if (current instanceof Error) {
+        segment = current.message || current.name;
+        const code = current.code;
+        if (typeof code === "string" && code && !segment.includes(code)) {
+          segment = `${segment} [${code}]`;
+        }
+      } else if (typeof current === "string") {
+        segment = current;
+      } else {
+        segment = String(current);
+      }
+      if (segment && !parts.includes(segment)) parts.push(segment);
+      const next = current.cause;
+      if (next === current) break;
+      current = next;
+    }
+    if (parts.length === 0) return String(err);
+    return parts.length === 1 ? parts[0] : parts.join(" \u2190 ");
+  } catch {
+    return String(err);
+  }
+}
 function isPrivateIp(ip) {
   const parts = ip.split(".").map(Number);
   if (parts.length !== 4 || parts.some((p) => isNaN(p))) return false;

package/docs/ARCHITECTURE.md

@@ -203,6 +203,30 @@ Cross-session, cross-process state (active sessions, browser status, metrics) li
 `StateManagerService` (`src/infrastructure/state/`), which serializes concurrent writes
 with file-based locking (`FileLockService`).
 
+### Concurrent runs (the run cap)
+
+Every pi-research process on a machine — CLI, agent skill, pi extension, SDK — shares
+one leader-elected browser pool and one embedding model. Letting an unbounded number of
+research runs onto that shared pool does not slow runs down gracefully; it saturates the
+priority queue and degrades *all* of them at once.
+
+`ResearchRunSemaphore` (`src/infrastructure/research-run-semaphore.ts`) therefore gates
+every `runResearch()` entry on one of N slots, realized as N well-known lock files in the
+state directory and coordinated by the same `FileLockService`. Because slot ownership is
+recorded as PID + process start time, a slot held by a crashed run is reclaimed
+immediately by the next acquire, while a *live* holder is never stolen — a legitimate run
+holds its slot for minutes, and stealing it would admit the (N+1)th run the cap exists to
+prevent.
+
+Runs beyond the cap **queue** rather than fail: the acquire polls until a slot frees,
+announcing itself once through the observer (`onRunQueued`, surfaced by the CLI as
+`• queued: …`) so a waiting run is never mistaken for a hung one. Only if nothing frees
+within the whole queue window does it raise `ResearchRunCapacityError` — a temporary
+condition the CLI reports as exit code `75`, distinct from a crash. The cap fails *open*
+on any internal or IO error, so a fault in the semaphore itself can never prevent research
+from running. Both the cap and the queue window are configurable
+(`PI_RESEARCH_MAX_CONCURRENT_RUNS`, `PI_RESEARCH_RUN_ACQUIRE_TIMEOUT_MS`).
+
 ### TUI
 
 The live progress panel uses `@earendil-works/pi-tui`, which handles terminal state

package/docs/CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-08-04
+
+### Changed
+- **Concurrent runs over the cap now QUEUE instead of failing — the run-cap default is a queue, not a fail-fast.** v1.0.11 added the machine-wide run cap that stopped parallel runs saturating the shared browser/embedding pool, but it shipped with `PI_RESEARCH_RUN_ACQUIRE_TIMEOUT_MS` defaulting to `0`. That made contention *fatal*: the cap was enforced by rejecting the run outright, in about two seconds, rather than by serializing it. Verified end-to-end before the change — four simultaneous skill runs against the default cap produced two clean reports and two hard failures, with the two rejected queries simply lost. That is the wrong trade for a semaphore guarding a shared resource: an extra run is a legitimate request to do work, not an error. The default acquire wait is now **600000 ms (10 minutes)**, so over-cap runs wait for a slot and then execute normally; a depth-1 run measured at ~2–3 minutes, so this absorbs a backlog of roughly three further runs per slot. `PI_RESEARCH_RUN_ACQUIRE_TIMEOUT_MS=0` restores the old strict fail-fast. The cap itself is raised from **2 to 3** concurrent runs. The agent skill's recommended command timeouts are raised to match (depth 1 `1500000` ms, depth 2 `1800000`, depth 3 `2400000`), since a queued run legitimately takes longer than an unqueued one and the old budgets no longer bounded the worst case.
+- **A queued run now says so** (`• queued: N concurrent run(s) already active — waiting up to Ns for a slot…`) instead of sitting silent for the whole acquire wait. Silence for up to ten minutes is indistinguishable from a hang, which would have made the queueing change above *look* like a regression. The notice is emitted exactly once per run, via a new optional `ResearchObserver.onRunQueued(slots, maxWaitMs)`; because the queue happens before any orchestrator exists, the notification is dispatched to whichever observer shape the caller supplied — a `ResearchObserver` instance (SDK / pi extension) or the `HeadlessObserverOptions` bag carrying only `onProgress` (CLI / agent skill). A throwing front-end callback can never fail the run it is reporting on.
+
+### Added
+- **Distinct exit code `75` (`EX_TEMPFAIL`) for run-cap exhaustion.** Capacity exhaustion previously exited `70` — the same code as a genuine crash — so a calling agent could not tell "this machine is busy with other healthy runs, try again shortly" from "this run is broken", and the agent skill's own exit-code table told it to treat `70` as a transient error worth one immediate retry (which, under a 0 ms acquire, failed again instantly). It now exits `75`, documented in `SKILL.md` with explicit guidance not to reconfigure anything and not to retry in a tight loop, and `--json` output carries `retryable: true`. The classification is matched on the error name so it survives bundling into `dist/cli.mjs`, and is checked ahead of the credentials heuristic — the capacity message names `PI_RESEARCH_MAX_CONCURRENT_RUNS`, and the substring heuristic would otherwise have been at risk of reading a busy machine as a misconfigured one. Capacity exhaustion is also reported without a stack trace, since a routine "busy" state printed as a stack reads as a crash.
+
+### Fixed
+- **A browser-pool leader exiting could destroy a concurrent run outright — the retry reconnected to the dead leader instead of re-electing.** The browser pool is hosted by one elected leader process shared by every pi-research run on the machine, so when that leader finishes its own run and tears down its workers, every other run with work in flight takes `Worker pool is shutting down` on *all* outstanding tasks at once. The recovery path handled this incorrectly: on a pool-shutdown error it only waited for the pool to go idle and **never dropped the cached scheduler handle**, so the single retry called `getScheduler()`, got the same cached client still pointing at the dead leader's port (visible in logs as a retry "Connecting to existing scheduler" with an *identical* version id), and failed the same way. The generic transient-socket branch did the right thing and forced a re-resolve; the pool-shutdown branch — the case where the leader is provably going away — did not. Reproduced in a real six-way concurrent run: a run acquired its slot in the same second the leader shut down, all 20 queries of its search burst failed, and the run aborted with `Search completely failed: all 20 queries encountered worker errors` and the tell-tale `60 tracked error(s) … "Worker pool is shutting down" ×60` — roughly two seconds *before* a fresh leader finished being elected and served everyone else normally. A handover now drops the stale handle and forces re-resolution (joining the new leader, or winning the election itself), and gets its own retry budget of 3 attempts with a ~1.2 s backoff, sized to a real election rather than to the 100–500 ms jitter meant for a socket blip. The budget is tracked separately from the generic retry so a handover cannot be starved by, or consume, the single transient-socket attempt; genuinely unrecoverable pool loss still gives up rather than retrying forever. This failure mode became far more likely with over-cap queueing, since a queued run is admitted at exactly the moment another run finishes — which is exactly when the leader may be tearing down.
+- **The run-cap's two environment variables were entirely undocumented.** `PI_RESEARCH_MAX_CONCURRENT_RUNS` and `PI_RESEARCH_RUN_ACQUIRE_TIMEOUT_MS` shipped in v1.0.11 and appeared in neither `docs/CONFIGURATION.md` nor `.env.example` — the latter described in the docs as "the canonical, exhaustive list" — even though the capacity error message explicitly instructed the user to override the first of them. Both are now documented in both places, and the run cap has an `ARCHITECTURE.md` section covering slot ownership, crash reclamation, queueing and fail-open behaviour.
+- **`docs/SDK.md` recommended a workaround that the run cap had since made unreliable** — it told callers to "use a separate process per concurrent run" with no mention that separate processes are themselves bounded machine-wide, so following the documented advice past the cap hit a hard failure. It now documents the cap, the queue window, `ResearchRunCapacityError`, exit code `75`, and `onRunQueued`.
+
+## [1.0.12] - 2026-08-03
+
+### Fixed
+- **Run-cap / file-lock / leader-election could misreport a live process as dead (Windows/macOS) — the root cause of the flaky `run-semaphore-multiprocess` integration failures on Windows CI.** `ProcessLifecycleService.isProcessAlive(pid, expectedStartTime)` returned `false` ("dead") whenever `process.kill(pid, 0)` confirmed the process was alive but the follow-up **start-time lookup failed**. On Linux that null reliably means the process exited in the microsecond gap between the `signal(0)` and the `/proc/{pid}/stat` read, so `false` was correct — but on Windows/macOS the start time comes from a subprocess (`powershell Get-Process` / `ps`) that can fail or time out under load while the process is still very much alive. Reporting a confirmed-alive PID as dead is catastrophic for *every* caller: a live lock / leader / run-cap owner is reclaimed from under it, so two writers collide (lost update) or the run-cap admits extra concurrent runs. The v1.0.11 Windows CI failure manifested both ways depending on timing — `expected 3 to be 4` (two holders collided on one slot) and `expected +0 to be 3` (a 5th process stole a live holder's slot and was admitted past the cap). The fix re-confirms liveness instead of guessing: when the start-time lookup returns null it issues a second `signal(0)`; if the process is still alive it reports `true`, and only if that probe throws (the process genuinely died in the interim) does the outer handler return `false`. A real death is therefore still detected within one poll tick (~100 ms); the only behavioural change is that a confirmed-alive process is never again reclaimed on a transient start-time lookup failure. PID-reuse protection is unchanged when the start time is resolvable (the `±1s` slack comparison still applies). This is a strict safety improvement across all consumers — file locks, the run-cap semaphore, GPU locks, the embedding leader, browser scheduler and state sessions — none of which ever wanted a live owner treated as dead.
+- **Stack Exchange integration tests no longer fail when the upstream API returns empty results** — the Stack Exchange `search` endpoints intermittently answer `200 OK` (quota consumed, no error) with a zero-item `items:[]` for queries that normally return thousands of results (verified 2026-08-03: `q=javascript` on Stack Overflow returned `[]` from a residential IP). This is an upstream API degradation / contract drift, not a pi-research code fault and not a datacenter-IP block, yet it hard-failed the serial integration suite on all three CI OSes and thereby blocked every release whose code was otherwise identical to a previously-green build. The integration-test environment-skip helper (`isNetworkUnavailable`) now also recognizes a successful-but-empty Stack Exchange response (anchored on the tool-specific `**API Quota:**` footer plus the zero-item body) and skips the affected tests visibly via `ctx.skip()` — the same treatment already given to transport errors and `429`/`5xx` throttling. The anchor is emitted only by the Stack Exchange tool, so it cannot mask a regression in any other tool, and a populated result still exercises the assertions in full.
+
+## [1.0.11] - 2026-08-02
+
+### Added
+- **Cross-process research run-cap** — a machine-wide counting semaphore (`ResearchRunSemaphore`) now gates every `runResearch()` entry on one of N file-lock slots. This is the root-cause fix for the parallel-run instability (60+ error storms and, on constrained hosts, process aborts) that occurred when several research runs saturated the single shared leader-elected browser/embedding pool at once. Holders are reclaimed immediately when their PID exits (PID + startTime guards against PID reuse); *live* holders are never stolen, because a run legitimately holds a slot for minutes. The cap **fails open** on any internal/IO error (a semaphore bug can never break research) and **fails fast** with a distinct `ResearchRunCapacityError` only on genuine capacity exhaustion. (Phase 1 of the multi-run hardening plan.)
+- **Browser leader `drain` / 503 handover** — when the elected leader loses leadership (election loss, idle timeout, or shutdown), it now enters a draining state that answers new requests with an explicit `503 { error: "draining" }` *before* closing the listener, instead of letting connected clients stall on a connect timeout or bare reset. The client classifies this as a transient "re-elect and retry" signal (logged at DEBUG, recorded under its own `draining` errorType for forensics) and it is deliberately excluded from the circuit breaker so a routine leadership handover never reads as an incident.
+
+### Fixed
+- **Citation rewriting regression — `[removed]` tokens, list/code corruption, `[0]` deletion** — the prior placeholder-citation defense rewrote synthesis bodies with a global space collapse that flattened nested lists and 4-space code blocks, deleted bracketed integers *inside* quoted code (`items[12]`), treated `[0]` as a citation, and emitted broken `[removed]` tokens for dropped citations. All replaced by a structure-preserving rewrite: fenced blocks and inline-code spans are skipped entirely, line-leading indentation is preserved, dangling markers are removed cleanly (never as a visible token), and `[N]` outside a plausible citation range (`1..200`) and `[0]` are left untouched.
+- **Provenance gate mass-dropping legitimate citations** — the gate that previously DROPPED citations tagged Scrape/Transcript when their URL was absent from the successful-scrape pool conflated a *blocked* scrape (real URL, content unretrieved) with fabrication: under the common high-scrape-failure rate (bot blocks on GitHub / Microsoft / etc.) it mass-deleted real citations. The gate is removed; every parsed citation is now kept (deduped by URL). Fabrication defense rests on URL dedup plus a new prose-URL sweep instead of punishing failed scrapes.
+- **Fabricated inline URLs in synthesis prose** — inline `https?://` tokens in the report body whose URL was not retrieved this session are now redacted to `[link removed: not found in retrieved sources]` (verified inline references are kept). A matching caveat block is appended when a model-written `CITED LINKS` section survives a run that retrieved nothing, so no report ships fully-sourced-looking with no warning on a zero-retrieval run.
+- **Fetch-layer scrape had no retry** — the fetch layer was the only scrape layer with no transient retry, so a single socket/DNS blip (ECONNRESET, ENOTFOUND, `UND_ERR_*`, a bare `fetch failed`) cost a full 10–30× slower browser render. It now retries once (250 ms, gated on `isTransientError`) before falling back to the stealth browser; SSRF rejections, size caps and 4xx rethrow immediately. Error tracking is recorded exactly once per URL (moved out of the retried layer) rather than once per attempt.
+- **Uninformative `fetch failed` scrape logs** — Node/undici wraps the real transport reason under `error.cause`; logging only `String(err)` recorded the uninformative top-level message and discarded it. A new `formatErrorWithCause` walks the cause chain (bounded, `.code`-folding, defensive) so every fetch-failure line is self-diagnosing; it is now used consistently across the scrape path.
+- **Final synthesis body never logged** — every other layer (researcher prompts/responses, searches, scrapes) was logged at DEBUG, but the synthesis itself — the actual bytes returned to the caller — was the one conspicuous exception, making post-hoc diagnosis of citation/output reports impossible. The full final and fallback synthesis bodies are now logged at DEBUG.
+- **`abortableDelay` could exit the process mid-operation** — the timer was unconditionally `unref`'d, so a foreground backoff that was the sole pending handle let Node drain the loop and silently truncate work. A `keepAlive` option (used by the new foreground fetch retry) holds the loop until the operation completes; background callers are unaffected.
+
+## [1.0.10] - 2026-07-30
+
+### Fixed
+- **pi 0.83.0 compatibility — `ResourceLoader` contract** — pi 0.83.0 extended the `ResourceLoader` contract with `getSystemPromptSource()` and `getAppendSystemPromptSources()` (consumed by interactive mode's startup context listing for file-backed `SYSTEM.md`/`APPEND_SYSTEM.md`). The in-memory sub-session loader now implements both, returning "no backing file" — accurate for prompts passed as text. The extra methods are harmless on pre-0.83 hosts, so the supported range stays `>=0.80.8 <1`. Audited the 0.82.1→0.83.0 dist diffs: the only other contract change (`ExtensionContext.scopedModels`) is provided by pi's own session code, and the mock runtime path has been immune since v1.0.9 via `createExtensionRuntime()`.
+
 ## [1.0.9] - 2026-07-28
 
 ### Fixed

package/docs/CONFIGURATION.md

@@ -76,6 +76,8 @@ Research
 | `PI_RESEARCH_MAX_FAILED_RESEARCHERS` | `2` | 1–10 | Unique researcher failures that abort the whole run. Raise to let slower, still-in-flight researchers finish before giving up. |
 | `PI_RESEARCH_WORKER_THREADS` | `4` | 1–10 | Browser worker processes. Higher = more throughput, more CPU/RAM. |
 | `PI_RESEARCH_WORKER_CONCURRENCY` | `2` | 1–10 | Tasks per worker process. |
+| `PI_RESEARCH_MAX_CONCURRENT_RUNS` | `3` | ≥1 | Machine-wide cap on research runs executing at the same time, across **every** process (CLI, agent skill, pi extension, SDK). Runs beyond the cap queue rather than fail. All concurrent runs share one leader-elected browser/embedding pool, so oversubscribing it degrades every run at once. |
+| `PI_RESEARCH_RUN_ACQUIRE_TIMEOUT_MS` | `600000` | ≥0 | How long a run queues for a free slot before failing with "maximum concurrent research runs reached" (CLI exit `75`). `0` = fail immediately instead of queueing. |
 | `PI_RESEARCH_MODEL` | _(pi: session model; CLI/skill: required)_ | — | The model research runs on. **Required for the standalone CLI / agent skill** — they use only this configured model (never the model selected inside the pi extension) and refuse to start without one (the CLI's per-run `--model` flag also satisfies this). On the SDK it selects the session model when no `model` option is given. In the pi extension it overrides researcher sub-agents and knowledge synthesis, while the coordinator and evaluator keep using the session model. Accepts `provider/id` or a bare model id. |
 | `PI_RESEARCH_DISABLED_TOOLS` | _(none)_ | — | Comma-separated research tools to disable for a run (`search`, `scrape`, `security_search`, `stackexchange`, `youtube_transcript`, `grep`). Removed from every researcher's toolset and named in the coordinator/evaluator prompt. |
 | `PI_RESEARCH_REPORT_EXPORT_ENABLED` (TUI) | `false` | — | Front-ends write a Markdown report to disk and surface its path. |

package/docs/SDK.md

@@ -85,6 +85,15 @@ report caused by a sparse topic apart from one where most researchers failed). B
 > Concurrency: a single initialized SDK instance runs one research call at a time.
 > Overlapping `runDeepResearch`/`runQuickResearch` calls on the same instance throw
 > — run them sequentially, or use a separate process per concurrent run.
+>
+> Separate processes are additionally bounded by a **machine-wide run cap**
+> (`PI_RESEARCH_MAX_CONCURRENT_RUNS`, default 3) covering every pi-research process
+> on the host, because they all share one leader-elected browser/embedding pool. A
+> run over the cap queues for up to `PI_RESEARCH_RUN_ACQUIRE_TIMEOUT_MS` (default
+> 10 min) and only then rejects with `ResearchRunCapacityError` — a temporary
+> "try again shortly" condition, surfaced by the CLI as exit code `75`. Supply an
+> observer with `onRunQueued(slots, maxWaitMs)` to tell a waiting user the run is
+> queued rather than hung.
 
 The SDK does not write report files. Report export is a front-end concern — the pi
 extension and the CLI / agent skill do it when `PI_RESEARCH_REPORT_EXPORT_ENABLED=true`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.0.10",
+  "version": "1.1.0",
   "description": "A set of web research tools (search, scrape, and others) and research agent system that uses them safely and efficiently.",
   "type": "module",
   "private": false,
@@ -142,7 +142,10 @@
     "ua-parser-js": "^1.0.41",
     "protobufjs": "7.6.5",
     "vite": "^8.0.16",
-    "adm-zip": "^0.6.0"
+    "adm-zip": "^0.6.0",
+    "jsdom": {
+      "undici": "^7.29.0"
+    }
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/skills/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.0.10", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.1.0", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 
@@ -22,8 +22,16 @@ node "<SKILL_DIR>/scripts/run.mjs" status    [--json]
 - **stderr** = progress + errors — relay errors, suppress routine progress.
 - **Always set a generous command timeout** so a stalled run can't block forever, but
   leave plenty of headroom — a real run should finish well inside it:
-  `knowledge` 600000ms · `research --depth 1` 900000ms · `--depth 2` 1200000ms · `--depth 3` 1800000ms.
+  `knowledge` 600000ms · `research --depth 1` 1500000ms · `--depth 2` 1800000ms · `--depth 3` 2400000ms.
+  These already include headroom for the run to sit **queued** behind other runs on a
+  busy machine (see below); don't shorten them on the assumption a slot is free.
 - **Background**: append `&` and keep the PID to work while a run completes; otherwise it runs foreground (blocks). Timeouts apply either way.
+- **Several at once is fine.** Up to 3 runs execute concurrently machine-wide (shared
+  with any other tool or agent on this machine); further runs **queue** for a slot and
+  report `• queued: …` on stderr — that is normal, not a stall. Only if nothing frees
+  up within the queue window does a run exit `75` (see *Exit codes*). Prefer one
+  `research` call with a well-scoped query over splitting one topic into many parallel
+  calls — depth 1 already parallelises internally.
 
 ## Workflow
 
@@ -57,6 +65,7 @@ node "<SKILL_DIR>/scripts/run.mjs" status    [--json]
 | `0` | Success | Read stdout; cite sources; relay any "saved to: <path>" line. |
 | `78` on `knowledge` | Store disabled/unconfigured | Silent; proceed to `research`. |
 | `78` on `research` | Engine missing or no model/key | **Stop. Relay full stderr** (it shows where to configure). Don't retry until fixed. |
+| `75` | Machine at capacity — other research runs are already using every slot | **Nothing is broken.** Wait for an in-flight run to finish, then retry this query once. Don't reconfigure anything and don't retry in a tight loop. |
 | `70` | Runtime error | Relay stderr; suggest one retry for transient failures (network, rate limit). |
 | `64` | Bad arguments | Fix args; don't surface unless the query itself is malformed. |
 

package/src/cli.ts

@@ -76,6 +76,14 @@ export const EXIT = {
   CONFIG: 78,
   /** Something went wrong at runtime (network, provider, internal). */
   SOFTWARE: 70,
+  /**
+   * Temporary failure — the request was well-formed and the install is healthy,
+   * but the machine is at capacity right now (all research run slots held by
+   * live runs). Distinct from SOFTWARE so a calling agent can tell "busy, try
+   * again shortly" apart from "this run crashed" and back off instead of
+   * re-running a broken command.
+   */
+  TEMPFAIL: 75,
 } as const;
 
 // ---------------------------------------------------------------------------
@@ -108,6 +116,12 @@ function makeProgressObserver(): HeadlessObserverOptions {
         case 'planning_success':
           toStderr(`  • plan: ${data?.plan?.researchers?.length ?? '?'} researcher(s)\n`);
           break;
+        case 'run_queued':
+          toStderr(
+            `  • queued: ${data?.slots ?? '?'} concurrent run(s) already active — waiting up to ` +
+              `${Math.round((data?.maxWaitMs ?? 0) / 1000)}s for a slot…\n`,
+          );
+          break;
         case 'round_start':
           toStderr(`  • round ${data?.round}\n`);
           break;
@@ -829,9 +843,19 @@ export async function reportError(err: unknown, what: string, json?: boolean): P
   // research-stop — regardless of real cause — as a config error (exit 78).
   const isTaggedResearchStop = (err as { code?: unknown } | undefined)?.code === RESEARCH_STOPPED_ERROR_CODE;
 
+  // Run-cap exhaustion is an operational state, not a fault: every slot is held by
+  // another *healthy* live run. Matched on the error name rather than `instanceof`
+  // so it survives bundling (dist/cli.mjs) and any duplicate module instance.
+  // Checked ahead of the substring heuristics below rather than relying on the
+  // current wording of the message: capacity text is config-shaped (it names two
+  // PI_RESEARCH_* env vars), so an exact classification must not depend on that
+  // message never drifting into one of the credential keywords. Misreading a busy
+  // machine as a setup problem would send the user to reconfigure a working install.
+  const isCapacity = err instanceof Error && err.name === 'ResearchRunCapacityError';
+
   // Auth / model / config-shaped errors → CONFIG exit + config block.
   const isConfigError =
-    !isTaggedResearchStop && (
+    !isTaggedResearchStop && !isCapacity && (
     lower.includes('no llm model available') ||
     lower.includes('not found in pi') ||
     lower.includes('no api key') ||
@@ -846,12 +870,19 @@ export async function reportError(err: unknown, what: string, json?: boolean): P
   // classifying that as a setup problem sends the user to reconfigure a
   // perfectly working key instead of waiting out the limit.
   const isRateLimit = lower.includes('429') || lower.includes('rate limit') || lower.includes('too many requests');
-  const exitCode = isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
+  const exitCode = isCapacity
+    ? EXIT.TEMPFAIL
+    : isConfigError && !isRateLimit
+      ? EXIT.CONFIG
+      : EXIT.SOFTWARE;
 
   // --json: emit a structured error on stdout so a machine consumer never has to
   // special-case plain-text stderr. Mirrors the { ok: true, ... } success shape.
   if (json) {
     const payload: Record<string, unknown> = { ok: false, error: msg, exitCode };
+    // Machine-readable "this will succeed later" flag, so a consumer can back off
+    // and retry without string-matching the human message.
+    if (isCapacity || isRateLimit) payload['retryable'] = true;
     if (process.env['PI_RESEARCH_DEBUG'] === 'true' && err instanceof Error && err.stack) {
       payload['stack'] = err.stack;
     }
@@ -859,6 +890,13 @@ export async function reportError(err: unknown, what: string, json?: boolean): P
     return exitCode;
   }
 
+  // Capacity exhaustion is a healthy-machine "busy" state — report it as such and
+  // never with a stack trace, which would read as a crash for a routine condition.
+  if (isCapacity) {
+    toStderr(`\nError: pi-research ${what} did not start: ${msg}\n`);
+    return exitCode;
+  }
+
   // Rate limits are operational, not fatal setup problems — checked FIRST.
   if (isRateLimit) {
     toStderr(`\nError: pi-research ${what} halted: provider rate limit reached. Wait a moment and retry.\n  ${msg}\n`);

package/src/core/interfaces/observer-interfaces.ts

@@ -18,6 +18,15 @@ export interface HeadlessObserverOptions {
 export interface ResearchObserver {
   onStart?(query: string, complexity: number): void;
 
+  /**
+   * Fired once when the run cannot start immediately because every concurrent-run
+   * slot is held, and it is about to queue. Without this a queued run is silent
+   * for as long as the acquire wait allows, which is indistinguishable from a hang.
+   * @param slots  the machine-wide concurrent-run cap
+   * @param maxWaitMs how long the run will queue before giving up
+   */
+  onRunQueued?(slots: number, maxWaitMs: number): void;
+
   // Coordinator/Planning phase
   onPlanningStart?(attempt: number): void;
   onPlanningProgress?(status: string): void;

package/src/core/interfaces/service-names.ts

@@ -31,6 +31,8 @@ export const ServiceNames = {
   // Research session services
   RESEARCH_SESSION_SERVICE: 'research-session-service',
   RESEARCH_SYNTHESIS_SERVICE: 'research-synthesis-service',
+  // Cross-process cap on concurrent research runs (Phase 1 run-cap)
+  RESEARCH_RUN_SEMAPHORE: 'research-run-semaphore',
 } as const;
 
 /**

package/src/infrastructure/browser/browser-client.ts

@@ -103,7 +103,25 @@ export class BrowserClient implements IScheduler {
                     const duration = Date.now() - start;
                     try {
                         const parsed = JSON.parse(body);
-                        if (res.statusCode !== 200) {
+                        if (res.statusCode === 503 && parsed?.error === 'draining') {
+                            // Planned leadership handover, not a fault. Distinct message so
+                            // isServerDrainingError can classify it: retry paths treat it as
+                            // transient and the circuit breaker ignores it. Logged at DEBUG,
+                            // not ERROR, so a routine re-election doesn't read as an incident.
+                            // It is still recorded in the error tracker (this file records every
+                            // non-200 uniformly) under its own `draining` errorType, which is
+                            // what keeps handovers distinguishable from real 503s in forensics.
+                            const error = new Error(
+                                `Browser pool leader is draining (${parsed.reason || 'leadership-lost'}) — re-elect and retry`,
+                            );
+                            logger.debug(`[BrowserClient] Leader draining on ${path}; re-election required.`);
+                            errorTracker.trackError(error, {
+                                component: 'browser-manager',
+                                operation,
+                                errorType: 'draining',
+                            });
+                            reject(error);
+                        } else if (res.statusCode !== 200) {
                             const error = new Error(parsed.error || `HTTP ${res.statusCode}`);
                             errorTracker.trackError(error, {
                                 component: 'browser-manager',

package/src/infrastructure/browser/browser-error-utils.ts

@@ -31,7 +31,11 @@ export function isTransientSocketError(error: unknown): boolean {
         // destroyed (e.g., during scheduler restart). Treat as transient — the pool will
         // be ready for new tasks once destruction completes and a new pool is initialized.
         err.message.includes('Cannot execute a task on destroying pool') ||
-        err.message.includes('destroying pool')
+        err.message.includes('destroying pool') ||
+        // The leader answered 503 because it is shutting down after losing
+        // leadership. Retrying re-elects and reaches the new leader, so this is
+        // transient in exactly the same sense as a pool drain.
+        err.message.includes('Browser pool leader is draining')
     );
 }
 
@@ -68,11 +72,36 @@ export function isTaskTimeoutError(error: unknown): boolean {
     );
 }
 
+/**
+ * Check if an error is a "leader is draining" rejection (HTTP 503 from
+ * {@link BrowserServer.beginDrain}).
+ *
+ * The leader answers 503 while tearing down after losing leadership, so this is
+ * an expected transition signal rather than a fault: the correct response is to
+ * re-elect and retry against the new leader. It must not count toward the
+ * circuit breaker — a leadership handover would otherwise look like a burst of
+ * infrastructure failures and open the breaker for every subsequent request.
+ */
+export function isServerDrainingError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') return false;
+    const err = error as NodeError;
+    return typeof err.message === 'string' && err.message.includes('Browser pool leader is draining');
+}
+
 /**
  * Check if an error is specifically a pool-shutdown / pool-drain error.
- * For these errors the scheduler itself is fine — only the WorkerPool is temporarily
- * draining. The correct recovery is to wait for the drain to finish and retry,
- * NOT to call forceSchedulerRestart (which would start another drain cycle).
+ *
+ * These are never counted against the circuit breaker: the pool recovers on its own.
+ *
+ * NOTE: this was once documented as "wait for the drain to finish and retry, NOT
+ * forceSchedulerRestart". That is right only when the draining pool is *local*. In the
+ * common case the pool belongs to another process — the elected leader — which is
+ * exiting, so waiting alone leaves the cached client pointed at a dead port and the
+ * retry fails identically (this cost whole search bursts; see the v1.1.0 changelog).
+ * Recovery must also drop the cached scheduler handle so the next call re-resolves the
+ * new leader; `recoverFromLeaderHandover` in task-execution-service.ts does exactly
+ * that, using `forceSchedulerRestart(false)` whose liveness probe and in-progress guard
+ * prevent the restart churn the old note was warning about.
  */
 export function isPoolShutdownError(error: unknown): boolean {
     if (!error || typeof error !== 'object') return false;
@@ -107,6 +136,9 @@ const DEFAULT_BREAKER_CONFIG: any = {
     isTransientError: (error: unknown) => {
         // Pool-drain transients: pool recovers on its own — don't count.
         if (isPoolShutdownError(error)) return false;
+        // Leadership handover (503 draining) is a planned transition, not a
+        // failure — counting it would open the breaker on every re-election.
+        if (isServerDrainingError(error)) return false;
         // Cloudflare blocks are content-layer rejections, not infra failures — don't count.
         if (isCloudflareBlockError(error)) return false;
         // Task-level timeouts (slow/unresponsive sites) are expected during parallel

package/src/infrastructure/browser/browser-server.ts

@@ -32,9 +32,57 @@ export function getBrowserServerAuthSecret(): string {
 export class BrowserServer {
     private server: http.Server | null = null;
     private port: number = 0;
+    /**
+     * Live client sockets. Tracked so teardown can tell whether anyone is still
+     * attached (`hasActiveClients`) rather than guessing, and so drain has a
+     * meaningful count to report.
+     */
+    private connections: Set<import('node:net').Socket> = new Set();
+    private draining = false;
+    /**
+     * Why this server stopped accepting work. Reported to the client so a log line
+     * says which teardown it hit — a lost election, an idle timeout, or process
+     * shutdown all reach the same code path but are very different incidents.
+     */
+    private drainReason = 'shutting-down';
 
     constructor(private options: BrowserServerOptions) {}
 
+    /**
+     * Enter draining mode: every *subsequent* request is answered `503` instead of
+     * being served or left to hit a closed socket. Requests already past this
+     * check run to completion, so drain never truncates in-flight work.
+     *
+     * This exists for leadership-loss teardown. Without it a client that is
+     * mid-conversation with a leader that just lost the election waits out a
+     * connect timeout or gets a bare ECONNREFUSED/RST once the listener closes,
+     * and only then re-elects. An explicit 503 turns that silent stall into an
+     * immediate, unambiguous "this leader is gone — re-elect now".
+     *
+     * Idempotent: calling it while already draining is a no-op.
+     */
+    beginDrain(reason = 'shutting-down'): void {
+        if (this.draining) return;
+        this.draining = true;
+        this.drainReason = reason;
+        logger.log(`[BrowserServer] Draining (${reason}) — refusing new requests with 503 (${this.connections.size} client connection(s) attached).`);
+    }
+
+    /** True once {@link beginDrain} has been called. */
+    isDraining(): boolean {
+        return this.draining;
+    }
+
+    /** Whether any client socket is currently attached. */
+    hasActiveClients(): boolean {
+        return this.connections.size > 0;
+    }
+
+    /** Number of attached client sockets (observability / teardown decisions). */
+    getConnectionCount(): number {
+        return this.connections.size;
+    }
+
     async start(): Promise<number> {
         return new Promise((resolve, reject) => {
             this.server = http.createServer(async (req, res) => {
@@ -49,6 +97,20 @@ export class BrowserServer {
                     return;
                 }
 
+                // Checked after auth so an unauthenticated caller cannot probe
+                // leadership state, and before routing so no new work is started
+                // against a pool that is being torn down. `Connection: close`
+                // stops the client reusing this socket for a retry that would
+                // only 503 again.
+                if (this.draining) {
+                    res.writeHead(503, {
+                        'Content-Type': 'application/json',
+                        'Connection': 'close',
+                    });
+                    res.end(JSON.stringify({ error: 'draining', reason: this.drainReason }));
+                    return;
+                }
+
                 if (req.method !== 'POST') {
                     res.writeHead(405);
                     res.end('Method Not Allowed');
@@ -138,6 +200,13 @@ export class BrowserServer {
                 });
             });
 
+            this.server.on('connection', (socket) => {
+                this.connections.add(socket);
+                socket.on('close', () => {
+                    this.connections.delete(socket);
+                });
+            });
+
             this.server.listen(0, '127.0.0.1', () => {
                 const addr = this.server?.address();
                 if (addr && typeof addr === 'object') {
@@ -162,6 +231,7 @@ export class BrowserServer {
             return new Promise((resolve) => {
                 this.server?.close(() => {
                     this.server = null;
+                    this.connections.clear();
                     resolve();
                 });
             });

package/src/infrastructure/browser/browser-task-scheduler.ts

@@ -108,7 +108,7 @@ export class BrowserTaskScheduler implements IScheduler {
                     if (this.consecutiveLeadershipMisses >= this.LEADERSHIP_MISS_THRESHOLD) {
                         metrics.increment('browser_leadership_lost_total', 1);
                         logger.error(`[Scheduler] Leadership threshold exceeded (${this.consecutiveLeadershipMisses} misses), shutting down pool...`);
-                        await this.shutdown();
+                        await this.shutdown('leadership-lost');
                         return;
                     }
                 } else {
@@ -145,7 +145,7 @@ export class BrowserTaskScheduler implements IScheduler {
             // getService throwing during a concurrent container disposal) would otherwise surface
             // as an unhandledRejection from this fire-and-forget timer. Swallow it — an idle
             // teardown that fails is non-fatal; the next run gets a fresh scheduler regardless.
-            this.shutdown().catch(err => logger.warn('[Scheduler] Idle-timeout shutdown failed (non-fatal):', err));
+            this.shutdown('idle-timeout').catch(err => logger.warn('[Scheduler] Idle-timeout shutdown failed (non-fatal):', err));
         }, this.IDLE_TIMEOUT_MS);
         if (this.idleTimer.unref) this.idleTimer.unref();
     }
@@ -374,10 +374,26 @@ export class BrowserTaskScheduler implements IScheduler {
         return result;
     }
 
-    async shutdown() {
+    /**
+     * @param reason why the pool is going away. Reported verbatim to clients in the
+     *   drain 503, so a lost election, an idle timeout and a process shutdown are
+     *   distinguishable in a client-side log rather than all reading as one.
+     */
+    async shutdown(reason = 'shutting-down') {
         if (this.isShuttingDown) return;
         this.isShuttingDown = true;
 
+        // Start draining before any of the teardown below. Clearing state and
+        // stopping the pool involves awaits, and until the listener actually
+        // closes a connected client would otherwise keep issuing requests against
+        // a pool that is already going away — the leadership-loss case this
+        // guards. Draining first turns those into an immediate 503 so the client
+        // re-elects at once instead of waiting for a reset.
+        if (this.server?.hasActiveClients()) {
+            logger.log(`[Scheduler] Draining ${this.server.getConnectionCount()} client connection(s) before shutdown (${reason}).`);
+        }
+        this.server?.beginDrain(reason);
+
         if (this.idleTimer) {
             clearTimeout(this.idleTimer);
             this.idleTimer = null;

package/src/infrastructure/browser/scheduler-factory.ts

@@ -139,7 +139,7 @@ export async function forceSchedulerRestart(forceClearRemoteState: boolean = fal
 
         if (oldScheduler && 'schedulerId' in oldScheduler && oldScheduler.schedulerId) {
             if (oldScheduler instanceof BrowserTaskScheduler) {
-                const shutdownPromise: Promise<void> = oldScheduler.shutdown().catch((err: unknown) => {
+                const shutdownPromise: Promise<void> = oldScheduler.shutdown('leadership-lost').catch((err: unknown) => {
                     logger.warn('[Scheduler] Error during old scheduler shutdown after restart:', err);
                 });
                 schedulerService.setPendingShutdownPromise(shutdownPromise);