@lincoln504/pi-research 1.0.0 → 1.0.2

package/README.md

@@ -52,36 +52,21 @@ Ask in natural language — the tool understands the depth needed:
 - An LLM with a 100k+ context window (bring your own key)
 - Internet access
 - A residential IP address — search, scraping, and YouTube transcripts all rely on a residential connection. A datacenter/VPS/cloud IP gets bot-blocked by the providers these features depend on.
-- The pi runtime the engine builds on — `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui`. The pi extension uses the host's copies; the standalone CLI / agent skill install them as dependencies (`@earendil-works/pi-coding-agent` is the dependency the launcher checks is resolvable, and it will tell you to reinstall if a partial install leaves it out).
+- The pi runtime the engine builds on — `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui`. The pi extension uses the host's copies; the standalone CLI / agent skill install them as dependencies.
 - Cloudflare and similar anti-automation systems block scraping on some sites, so runs will identify sources they cannot reach. pi-research compensates with volume: the search tool rapidly pulls a large set of results off free DuckDuckGo, giving the model a wide selection of reachable content to cite.
 
 ### Install
 
-Install the front-end you want.
-
-pi extension
-
 ```bash
 pi install npm:@lincoln504/pi-research
 ```
 
-Standalone CLI / agent skill
-
-```bash
-npm install -g @lincoln504/pi-research
-```
+See [Agent skill](docs/AGENT-SKILL.md) or [SDK](docs/SDK.md) for standalone (no pi extension) installation.
 
 Then configure a model and key — set `PI_RESEARCH_MODEL` (e.g. `openai/gpt-4o`) plus `PI_RESEARCH_API_KEY` and `PI_RESEARCH_PROVIDER`, either as environment variables or in `~/.pi/research/config.env`. See [Configuration](docs/CONFIGURATION.md). (The pi extension needs no key — it uses pi's own auth.)
 
-See [Agent skill](docs/AGENT-SKILL.md) for details.
-
 The first install pulls the stealth browser engine, which takes a few minutes.
 
-On Windows, run the CLI from `cmd` or use `pi-research.cmd` — stock PowerShell
-execution policy (`Restricted`) blocks npm's `.ps1` shims with a "running
-scripts is disabled" error. Alternatively run
-`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once.
-
 ### Stability (v1.x.x)
 
 v0.1.13 (April 2026) was the last release before a rebuild against current pi APIs

package/dist/cli.mjs

@@ -20166,7 +20166,8 @@ ${prompt}`);
           const msg2 = `Researcher ${id} (${researcherConfig.name}) timed out after ${config.RESEARCHER_TIMEOUT_MS}ms`;
           session.abort().catch((err) => {
             logger.warn("[ResearcherExecutor] Failed to abort timed-out researcher session:", err);
-          }).finally(() => reject(new Error(msg2)));
+          });
+          reject(new Error(msg2));
         }, config.RESEARCHER_TIMEOUT_MS);
       });
       let abortCleanup;
@@ -20248,9 +20249,18 @@ ${responseText}`);
       }
     } finally {
       subscription();
-      await session.abort().catch((err) => {
-        logger.warn(`[ResearcherExecutor] Failed to abort researcher session ${id}:`, err);
-      });
+      await Promise.race([
+        session.abort().catch((err) => {
+          logger.warn(`[ResearcherExecutor] Failed to abort researcher session ${id}:`, err);
+        }),
+        new Promise((resolve8) => {
+          const t = setTimeout(() => {
+            logger.warn(`[ResearcherExecutor] Researcher ${id} session abort did not settle within 10s; continuing cleanup`);
+            resolve8();
+          }, 1e4);
+          t.unref?.();
+        })
+      ]);
       sessionService?.unregisterSession(researchId, id);
       if (ctx.mode !== "tui" && ctx.hasUI && typeof ctx.ui.setHiddenThinkingLabel === "function") {
         ctx.ui.setHiddenThinkingLabel();
@@ -20526,7 +20536,8 @@ ${prompt}`);
             const msg2 = `Quick research timed out after ${this.config.RESEARCHER_TIMEOUT_MS}ms`;
             session.abort().catch((err) => {
               logger.warn("[QuickOrchestrator] Failed to abort timed-out session:", err);
-            }).finally(() => reject(new Error(msg2)));
+            });
+            reject(new Error(msg2));
           }, this.config.RESEARCHER_TIMEOUT_MS);
         });
         let abortCleanup;
