@lincoln504/pi-research 1.0.12 → 1.1.2

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.2] - 2026-08-04
+
+> Supersedes `v1.1.1`, which was tagged but never published: its release run was
+> correctly blocked by a red CI, and the tag is retained only as a marker of that
+> attempt. Everything below is the full set of changes since 1.1.0.
+
+### Fixed
+- **The multi-process run-cap test counted cumulative slot acquisitions as concurrent ones.** The "thundering herd" test asserts the *concurrent* cap but tallied *cumulative* `acquired` events, and let its winners hold for a finite 4 s. On a slow runner the six contenders start staggered, so a late one can attempt after an early winner's hold has already elapsed, legitimately win the freed slot, and push the cumulative tally past the cap while at most `MAX` ever held at once — a false failure that blocked this release on Windows CI. Confirmed by direct reproduction: with the stagger forced, four acquisitions were recorded against a maximum of two concurrent holders, the late pair's acquire timestamps falling strictly after the early pair's releases on reused slots. Winners now hold until killed, so there is no free slot to win and the count measures genuine simultaneity — a strictly stronger assertion. Test-only; the semaphore itself was never at fault and is unchanged. (The sibling "distinct slot assignments" test was fixed the same way in 1.1.0; that change cited this test's own stated principle but left this test on the racy pattern.)
+- **Citation markers could be silently retargeted at the wrong source.** When merging researcher reports, `normalizeCitations` renumbers each report's local `[N]` markers to global ids — but a marker it could not map was left *verbatim* instead of being removed. Global ids are assigned densely from 1, so a surviving `[1]` no longer meant "this report's first source": it resolved against the renumbered global list and pointed at an unrelated document. Markers go unmapped whenever `parseCitations` legitimately drops an entry, e.g. a URL whose hostname has no dot (`localhost`, a bare internal host, a malformed line). This was not cosmetic — the normalized body is fed straight into the evaluator/synthesis prompt, which is explicitly told the numbering is already global, so the model faithfully reproduced the wrong attribution, and `ensureCitedLinks` then regenerated a `CITED LINKS` list perfectly consistent with it. A correct structure-preserving rewriter already existed on the synthesis path (added in 1.0.11); it is now shared, so dangling markers are removed cleanly while fenced blocks and inline-code spans — a quoted `items[12]` — stay untouched. The prior test could never have caught this: its assertion was structurally guaranteed by the CITED-LINKS slice regardless of marker handling.
+- **A retry could silently abandon the operation instead of retrying it.** `retryWithBackoff` awaited its inter-attempt sleep on an `unref`'d timer. The sleep *is* the operation — the retry has already been decided and the next attempt must run — and `abortableDelay`'s own docstring says exactly that (`web-scraper.ts` passes `keepAlive` with a comment explaining why); the backoff simply omitted it. The failure compounds itself: the transient network errors that trigger a retry are precisely the ones that leave no referenced socket handle, so the backoff is frequently the *only* pending handle, and Node drains the event loop and exits mid-retry. The next attempt never runs and nothing is reported — in the CLI neither branch of the top-level handler fires, so the user gets a bare exit with no report and no error. Affected every `retryWithBackoff` caller (LLM planning, all four security clients, YouTube transcripts) plus both knowledge-search retry loops.
+- **The circuit breaker could pin permanently in `HALF_OPEN`, collapsing parallel search bursts.** `onFailure` is the only path back to `OPEN` and is skipped for errors the breaker does not count, while `transitionTo('HALF_OPEN')` never re-arms `nextAttemptTime` — so a trial probe failing with a non-counted error left the breaker stuck with no time-based escape, fast-failing every caller beyond `halfOpenMaxCalls` (default 1) indefinitely. This was not a corner case for the browser pool: `DEFAULT_BREAKER_CONFIG.isTransientError` deliberately excludes pool-shutdown, draining, Cloudflare and task-timeout errors — exactly what a recovering or blocked pool returns — so the probe most likely to run was also the one most likely to pin it. A non-counted probe failure is now treated as *inconclusive* and re-opens with a fresh reset window.
+- **`npm install <dir>`, `file:`, `npm link` and `pi install <dir>` aborted during install.** The published package ships the built `skills/pi-research/scripts/run.mjs` and deliberately excludes its `run.ts` source, yet also ships `prepare.cjs` + `build.cjs` — and `prepare` runs `build.cjs all`, whose `skill` target hard-requires `run.ts` as its esbuild entry point. Running the shipped build against the shipped tree failed with `Could not resolve run.ts` and exit 1. Registry `.tgz` and `npx` installs were unaffected only because `prepare` does not run there. The target now no-ops when `run.ts` is absent and `run.mjs` is already built, and still errors when neither exists.
+- **A pool-reset error told callers to retry, but nothing recognised it.** `worker-pool-manager` throws `Worker pool is being reset, please retry` while auto-recovery swaps the pool, and no error classifier matched that string — so the first attempt rethrew instead of retrying. Auto-recovery fires only after 3 consecutive worker failures, i.e. exactly when a burst of tasks is in flight and would all fail together: the same user-visible shape as the leader-handover loss fixed in 1.1.0, entering through a different door. Now classified as a transient pool-unavailable condition.
+- **Cancelling a run at the wrong moment could kill the process.** `withTimeout`'s early-abort path returned before attaching to the caller-supplied promise, orphaning that promise's eventual rejection. Node 22+ defaults to `--unhandled-rejections=throw`, and the main process registers no `unhandledRejection` handler, so an Esc timed between two awaits (reachable via the YouTube transcript client, which threads the same signal into both) crashed the host instead of cancelling cleanly. The in-flight rejection is now adopted before bailing out.
+
+### Changed
+- **Model-resolution errors now lead with the credential path instead of pointing at `models.json`.** For a provider pi ships built in (openrouter, anthropic, openai, …), the fix for an unresolved model is a credential — after which pi fetches that provider's catalog, with real pricing and context limits, on its own. Both error messages instead named `~/.pi/agent/models.json` as the remedy, which is wrong for exactly that case and demonstrably led users to hand-write `models[]` entries. Because such an entry **replaces** pi's catalog entry wholesale rather than merging into it (`modelOverrides` is the merging mechanism), doing so silently zeroed out the model's pricing and capped its context and output windows. The messages now name `/login`, `auth.json` and the provider env var first, scope `models.json` to genuinely custom or self-hosted providers, and warn about the replace-vs-merge distinction.
+- **A cost of exactly `$0.00` is now shown rather than omitted.** Cost is computed locally as tokens × the model's price table, never read off the wire, so a model whose table is all zeros bills tokens and reports zero indefinitely. Every display site gated on `cost > 0`, which made a misconfigured price table indistinguishable from "nothing reported yet" — and on the CLI progress line a falsy cost suppressed the **token count** as well, so the run appeared to consume nothing. Zero is also the honest figure for flat-rate plans and local models. `recordLlmUsage` additionally warns once per model when tokens are billed against an all-zero table, naming the usual cause.
+- **Session Metrics now actually reports cost.** The view has always advertised "API cost estimates", but `SessionStats` carried no cost field to show; it now aggregates and displays one.
+
+### Documentation
+- **`README.md` claimed the research agent has "no filesystem or shell access" and is "safe to point at anything".** The shell half is accurate; the filesystem half was not — `read` and `grep` are registered unconditionally and the researcher exclusion list (`bash`, `write`, `edit`, `repl`, `git`, `terminal`) never excluded them. `ARCHITECTURE.md` documented this correctly, so the README was the outlier — and it is the sentence a user relies on when deciding whether to run this against a sensitive directory. Corrected to what the code actually enforces: no shell, no writes, but reads and searches within the working directory.
+- **The `knowledge-config` example was an unquoted shell pipe.** `... knowledge-config set none|project|global` sat inside a block `SKILL.md` explicitly instructs the agent to run on the user's behalf; pasted literally, bash executes `set none` and pipes into two "command not found" lines — so a user asking to *enable* the store would have it silently *disabled*. Now a `<none|project|global>` placeholder, fixed in all four copies.
+- **Exit-code documentation gaps.** `75` (at capacity) — 1.1.0's headline exit code — was missing from the CLI's own `--help`. And `78` from `knowledge` covers two very different conditions (store deliberately disabled vs. missing credentials) while `SKILL.md` documented only the first, telling agents to stay silent and continue on what is actually a hard configuration failure. Both surfaces now distinguish them.
+- **`docs/SDK.md` recommended a loader recipe that cannot work.** It suggested `node --experimental-transform-types your-script.ts` for consuming the TypeScript entrypoint; Node refuses to strip *or* transform TypeScript under `node_modules`, failing with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. A loader (`tsx`/`ts-node`) or the pi host is mandatory, and the limitation is now stated.
+
+## [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

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. |
@@ -216,7 +218,7 @@ set the knowledge-store mode per directory directly:
 
 ```sh
 pi-research knowledge-config                       # show the mode here and where it comes from
-pi-research knowledge-config set none|project|global
+pi-research knowledge-config set <none|project|global>   # pick ONE value
 ```
 
 Under the agent skill you don't have to run this yourself — you ask the agent (e.g. "disable the