@@ -22858,6 +22869,135 @@ change the machine-wide default: set PI_RESEARCH_KNOWLEDGE_STORE_MODE=<mode> in
   );
   return EXIT.OK;
 }
+async function cmdSkill(s) {
+  const {
+    installSkill: installSkill2,
+    uninstallSkill: uninstallSkill2,
+    skillInstallCandidates: skillInstallCandidates2,
+    skillUninstallCandidates: skillUninstallCandidates2,
+    detectHarnesses: detectHarnesses2,
+    SKILL_AGENT_TARGETS: SKILL_AGENT_TARGETS2
+  } = await Promise.resolve().then(() => (init_skill_installer(), skill_installer_exports));
+  const isTarget2 = (id) => SKILL_AGENT_TARGETS2.includes(id);
+  if (s.action === "status") {
+    const agents = detectHarnesses2().filter((d) => isTarget2(d.id));
+    if (s.json) {
+      toStdout(pretty({
+        command: "skill",
+        action: "status",
+        agents: agents.map((d) => ({ id: d.id, label: d.label, present: d.present, installed: d.installed, path: d.absSkillPath }))
+      }));
+      return EXIT.OK;
+    }
+    toStdout(`pi-research agent skill \u2014 install status
+
+`);
+    for (const d of agents) {
+      const state = !d.present ? "agent not detected" : d.installed === "none" ? "not installed" : d.installed === "foreign" ? "a different skill occupies this slot \u2014 left untouched" : `installed (${d.installed === "owned-copy" ? "copy" : "symlink"})`;
+      const loc = d.installed === "owned-symlink" || d.installed === "owned-copy" ? `  \u2192 ${d.absSkillPath}` : "";
+      toStdout(`  ${d.label.padEnd(18)} ${state}${loc}
+`);
+    }
+    toStdout(`
+install:   ${BINARY_NAME} skill install
+uninstall: ${BINARY_NAME} skill uninstall
+`);
+    return EXIT.OK;
+  }
+  if (s.action === "install") {
+    const candidates2 = skillInstallCandidates2();
+    if (candidates2.length === 0) {
+      const note = "No supported coding agents detected under $HOME (looked for Claude, OpenAI Codex CLI, OpenClaw). Set one up first, then re-run.";
+      if (s.json) {
+        toStdout(pretty({ command: "skill", action: "install", dryRun: !!s.dryRun, results: [], note }));
+        return EXIT.OK;
+      }
+      toStderr(`
+[pi-research] ${note}
+`);
+      return EXIT.OK;
+    }
+    let results2;
+    try {
+      results2 = installSkill2(candidates2.map((d) => d.id), { dryRun: s.dryRun, copy: s.copy });
+    } catch (err) {
+      return reportError(err, "skill install", s.json);
+    }
+    if (s.json) {
+      toStdout(pretty({ command: "skill", action: "install", dryRun: !!s.dryRun, results: results2 }));
+    } else {
+      toStdout(`pi-research agent skill \u2014 ${s.dryRun ? "install (dry run)" : "install"}
+
+`);
+      for (const r of results2) toStdout(`  ${r.tool.padEnd(10)} ${describeInstall(r)}
+`);
+      toStdout(`
+The skill activates automatically \u2014 ask the agent to research something.
+`);
+    }
+    return results2.some((r) => r.status === "error") ? EXIT.SOFTWARE : EXIT.OK;
+  }
+  const candidates = skillUninstallCandidates2();
+  if (candidates.length === 0) {
+    const note = "No pi-research skill installs found to remove.";
+    if (s.json) {
+      toStdout(pretty({ command: "skill", action: "uninstall", dryRun: !!s.dryRun, results: [], note }));
+      return EXIT.OK;
+    }
+    toStdout(`
+[pi-research] ${note}
+`);
+    return EXIT.OK;
+  }
+  let results;
+  try {
+    results = uninstallSkill2(candidates.map((d) => d.id), { dryRun: s.dryRun });
+  } catch (err) {
+    return reportError(err, "skill uninstall", s.json);
+  }
+  if (s.json) {
+    toStdout(pretty({ command: "skill", action: "uninstall", dryRun: !!s.dryRun, results }));
+  } else {
+    toStdout(`pi-research agent skill \u2014 ${s.dryRun ? "uninstall (dry run)" : "uninstall"}
+
+`);
+    for (const r of results) toStdout(`  ${r.tool.padEnd(10)} ${describeUninstall(r)}
+`);
+  }
+  return results.some((r) => r.status === "error") ? EXIT.SOFTWARE : EXIT.OK;
+}
+function describeInstall(r) {
+  switch (r.status) {
+    case "installed":
+      return `${r.type === "copy" ? "copied" : "symlinked"} \u2192 ${r.path}`;
+    case "already-installed":
+      return `already installed \u2192 ${r.path}`;
+    case "planned":
+      return `would ${r.type === "copy" ? "copy" : "symlink"} \u2192 ${r.path}`;
+    case "skipped-foreign":
+      return "a different skill occupies this slot \u2014 left untouched";
+    case "error":
+      return `failed: ${r.message ?? "unknown error"}`;
+    default:
+      return r.status;
+  }
+}
+function describeUninstall(r) {
+  switch (r.status) {
+    case "removed":
+      return `removed \u2192 ${r.path}`;
+    case "planned":
+      return `would remove \u2192 ${r.path}`;
+    case "not-present":
+      return "nothing installed";
+    case "skipped-foreign":
+      return "not ours \u2014 left untouched";
+    case "error":
+      return `failed: ${r.message ?? "unknown error"}`;
+    default:
+      return r.status;
+  }
+}
 function reportError(err, what, json) {
   const msg2 = err instanceof Error ? err.message : String(err);
   const lower = msg2.toLowerCase();
@@ -22940,6 +23080,12 @@ COMMANDS
     --config <path>              Use this config file instead of the base config.env.
     --json                       Emit a JSON object.
 
+  skill [status]                 Show where the agent skill is installed across your coding agents.
+  skill install                  Install the skill into detected agents (Claude, Codex, OpenClaw).
+    --copy | --dry-run | --json  Copy instead of symlink; plan only; JSON output.
+  skill uninstall                Remove the skill from agents where pi-research installed it.
+    --dry-run | --json           Plan only; JSON output.
+
   help, --help, -h               Show this help.
 
 CONFIGURE
@@ -23055,6 +23201,33 @@ function parseArgs(argv) {
     }
     throw new UsageError(`unknown knowledge-config action "${action}". Use: show | set <none|project|global>.`);
   }