package/docs/KNOWLEDGE-STORE.md

@@ -44,7 +44,7 @@ a project-scoped setting you can change per directory:
 | `none` | The store is disabled — nothing is read or written, the `research_knowledge_search` tool is not advertised to the agent, and `/knowledge-store` is unavailable. Re-enabling needs no restart (see [PI-EXTENSION.md](PI-EXTENSION.md) for the registration mechanics). |
 
 Change the mode for the current directory with the `/research-config` TUI (Knowledge Mode)
-in the pi extension, or with `pi-research knowledge-config set none|project|global` on the
+in the pi extension, or with `pi-research knowledge-config set <none|project|global>` (pick one value) on the
 standalone CLI. The setting persists to the per-directory project registry — see
 [CONFIGURATION.md](CONFIGURATION.md) for the full precedence chain. The change applies on
 the next run — no restart.

package/docs/SDK.md

@@ -33,13 +33,16 @@ global file entirely and run purely from defaults + `process.env` + `options.con
 > `enum` and constructor parameter properties, which Node's strip-only mode
 > (`--experimental-strip-types`, the default since Node 23.6) rejects with
 > `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`. Use one of:
-> - the pi host, which loads it natively;
-> - **`node --experimental-transform-types your-script.ts`** — must be passed
->   explicitly; full transform is not the default on any current Node release;
+> - the pi host, which loads it natively (via `jiti`);
 > - a loader such as `tsx` or `ts-node`.
 >
-> Plain `node script.js` doing `require('@lincoln504/pi-research/sdk')`, or
-> `--experimental-strip-types`, will not work. (`engines.node` is `>=22.19.0`.)
+> **Bare Node cannot load it at all, with any flag.** Node refuses to strip or
+> transform TypeScript that lives under `node_modules` — as an installed
+> dependency's source does — failing with
+> `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. That applies to
+> `--experimental-transform-types` exactly as it does to
+> `--experimental-strip-types`, so neither flag helps here; a loader (or the pi
+> host) is mandatory. (`engines.node` is `>=22.19.0`.)
 
 ```typescript
 import {
@@ -85,6 +88,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.12",
+  "version": "1.1.2",
   "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,

package/scripts/build.cjs

@@ -106,13 +106,31 @@ const TARGETS = {
     copyWebGpuProbe();
     copyPrompts();
   },
-  skill: () =>
-    esbuild.build({
+  skill: () => {
+    const entry = p('skills', 'pi-research', 'scripts', 'run.ts');
+    const outfile = p('skills', 'pi-research', 'scripts', 'run.mjs');
+    // The published package ships the BUILT run.mjs and deliberately excludes its
+    // run.ts source (package.json "files": "!skills/pi-research/scripts/run.ts"),
+    // yet it also ships prepare.cjs + build.cjs — and `prepare` runs `build.cjs all`.
+    // On any install that executes prepare against the shipped tree (npm install
+    // <dir>, file:, npm link, pi install <dir>) this target had no entry point and
+    // aborted the whole install with "Could not resolve run.ts". Registry .tgz and
+    // npx installs were unaffected only because prepare does not run there.
+    // Nothing to do when the artifact is already present and its source is not.
+    if (!fs.existsSync(entry)) {
+      if (fs.existsSync(outfile)) {
+        console.log('[build] skill: run.ts absent and run.mjs already built (published tree) — skipping');
+        return Promise.resolve();
+      }
+      throw new Error(`[build] skill: neither ${entry} nor a prebuilt ${outfile} exists`);
+    }
+    return esbuild.build({
       ...COMMON,
-      entryPoints: [p('skills', 'pi-research', 'scripts', 'run.ts')],
-      outfile: p('skills', 'pi-research', 'scripts', 'run.mjs'),
+      entryPoints: [entry],
+      outfile,
       banner: { js: SHEBANG },
-    }),
+    });
+  },
 };
 
 // The cli target's copyThreadWorker step depends on the worker output existing,

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.12", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.1.2", "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
 
@@ -55,8 +63,9 @@ node "<SKILL_DIR>/scripts/run.mjs" status    [--json]
 | Exit | Meaning | Action |
 |------|---------|--------|
 | `0` | Success | Read stdout; cite sources; relay any "saved to: <path>" line. |
-| `78` on `knowledge` | Store disabled/unconfigured | Silent; proceed to `research`. |
+| `78` on `knowledge` | Two cases — **read stderr to tell them apart.** | Says the store is **disabled**: silent; proceed to `research`. Mentions **credentials/model/API key**: this is the same hard config failure as `78` on `research` — **stop and relay full stderr**; don't silently continue, `research` will fail the same way. |
 | `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. |
 
@@ -72,7 +81,7 @@ the new setting. Check the current one first if useful:
 
 ```
 node "<SKILL_DIR>/scripts/run.mjs" knowledge-config                    # current mode + where it's set
-node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set none|project|global
+node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set <none|project|global>   # pick ONE value
 ```
 
 The change applies to the current directory on the next run. Never change it unprompted.

package/skills/pi-research/references/configuration.md

@@ -52,7 +52,7 @@ shared store — the default), `project` (scoped to the current directory), or `
 
 ```sh
 node "<SKILL_DIR>/scripts/run.mjs" knowledge-config                     # current mode + its source
-node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set none|project|global
+node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set <none|project|global>   # pick ONE value
 ```
 
 `set` persists to the per-directory project registry (`~/.pi/research/state/

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;
@@ -123,9 +137,19 @@ function makeProgressObserver(): HeadlessObserverOptions {
         case 'evaluation_decision':
           toStderr(`  • evaluator: ${data?.action}\n`);
           break;
-        case 'tokens_consumed':
-          if (data?.cost) toStderr(`  • tokens: ${data?.tokens ?? 0} ($${Number(data.cost).toFixed(4)})\n`);
+        case 'tokens_consumed': {
+          // A truthiness check on cost used to gate this whole line, so a model with
+          // an all-zero price table suppressed the TOKEN count as well — the run
+          // looked like it consumed nothing. Tokens stand on their own; cost is
+          // appended whenever it is a number, including 0.
+          const consumed = Number(data?.tokens ?? 0);
+          const costVal = typeof data?.cost === 'number' ? data.cost : undefined;
+          if (consumed > 0 || costVal !== undefined) {
+            const costPart = costVal === undefined ? '' : ` ($${costVal.toFixed(4)})`;
+            toStderr(`  • tokens: ${consumed}${costPart}\n`);
+          }
           break;
+        }
         case 'complete':
           toStderr(`  • complete (${data?.result?.length ?? 0} chars)\n`);
           break;
@@ -829,9 +853,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 +880,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 +900,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`);
@@ -978,7 +1026,9 @@ CONFIGURE
 EXIT CODES
   0  success
   64 bad arguments
+  75 at capacity — every concurrent run slot is busy; nothing is broken, retry later
   78 not configured — message prints the exact locations to fix
+     (on \`knowledge\`, also returned when the store is deliberately disabled)
   70 runtime error (network, provider, internal)
 `;
 }

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/llm/model-registry-factory.ts