+  if (cmd === "skill") {
+    let json = false;
+    let dryRun = false;
+    let copy = false;
+    const positional = [];
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === "--json") json = true;
+      else if (a === "--dry-run") dryRun = true;
+      else if (a === "--copy") copy = true;
+      else if (a?.startsWith("--")) {
+        throw new UsageError(`unknown option for skill: ${a}`);
+      } else if (a !== void 0) {
+        positional.push(a);
+      }
+    }
+    const action = positional[0] ?? "status";
+    if (action !== "install" && action !== "uninstall" && action !== "status") {
+      throw new UsageError(`unknown skill action "${action}". Use: status | install | uninstall.`);
+    }
+    if (positional.length > 1) {
+      throw new UsageError(`unexpected argument "${positional[1]}" after "skill ${action}".`);
+    }
+    out.command = "skill";
+    out.skill = { action, json, dryRun, copy };
+    return out;
+  }
   if (cmd === "research") {
     const r = { query: "" };
     const initialLinks = [];
@@ -23178,6 +23351,8 @@ ${buildHelp()}`);
       return cmdKnowledge(parsed.knowledge.queries, parsed.knowledge.json);
     case "knowledge-config":
       return cmdKnowledgeConfig(parsed.knowledgeConfig);
+    case "skill":
+      return cmdSkill(parsed.skill);
     case "research":
       return cmdResearch(parsed.research);
     default:

package/docs/AGENT-SKILL.md

@@ -5,6 +5,29 @@ so any skills-compatible coding agent (Claude, OpenAI Codex CLI, OpenClaw, and
 others using the same `SKILL.md` directory model) can run web research through the
 pi-research software.
 
+### Install
+
+Already running the `pi` extension (`pi install npm:@lincoln504/pi-research`)? You
+already have the engine — install the skill into your other agents with
+`/research-config` → Install in External Agents (see [Installation flow](#installation-flow))
+and skip the rest.
+
+For standalone use without pi, install the engine globally, then link the skill into
+every coding agent detected on this machine:
+
+```bash
+npm install -g @lincoln504/pi-research   # the engine (puts `pi-research` on PATH)
+pi-research skill install                # link the skill into Claude, Codex, OpenClaw
+```
+
+`skill install` targets only agents already set up under `$HOME`, never overwrites a
+different skill in the slot, and records what it created so `pi-research skill uninstall`
+removes exactly that. Run `pi-research skill status` to see where it is installed.
+
+On Windows, run `pi-research` from `cmd` or use `pi-research.cmd`: PowerShell's default
+execution policy (`Restricted`) blocks npm's `.ps1` shims ("running scripts is
+disabled"); or run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once.
+
 ![Installing the research skill into external agents](media/05-agent-skill.gif)
 
 ### How it works
@@ -16,7 +39,7 @@ agent
 run.mjs  —  zero-dep launcher (skills/pi-research/scripts/)
   │  locates the installed engine, or fails fast with guidance
   ▼
-pi-research engine  —  the SDK (dist/cli.mjs)
+pi-research engine  —  the CLI (dist/cli.mjs)
   │  init → run → shutdown
   ▼
 cited Markdown report  →  stdout  →  back to the agent
@@ -50,6 +73,11 @@ Install in External Agents. The installer:
    removes only its own links. Stale links are also garbage-collected on startup and
    on `npm uninstall`.
 
+Standalone (no pi extension). `pi-research skill install` and `pi-research skill uninstall`
+do exactly the same from the CLI — same agent detection, same manifest, same
+never-clobber-a-foreign-skill guarantee — for people who installed the engine with
+`npm install -g` and never open the interactive extension.
+
 **OpenClaw without `pi`**
 
 If you run OpenClaw but not the `pi` extension, register the skill with OpenClaw's

package/docs/ARCHITECTURE.md

@@ -301,7 +301,7 @@ Browser & scraping
 
 - [Camoufox](https://camoufox.com) — stealth Firefox (driven via [Playwright](https://playwright.dev)) for undetected search and scraping
 - [poolifier](https://github.com/poolifier/poolifier) — the worker-process pool behind the browser workers
-- [html-to-markdown](https://github.com/Goldziher/html-to-markdown) & [node-html-markdown](https://github.com/crosstype/node-html-markdown) — convert scraped HTML to Markdown
+- [html-to-markdown](https://github.com/kreuzberg-dev/html-to-markdown) — converts scraped HTML to Markdown (node-html-markdown serves as the pure-JS fallback)
 - `pdf-oxide-wasm` — PDF text extraction (Rust/WASM)
 
 Knowledge store & embeddings

package/docs/CONFIGURATION.md

@@ -75,7 +75,7 @@ Research
 | `PI_RESEARCH_RETRY_DELAY_MS` | `2000` | 100–10000 | Base delay between retries. |
 | `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_MODEL` | _(session model)_ | — | Model override for researcher sub-agents (deep and quick) and knowledge synthesis. The coordinator and evaluator keep using the session model. Accepts `provider/id` or a bare model id. |
+| `PI_RESEARCH_MODEL` | _(session model)_ | — | Model override for researcher sub-agents (deep and quick) and knowledge synthesis. In the pi extension the coordinator and evaluator keep using the session model; on the standalone CLI/SDK, when no `--model`/`model` option is given, this also selects the session model itself. 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. |
 | `PI_RESEARCH_REPORT_EXPORT_DIR` | _(smart cwd)_ | — | Pin exported reports to a fixed directory, bypassing the cwd-relative resolution. Useful for the agent skill, which runs from the host agent's arbitrary directory. |

package/docs/KNOWLEDGE-STORE.md

@@ -41,15 +41,13 @@ a project-scoped setting you can change per directory:
 |------|----------|
 | `global` (default) | One store shared across every directory. A finding cached in one project is retrievable from any other. |
 | `project` | Findings are scoped to the working directory they were created in; only that directory retrieves them. |
-| `none` | The store is disabled — no data is read or written. The `research_knowledge_search` tool stays registered (so re-enabling the mode later needs no pi restart) but is not advertised to the agent: its prompt guidance is stripped, and any direct call returns a "knowledge store is disabled" result. The `/knowledge-store` command is unavailable. |
+| `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
-standalone CLI (`pi-research knowledge-config` shows the current mode and its source). Under
-the agent skill you don't have to run anything — you ask the agent to change it and it runs that
-command for you. All persist to the per-directory project registry; a per-directory value
-overrides a machine-wide `PI_RESEARCH_KNOWLEDGE_STORE_MODE` in `config.env`, and a real
-environment variable overrides everything. The change applies on the next run — no restart.
+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.
 
 All scopes share one physical LanceDB directory; project vs. global rows are
 distinguished by columns (a normalized workspace path and a global flag) and filtered

package/docs/SDK.md

@@ -4,6 +4,15 @@ The programmatic SDK for scripts, CI, and custom tooling. For configuration —
 layering model, the TUI settings, and every environment variable — see
 [CONFIGURATION.md](CONFIGURATION.md).
 
+### Install
+
+Install it as a dependency of your project so the imports resolve — even if you already
+run the `pi` extension, which keeps its own private copy your scripts can't import:
+
+```bash
+npm install @lincoln504/pi-research
+```
+
 `src/sdk.ts` is a library for scripts, CI, and custom tooling. It is configured
 from code, not from a global overlay file — there is no `sdk.env`. It reads the
 base `~/.pi/research/config.env` as a baseline, and everything is

package/docs/THIRD-PARTY-NOTICES.md

@@ -6,8 +6,9 @@ license covers this project's own source code only.
 This package depends on third-party software distributed under its own license
 terms. Dependencies are resolved and installed by npm at install time (by
 reference); they are **not** bundled into this package's published artifacts
-(`dist/*` is built with esbuild `--packages=external`, so no third-party code is
-inlined).
+(the esbuild-bundled entry points — `dist/cli.mjs`, `dist/thread-worker.mjs` — are
+built with `--packages=external`, and the remaining `dist/` files are copied
+first-party sources, so no third-party code is inlined).
 
 ### Notable dependency licensing
 
@@ -15,7 +16,7 @@ camoufox-js / Camoufox browser
 
 The `camoufox-js` npm package itself is licensed under **MPL-2.0** (file-level
 copyleft). It is resolved at install time and **not bundled** into this package's
-artifacts (`dist/*` is built `--packages=external`), so no MPL-covered source is
+artifacts (the bundled entry points are built `--packages=external`), so no MPL-covered source is
 combined into or redistributed by this MIT package. It is used in-process only to
 configure and launch the Camoufox (Firefox-fork) browser **binary as a separate
 operating-system process**, which this package then drives over the Playwright/CDP
@@ -27,7 +28,7 @@ ua-parser-js
 `ua-parser-js` 2.x is licensed under AGPL-3.0-or-later. To keep this MIT-licensed
 package free of AGPL-licensed code in its dependency tree, `package.json`
 `overrides` pins `ua-parser-js` to the `1.x` line, which is MIT-licensed. The
-1.x and 2.x APIs are compatible for the only surface our transitive dependency
+1.x and 2.x APIs are compatible for the only surface our direct dependency
 (`camoufox-js`) uses, and the pin is behavior-neutral for this package's usage
 (no custom `navigator.userAgent`/`fingerprint` is passed to Camoufox).
 
@@ -48,7 +49,8 @@ sharp / @img/sharp-libvips (via @huggingface/transformers)
 in turn installs prebuilt `@img/sharp-libvips-*` native packages licensed under
 **LGPL-3.0-or-later**. These are platform-specific shared libraries linked
 **dynamically** at runtime and resolved at install time; no LGPL code is statically
-linked into or bundled with this package (`dist/*` is built `--packages=external`).
+linked into or bundled with this package (the bundled entry points are built
+`--packages=external`).
 Dynamic linkage of an unmodified LGPL library from an MIT-licensed program is
 permitted by the LGPL. The image path is only exercised by the embedding/knowledge
 stack; text-only research does not load it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.0.0",
+  "version": "1.0.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/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.0", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.0.2", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/src/cli.ts

@@ -598,6 +598,120 @@ async function cmdKnowledgeConfig(kc: NonNullable<ParsedArgs['knowledgeConfig']>
   return EXIT.OK;
 }
 
+// ---------------------------------------------------------------------------
+// skill subcommand
+// ---------------------------------------------------------------------------
+
+/**
+ * skill subcommand: install / uninstall / inspect the pi-research Agent Skill in
+ * the coding agents on this machine (Claude, OpenAI Codex CLI, OpenClaw). This is
+ * the CLI equivalent of the pi extension's `/research-config → Install in External
+ * Agents`, for standalone users who installed the engine with `npm install -g` and
+ * never open the interactive pi extension. It drives the SAME skill-installer
+ * library the TUI uses, so the guarantees are identical: only agents whose config
+ * dir already exists are targeted, a foreign skill already in the slot is never
+ * clobbered, and every link/copy is manifest-tracked so uninstall removes exactly
+ * what was created.
+ */
+async function cmdSkill(s: NonNullable<ParsedArgs['skill']>): Promise<number> {
+  const {
+    installSkill, uninstallSkill, skillInstallCandidates, skillUninstallCandidates,
+    detectHarnesses, SKILL_AGENT_TARGETS,
+  } = await import('./skill-install/skill-installer.ts');
+  const isTarget = (id: string): boolean =>
+    (SKILL_AGENT_TARGETS as readonly string[]).includes(id);
+
+  if (s.action === 'status') {
+    const agents = detectHarnesses().filter((d) => isTarget(d.id));
+    if (s.json) {
+      toStdout(pretty({
+        command: 'skill', action: 'status',
+        agents: agents.map((d) => ({ id: d.id, label: d.label, present: d.present, installed: d.installed, path: d.absSkillPath })),
+      }));
+      return EXIT.OK;
+    }
+    toStdout(`pi-research agent skill — install status\n\n`);
+    for (const d of agents) {
+      const state = !d.present ? 'agent not detected'
+        : d.installed === 'none' ? 'not installed'
+        : d.installed === 'foreign' ? 'a different skill occupies this slot — left untouched'
+        : `installed (${d.installed === 'owned-copy' ? 'copy' : 'symlink'})`;
+      const loc = d.installed === 'owned-symlink' || d.installed === 'owned-copy' ? `  → ${d.absSkillPath}` : '';
+      toStdout(`  ${d.label.padEnd(18)} ${state}${loc}\n`);
+    }
+    toStdout(`\ninstall:   ${BINARY_NAME} skill install\nuninstall: ${BINARY_NAME} skill uninstall\n`);
+    return EXIT.OK;
+  }
+
+  if (s.action === 'install') {
+    const candidates = skillInstallCandidates();
+    if (candidates.length === 0) {
+      const note = 'No supported coding agents detected under $HOME (looked for Claude, OpenAI Codex CLI, OpenClaw). Set one up first, then re-run.';
+      if (s.json) { toStdout(pretty({ command: 'skill', action: 'install', dryRun: !!s.dryRun, results: [], note })); return EXIT.OK; }
+      toStderr(`\n[pi-research] ${note}\n`);
+      return EXIT.OK;
+    }
+    let results;
+    try {
+      results = installSkill(candidates.map((d) => d.id), { dryRun: s.dryRun, copy: s.copy });
+    } catch (err) {
+      return reportError(err, 'skill install', s.json);
+    }
+    if (s.json) {
+      toStdout(pretty({ command: 'skill', action: 'install', dryRun: !!s.dryRun, results }));
+    } else {
+      toStdout(`pi-research agent skill — ${s.dryRun ? 'install (dry run)' : 'install'}\n\n`);
+      for (const r of results) toStdout(`  ${r.tool.padEnd(10)} ${describeInstall(r)}\n`);
+      toStdout(`\nThe skill activates automatically — ask the agent to research something.\n`);
+    }
+    return results.some((r) => r.status === 'error') ? EXIT.SOFTWARE : EXIT.OK;
+  }
+
+  // uninstall
+  const candidates = skillUninstallCandidates();
+  if (candidates.length === 0) {
+    const note = 'No pi-research skill installs found to remove.';
+    if (s.json) { toStdout(pretty({ command: 'skill', action: 'uninstall', dryRun: !!s.dryRun, results: [], note })); return EXIT.OK; }
+    toStdout(`\n[pi-research] ${note}\n`);
+    return EXIT.OK;
+  }
+  let results;
+  try {
+    results = uninstallSkill(candidates.map((d) => d.id), { dryRun: s.dryRun });
+  } catch (err) {
+    return reportError(err, 'skill uninstall', s.json);
+  }
+  if (s.json) {
+    toStdout(pretty({ command: 'skill', action: 'uninstall', dryRun: !!s.dryRun, results }));
+  } else {
+    toStdout(`pi-research agent skill — ${s.dryRun ? 'uninstall (dry run)' : 'uninstall'}\n\n`);
+    for (const r of results) toStdout(`  ${r.tool.padEnd(10)} ${describeUninstall(r)}\n`);
+  }
+  return results.some((r) => r.status === 'error') ? EXIT.SOFTWARE : EXIT.OK;
+}
+
+function describeInstall(r: { status: string; type?: string; path: string; message?: string }): string {
+  switch (r.status) {
+    case 'installed': return `${r.type === 'copy' ? 'copied' : 'symlinked'} → ${r.path}`;
+    case 'already-installed': return `already installed → ${r.path}`;
+    case 'planned': return `would ${r.type === 'copy' ? 'copy' : 'symlink'} → ${r.path}`;
+    case 'skipped-foreign': return 'a different skill occupies this slot — left untouched';
+    case 'error': return `failed: ${r.message ?? 'unknown error'}`;
+    default: return r.status;
+  }
+}
+
+function describeUninstall(r: { status: string; path: string; message?: string }): string {
+  switch (r.status) {
+    case 'removed': return `removed → ${r.path}`;
+    case 'planned': return `would remove → ${r.path}`;
+    case 'not-present': return 'nothing installed';
+    case 'skipped-foreign': return 'not ours — left untouched';
+    case 'error': return `failed: ${r.message ?? 'unknown error'}`;
+    default: return r.status;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Error reporting & shutdown
 // ---------------------------------------------------------------------------
@@ -682,6 +796,7 @@ interface ParsedArgs {
   knowledge?: { queries: string[]; json?: boolean };
   knowledgeConfig?: { action: 'show' | 'set'; mode?: 'none' | 'project' | 'global'; json?: boolean };
   status?: { json?: boolean };
+  skill?: { action: 'install' | 'uninstall' | 'status'; json?: boolean; dryRun?: boolean; copy?: boolean };
   configPath?: string;
   json?: boolean;
 }
@@ -716,6 +831,12 @@ COMMANDS
     --config <path>              Use this config file instead of the base config.env.
     --json                       Emit a JSON object.
 
+  skill [status]                 Show where the agent skill is installed across your coding agents.
+  skill install                  Install the skill into detected agents (Claude, Codex, OpenClaw).
+    --copy | --dry-run | --json  Copy instead of symlink; plan only; JSON output.
+  skill uninstall                Remove the skill from agents where pi-research installed it.
+    --dry-run | --json           Plan only; JSON output.
+
   help, --help, -h               Show this help.
 
 CONFIGURE
@@ -839,6 +960,34 @@ export function parseArgs(argv: string[]): ParsedArgs {
     throw new UsageError(`unknown knowledge-config action "${action}". Use: show | set <none|project|global>.`);
   }
 
+  if (cmd === 'skill') {
+    let json = false;
+    let dryRun = false;
+    let copy = false;
+    const positional: string[] = [];
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === '--json') json = true;
+      else if (a === '--dry-run') dryRun = true;
+      else if (a === '--copy') copy = true;
+      else if (a?.startsWith('--')) {
+        throw new UsageError(`unknown option for skill: ${a}`);
+      } else if (a !== undefined) {
+        positional.push(a);
+      }
+    }
+    const action = positional[0] ?? 'status';
+    if (action !== 'install' && action !== 'uninstall' && action !== 'status') {
+      throw new UsageError(`unknown skill action "${action}". Use: status | install | uninstall.`);
+    }
+    if (positional.length > 1) {
+      throw new UsageError(`unexpected argument "${positional[1]}" after "skill ${action}".`);
+    }
+    out.command = 'skill';
+    out.skill = { action, json, dryRun, copy };
+    return out;
+  }
+
   if (cmd === 'research') {
     const r: ResearchArgs = { query: '' };
     const initialLinks: string[] = [];
@@ -1001,6 +1150,8 @@ async function main(argv: string[]): Promise<number> {
       return cmdKnowledge(parsed.knowledge!.queries, parsed.knowledge!.json);
     case 'knowledge-config':
       return cmdKnowledgeConfig(parsed.knowledgeConfig!);
+    case 'skill':
+      return cmdSkill(parsed.skill!);
     case 'research':
       return cmdResearch(parsed.research!);
     default:

package/src/orchestration/quick-research-orchestrator.ts

@@ -269,9 +269,13 @@ export class QuickResearchOrchestrator {
           const timeoutPromise = new Promise<void>((_, reject) => {
               timeoutId = setTimeout(() => {
                   const msg = `Quick research timed out after ${this.config.RESEARCHER_TIMEOUT_MS}ms`;
+                  // Reject FIRST, abort as fire-and-forget cleanup — see researcher-executor:
+                  // abort() awaits the stuck in-flight request, so gating the rejection on it
+                  // settling disables the timeout exactly when it is needed.
                   session.abort().catch((err) => {
                       logger.warn('[QuickOrchestrator] Failed to abort timed-out session:', err);
-                  }).finally(() => reject(new Error(msg)));
+                  });
+                  reject(new Error(msg));
               }, this.config.RESEARCHER_TIMEOUT_MS);
           });
 

package/src/orchestration/researcher-executor.ts

@@ -264,9 +264,14 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
       const timeoutPromise = new Promise<void>((_, reject) => {
         timeoutId = setTimeout(() => {
           const msg = `Researcher ${id} (${researcherConfig.name}) timed out after ${config.RESEARCHER_TIMEOUT_MS}ms`;
+          // Reject FIRST, abort as fire-and-forget cleanup: session.abort() awaits the
+          // in-flight request, which is the very thing that is stuck (e.g. a provider
+          // retry loop against an exhausted quota) — gating the rejection on it settling
+          // makes the timeout ineffective exactly when it is needed.
           session.abort().catch((err) => {
             logger.warn('[ResearcherExecutor] Failed to abort timed-out researcher session:', err);
-          }).finally(() => reject(new Error(msg)));
+          });
+          reject(new Error(msg));
         }, config.RESEARCHER_TIMEOUT_MS);
       });
 
@@ -375,9 +380,23 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
       }
     } finally {
       subscription();
-      await session.abort().catch((err) => {
-        logger.warn(`[ResearcherExecutor] Failed to abort researcher session ${id}:`, err);
-      });
+      // Bounded: after a timeout, session.abort() awaits the very in-flight request
+      // that is stuck (e.g. a provider retry loop against an exhausted quota) and may
+      // never settle — never let per-attempt cleanup hang the retry loop on it. The
+      // retry builds a fresh session; the abandoned abort keeps draining in the
+      // background and its session dies with the run's teardown.
+      await Promise.race([
+        session.abort().catch((err) => {
+          logger.warn(`[ResearcherExecutor] Failed to abort researcher session ${id}:`, err);
+        }),
+        new Promise<void>((resolve) => {
+          const t = setTimeout(() => {
+            logger.warn(`[ResearcherExecutor] Researcher ${id} session abort did not settle within 10s; continuing cleanup`);
+            resolve();
+          }, 10_000);
+          t.unref?.();
+        }),
+      ]);
       sessionService?.unregisterSession(researchId, id);
 
       // Restore the default thinking label now that the researcher is done.