@@ -219,6 +219,13 @@ export function constructMinimalModel(provider: string, modelId: string, _apiKey
     baseUrl: '', // Provider-specific base URLs are handled by pi-ai internal registry
     reasoning: false,
     input: ['text'],
+    // No catalog is available on this path, so there is no price data and no real
+    // context/output ceiling to read. The zeros below are "unknown", NOT "free":
+    // cost reporting for this model will read $0.00 (see warnIfUnpriced in
+    // utils/llm-usage.ts), and the window figures are conservative guesses, not the
+    // model's true limits — so docs/CONFIGURATION.md's "clamped to the model's real
+    // ceiling" guarantee does not hold here. Anyone relying on accurate cost or the
+    // full context window should give pi a credential so it can fetch the real catalog.
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 128_000,
     maxTokens: 32_768,
@@ -253,7 +260,7 @@ export function resolveModel(registry: ModelRegistry, modelSpec?: string, provid
         return constructMinimalModel(prov, modelId, apiKey);
       }
       
-      throw new Error(`Model "${modelSpec}" not found in pi's configured model registry. Check ${path.join(getAgentDir(), 'models.json')}.`);
+      throw new Error(buildModelNotFoundMessage(modelSpec));
     }
     
     // Validate format: must contain a slash OR be found as a bare model ID.
@@ -306,11 +313,41 @@ export function resolveModel(registry: ModelRegistry, modelSpec?: string, provid
     return constructMinimalModel(provider, modelSpec, apiKey);
   }
 
-  throw new Error(
-    `No LLM model available. Please configure your model registry (${path.join(getAgentDir(), 'models.json')}) or provide an explicit apiKey.`,
+  throw new Error(buildNoModelAvailableMessage());
+}
+
+/**
+ * Credential-first guidance for model-resolution failures.
+ *
+ * These messages used to say only "Check ~/.pi/agent/models.json", which is the
+ * WRONG remedy for a provider pi ships built in: the fix there is a credential,
+ * after which pi fetches the provider's catalog (with real pricing and context
+ * limits) on its own. Following the old advice, users hand-wrote `models[]`
+ * entries — and because such an entry REPLACES pi's catalog entry wholesale
+ * rather than merging into it, that silently zeroed out pricing and capped
+ * context/output windows. Lead with the credential path; scope models.json to
+ * genuinely custom providers; name `modelOverrides` for single-field tweaks.
+ */
+function credentialGuidance(): string {
+  const agentDir = getAgentDir();
+  return (
+    `  • Provider pi supports built-in (openrouter, anthropic, openai, …): add a credential — run \`pi\` and use /login, ` +
+    `set the provider's API-key environment variable, or add it to ${path.join(agentDir, 'auth.json')}. ` +
+    `pi then fetches that provider's model catalog automatically.\n` +
+    `  • Custom or self-hosted provider (Ollama, vLLM, a proxy): declare it in ${path.join(agentDir, 'models.json')}.\n` +
+    `    Note: a models.json entry REPLACES pi's catalog entry for the same model id, discarding its pricing and\n` +
+    `    context/output limits. To adjust a single field of a built-in model, use "modelOverrides" instead — it merges.`
   );
 }
 
+export function buildModelNotFoundMessage(modelSpec: string): string {
+  return `Model "${modelSpec}" not found in pi's model registry.\n${credentialGuidance()}`;
+}
+
+export function buildNoModelAvailableMessage(): string {
+  return `No LLM model available.\n${credentialGuidance()}\n  • Or pass an explicit apiKey.`;
+}
+
 /**
  * Read the user's provider order from ~/.pi/agent/models.json.
  * Returns provider keys in document (insertion) order, or [] when the file is

package/src/core/llm/research-model-resolver.ts

@@ -9,7 +9,7 @@ import { type Model } from '@earendil-works/pi-ai';
 import { type ModelRegistry } from '@earendil-works/pi-coding-agent';
 import { getConfig } from '../../config.ts';
 import { logger } from '../../logger.ts';
-import { pickPreferredAvailable, readModelsJsonProviderOrder, safeGetAll, safeGetAvailable } from './model-registry-factory.ts';
+import { buildNoModelAvailableMessage, pickPreferredAvailable, readModelsJsonProviderOrder, safeGetAll, safeGetAvailable } from './model-registry-factory.ts';
 
 /**
  * Resolve the research model with standardized priority:
@@ -87,5 +87,5 @@ export function resolveResearchModel(options: {
     return pickPreferredAvailable(anyModel, readModelsJsonProviderOrder()) as Model<any>;
   }
 
-  throw new Error('No LLM model available for research. Please configure your model registry (~/.pi/agent/models.json).');
+  throw new Error(buildNoModelAvailableMessage());
 }

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

@@ -90,9 +90,18 @@ export function isServerDrainingError(error: unknown): boolean {
 
 /**
  * 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;
@@ -100,7 +109,13 @@ export function isPoolShutdownError(error: unknown): boolean {
     return typeof err.message === 'string' && (
         err.message.includes('Worker pool is shutting down') ||
         err.message.includes('Cannot execute a task on destroying pool') ||
-        err.message.includes('destroying pool')
+        err.message.includes('destroying pool') ||
+        // worker-pool-manager throws this when auto-recovery is still swapping the
+        // pool. Its own text says "please retry", but until it was listed here no
+        // classifier matched it, so the first attempt rethrew instead of retrying —
+        // and auto-recovery fires only after 3 consecutive worker failures, i.e.
+        // exactly when a burst of tasks is in flight and would all die together.
+        err.message.includes('Worker pool is being reset')
     );
 }