@lincoln504/pi-research 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.2.0",
+  "version": "1.3.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,

package/scripts/cleanup.cjs

@@ -16,7 +16,7 @@
  */
 
 const { spawnSync } = require('child_process');
-const { rmSync, existsSync, lstatSync, readlinkSync, readFileSync, writeFileSync, unlinkSync } = require('fs');
+const { rmSync, existsSync, lstatSync, readdirSync, readlinkSync, readFileSync, writeFileSync, unlinkSync } = require('fs');
 const os = require('os');
 const path = require('path');
 
@@ -181,9 +181,71 @@ const rawDirName = process.env.PI_RESEARCH_CONFIG_DIR_NAME;
 const dirName = rawDirName && !rawDirName.includes('/') && !rawDirName.includes('\\') && rawDirName !== '.' && rawDirName !== '..'
   ? rawDirName
   : '.pi';
+
+/**
+ * Is this path PROVABLY equivalent to the layout the runtime itself would have
+ * constructed by default (`<dirName>/research`)? Wholesale rm of a state-dir
+ * override is only safe when the answer is yes: PI_RESEARCH_STATE_DIR may point
+ * at a SHARED directory, and rm'ing the override itself (unlike the cache sweep,
+ * which is namespaced via join(cacheHome, 'pi-research')) deleted everything the
+ * user kept beside our state.
+ *
+ * Deliberately NOT a bare "does any segment literally say pi-research" check —
+ * that matches naming convention, not ownership. A user is entirely free to
+ * point the override at, say, `~/agents-state/pi-research/` while keeping other
+ * tools' notes alongside it in the same folder (a natural way to organize
+ * several tools' state by name); a substring match would treat that shared
+ * folder as exclusively ours and wholesale-delete it. Only the exact default
+ * layout is something WE constructed and can therefore prove is ours.
+ */
+function isPiResearchNamespaced(p) {
+  const segs = p.split(/[\\/]+/).filter(Boolean);
+  for (let i = 0; i < segs.length - 1; i++) {
+    if (segs[i] === dirName && segs[i + 1] === 'research') return true;
+  }
+  return false;
+}
+
+/**
+ * Targeted state sweep for a non-namespaced override dir: delete ONLY the
+ * entries the runtime actually creates there and leave everything else — and
+ * the directory itself — untouched. The entry list mirrors the writers:
+ *   research-state.json + research-state-<hex>.tmp   (state-manager)
+ *   .locks/, backups/                                 (state-path-configuration)
+ *   project-settings.json + its .lock / .tmp. / .lock.stale- companions (config.ts)
+ *   research-run-slot-<i>.lock                        (research-run-semaphore)
+ * Best-effort; never throws.
+ */
+function removeOwnedStateEntries(dir) {
+  if (!dir || !existsSync(dir)) return;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+  const owned = (name) =>
+    name === 'research-state.json' ||
+    (name.startsWith('research-state-') && name.endsWith('.tmp')) ||
+    name === '.locks' ||
+    name === 'backups' ||
+    name === 'project-settings.json' ||
+    name.startsWith('project-settings.json.') ||
+    /^research-run-slot-\d+\.lock$/.test(name);
+  for (const name of entries) {
+    if (!owned(name)) continue;
+    try {
+      rmSync(path.join(dir, name), { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+    } catch (error) {
+      console.warn(`pi-research: could not remove state entry ${path.join(dir, name)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  console.log(`pi-research: removed pi-research state entries from ${dir} (directory preserved — not a pi-research-namespaced path).`);
+}
+
 const stateDir = stateOverride && path.isAbsolute(stateOverride)
   ? stateOverride
   : path.join(os.homedir(), dirName, 'research', 'state');
-removeOwnedScratchDir('state dir', stateDir);
+if (stateOverride && path.isAbsolute(stateOverride) && !isPiResearchNamespaced(stateDir)) {
+  removeOwnedStateEntries(stateDir);
+} else {
+  removeOwnedScratchDir('state dir', stateDir);
+}
 
 process.exit(0);

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

package/src/cleanup/research-cleanup.ts

@@ -82,11 +82,19 @@ export function createCleanupFunction(
     const { resetLogger } = await import('../logger.ts');
     resetLogger(researchId);
     
-    // FIX (#10): Clear session circuit breaker to prevent unbounded map growth.
+    // FIX (#10): Clear the session's browser circuit breaker to prevent unbounded
+    // map growth. Breakers are keyed by the plain researchId — createResearchRunId()
+    // generates it (`run-<8 hex>`) independently of piSessionId in
+    // research-tool-definition.ts, and tools/scrape.ts / tools/search.ts thread that
+    // same bare researchId into getBrowserCircuitBreaker() as BrowserTask.sessionId.
+    // (The `${piSessionId}-<8 hex>` shape this comment used to assume is produced
+    // only by generateSessionId(), which has no production caller.) This duplicates
+    // the clearSessionCircuitBreaker(targetId) call research-orchestration-service.ts
+    // already makes in its own finally block on the normal run-completion path; it
+    // matters here on paths where this cleanup runs alone, e.g. a throw before
+    // orchestrator.run() is ever reached.
     const { clearSessionCircuitBreaker } = await import('../infrastructure/browser/browser-error-utils.ts');
-    if (piSessionId) {
-      clearSessionCircuitBreaker(piSessionId);
-    }
+    clearSessionCircuitBreaker(researchId);
     
     const activePanels = getPiActivePanels(piSessionId);
     if (activePanels.length === 0) {

package/src/cli.ts

@@ -209,11 +209,24 @@ function makeProgressObserver(): HeadlessObserverOptions {
 // ---------------------------------------------------------------------------
 
 
+/**
+ * Thrown by bridgeConfigEnv when an EXPLICIT `--config` file is missing or
+ * unreadable. The ambient layers (config.env, cli.env) are optional overlays and
+ * stay tolerant — but a file the user named on this exact invocation silently
+ * not applying meant a typo'd `--config /path/ci.evn` ran on ambient config and
+ * reported success. main() maps this to EXIT.CONFIG for every command that
+ * accepts --config.
+ */
+export class ConfigFileError extends Error {}
+
 /**
  * Bridge the CLI's config files into process.env for keys not already set in the
  * real environment. Layers the base `~/.pi/research/config.env` then the CLI's
- * own `~/.pi/research/cli.env` overlay (overlay wins), or a `--config <path>`
- * override in place of the base.
+ * own `~/.pi/research/cli.env` overlay (overlay wins). With an explicit
+ * `--config <path>` the NAMED file layers on top of cli.env instead (highest
+ * file precedence); it does not replace the base — getConfig() still reads
+ * config.env as a lower-precedence file layer, so base keys the named file does
+ * not set still apply, and real environment variables always win.
  *
  * Why: auth values (PI_RESEARCH_API_KEY / _PROVIDER) are read directly from
  * process.env, NOT from the typed Config, so a key placed only in a config file
@@ -234,18 +247,37 @@ export function bridgeConfigEnv(explicitConfigPath?: string): { path: string; lo
   // default base, not the cli.env overlay). Project-scoped keys are only
   // bridged for these — see below.
   const fromExplicitBase = new Set<string>();
-  for (const filePath of [basePath, cliOverlayPath]) {
+  // Layer order decides the winner (later merge wins). Default: base then cli.env
+  // (overlay wins). With an explicit --config the NAMED file merges last: a file
+  // the user passed on this exact invocation is the most specific intent, and the
+  // ambient cli.env overlay silently overriding it re-created the very failure
+  // this bridge exists to fix (a key set in `--config ci.env` simply not applying).
+  const layers = explicitConfigPath !== undefined
+    ? [cliOverlayPath, basePath]
+    : [basePath, cliOverlayPath];
+  for (const filePath of layers) {
+    // Only the EXPLICIT --config file fails loudly (see ConfigFileError above);
+    // the ambient layers keep their missing/unreadable tolerance unchanged.
+    const isExplicit = explicitConfigPath !== undefined && filePath === basePath;
     try {
-      if (!fs.existsSync(filePath)) continue;
+      if (!fs.existsSync(filePath)) {
+        if (isExplicit) throw new ConfigFileError(`--config file not found: ${filePath}`);
+        continue;
+      }
       const parsed = parseDotEnv(fs.readFileSync(filePath, 'utf-8'));
       Object.assign(merged, parsed);
-      for (const k of Object.keys(parsed)) {
-        if (explicitConfigPath !== undefined && filePath === basePath) fromExplicitBase.add(k);
-        else fromExplicitBase.delete(k);
+      if (isExplicit) {
+        for (const k of Object.keys(parsed)) fromExplicitBase.add(k);
       }
       loaded = true;
-    } catch {
-      // ignore unreadable file; fall through to the next
+    } catch (err) {
+      if (err instanceof ConfigFileError) throw err;
+      if (isExplicit) {
+        throw new ConfigFileError(
+          `--config file could not be read: ${filePath} (${err instanceof Error ? err.message : String(err)})`,
+        );
+      }
+      // ignore unreadable ambient file; fall through to the next
     }
   }
   for (const [k, v] of Object.entries(merged)) {
@@ -514,7 +546,7 @@ interface ResearchArgs {
  * Research subcommand. Initializes the SDK, runs deep/quick research, prints the
  * markdown report to stdout, and always shuts down (even on failure).
  */
-async function cmdResearch(args: ResearchArgs): Promise<number> {
+export async function cmdResearch(args: ResearchArgs): Promise<number> {
   // Pre-flight with the per-run --model flag folded in: it satisfies the
   // model-required check and steers the provider-aware key detection.
   const det = await detectCredentials(args.model);
@@ -587,6 +619,18 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
       }
     }
 
+    // DeepResearchOrchestrator.run() does not throw on cancellation once at least
+    // one researcher has produced a report — it returns a fallback synthesis
+    // through its normal return path (synthesisService.hasReports branch; see
+    // deep-research-orchestrator.ts ~line 584-618). Left unchecked, a Ctrl-C
+    // mid-run that still yields a partial report would fall straight through to
+    // the unconditional success handling below and report ok:true / exit 0 —
+    // indistinguishable from an ordinary completed run. Mirrors reportError's
+    // own classification (same exitCodeForSignal formula) for the throwing case.
+    if (cancellationRequested) {
+      exit = cancellationSignal ? exitCodeForSignal(cancellationSignal) : EXIT.CANCELLED;
+    }
+
     if (args.json) {
       // Surface the internal quality/health signals that were previously log-only
       // (ISSUES-ANALYSIS-2026-07-09.md, Symptom 4): a caller reading only stdout/JSON
@@ -599,12 +643,20 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
         depth,
         report,
         ...(reportPath ? { reportPath } : {}),
+        // The run DID produce a real, complete report — ok stays true. `cancelled`
+        // is the qualifier a --json consumer needs to tell "user stopped it, here's
+        // what we had" apart from an ordinary finish.
+        ...(cancellationRequested ? { cancelled: true } : {}),
         ...(outcome ? { researchers: { planned: outcome.planned, launched: outcome.launched, succeeded: outcome.succeeded, failed: outcome.failed } } : {}),
         ...(errorReport && errorReport.totalErrors > 0 ? {
           trackedErrors: { total: errorReport.totalErrors, uniquePatterns: errorReport.uniquePatterns },
         } : {}),
       }));
     } else {
+      // Still a real, useful report — print it as before. The note goes to stderr
+      // (alongside the other lifecycle lines) so it never contaminates the report
+      // text a plain-mode caller pipes from stdout.
+      if (cancellationRequested) toStderr('[pi-research] run was cancelled — showing the partial report.\n');
       toStdout(report.endsWith('\n') ? report : report + '\n');
     }
   } catch (err) {
@@ -621,7 +673,7 @@ async function cmdResearch(args: ResearchArgs): Promise<number> {
  * result; `found: 'no'`/`'maybe'` tells the caller to follow up with live
  * research.
  */
-async function cmdKnowledge(queries: string[], json?: boolean): Promise<number> {
+export async function cmdKnowledge(queries: string[], json?: boolean): Promise<number> {
   const det = await detectCredentials();
   if (det.problem) {
     if (json) { toStdout(pretty({ ok: false, error: det.problem, exitCode: EXIT.CONFIG })); return EXIT.CONFIG; }
@@ -636,7 +688,7 @@ async function cmdKnowledge(queries: string[], json?: boolean): Promise<number>
       'Knowledge store is disabled (PI_RESEARCH_KNOWLEDGE_STORE_MODE=none). ' +
       "Set it to 'project' or 'global' to enable local knowledge search.\n\n" +
       `Configure in:\n  ${paths.configEnv}\n  ${paths.cliIfaceEnv}  (cli overlay)\n  or via PI_RESEARCH_KNOWLEDGE_STORE_MODE env var`;
-    if (json) toStdout(pretty({ found: 'no', text: msg, configured: false }));
+    if (json) toStdout(pretty({ ok: true, found: 'no', text: msg, configured: false }));
     else toStderr(`\n[pi-research] ${msg}\n`);
     return EXIT.CONFIG;
   }
@@ -660,7 +712,10 @@ async function cmdKnowledge(queries: string[], json?: boolean): Promise<number>
   }
 
   if (json) {
-    toStdout(pretty(result));
+    // `ok: true` makes `ok` a reliable success/failure discriminant across every
+    // knowledge JSON variant (disabled-store above, reportError's ok:false below,
+    // and this success shape) — additive only, every existing field is unchanged.
+    toStdout(pretty({ ok: true, ...result }));
   } else {
     toStdout((result.text.endsWith('\n') ? result.text : result.text + '\n'));
   }
@@ -715,51 +770,60 @@ async function cmdStatus(json?: boolean): Promise<number> {
  * setting on the user's behalf without hand-editing the locked registry JSON. A machine-wide
  * default is set instead via the PI_RESEARCH_KNOWLEDGE_STORE_MODE env var (per-run) or config.env.
  */
-async function cmdKnowledgeConfig(kc: NonNullable<ParsedArgs['knowledgeConfig']>): Promise<number> {
+export async function cmdKnowledgeConfig(kc: NonNullable<ParsedArgs['knowledgeConfig']>): Promise<number> {
   const cwd = process.cwd();
 
-  if (kc.action === 'set') {
-    const before = getConfig(cwd, 'cli').KNOWLEDGE_STORE_MODE;
-    const cfg = { ...getConfig(cwd, 'cli'), KNOWLEDGE_STORE_MODE: kc.mode! };
-    // Persist ONLY the knowledge-store mode for this directory — not the whole local-key set —
-    // so an unrelated per-directory DEFAULT_RESEARCH_DEPTH isn't frozen as a side effect.
-    saveConfig(cfg, 'local', cwd, ['PI_RESEARCH_KNOWLEDGE_STORE_MODE']); // per-directory registry write
-    resetConfig();                 // drop the cached config so `after` re-resolves from disk
+  // Wrapped like cmdKnowledge's own try/catch → reportError: without this, a
+  // thrown error (e.g. saveConfig failing to write the registry) escaped all the
+  // way to main()'s top-level catch, which ALWAYS writes plain text to stderr —
+  // silently breaking the documented `--json: Emit a JSON object` contract for
+  // this one subcommand.
+  try {
+    if (kc.action === 'set') {
+      const before = getConfig(cwd, 'cli').KNOWLEDGE_STORE_MODE;
+      const cfg = { ...getConfig(cwd, 'cli'), KNOWLEDGE_STORE_MODE: kc.mode! };
+      // Persist ONLY the knowledge-store mode for this directory — not the whole local-key set —
+      // so an unrelated per-directory DEFAULT_RESEARCH_DEPTH isn't frozen as a side effect.
+      saveConfig(cfg, 'local', cwd, ['PI_RESEARCH_KNOWLEDGE_STORE_MODE']); // per-directory registry write
+      resetConfig();                 // drop the cached config so `after` re-resolves from disk
+      const info = describeKnowledgeStoreMode(cwd, 'cli');
+      // The write always persists to the registry, but a real env var out-ranks the registry, so
+      // the EFFECTIVE mode can still differ from what was requested. Surface that instead of
+      // silently reporting a no-op.
+      const overridden = info.mode !== kc.mode;
+      if (kc.json) {
+        toStdout(pretty({ command: 'knowledge-config', action: 'set', requested: kc.mode, previous: before, saved: true, effectiveOverriddenBy: overridden ? info.origin : null, ...info, cwd }));
+        return EXIT.OK;
+      }
+      toStdout(
+        `knowledge store mode for this directory: ${before} -> ${kc.mode}  (saved per-directory)\n` +
+        `  scope:   ${kc.mode === 'none' ? 'disabled here' : kc.mode === 'project' ? 'this directory only' : 'shared across all directories'}\n` +
+        `  saved:   per-directory (${cwd})\n` +
+        `  db dir:  ${info.dbDir}\n` +
+        (overridden
+          ? `\nNOTE: the effective mode here is still '${info.mode}' because a higher-precedence ${info.origin} overrides it. Clear that source for this setting to take effect.\n`
+          : ''),
+      );
+      return EXIT.OK;
+    }
+
+    // show
     const info = describeKnowledgeStoreMode(cwd, 'cli');
-    // The write always persists to the registry, but a real env var out-ranks the registry, so
-    // the EFFECTIVE mode can still differ from what was requested. Surface that instead of
-    // silently reporting a no-op.
-    const overridden = info.mode !== kc.mode;
     if (kc.json) {
-      toStdout(pretty({ command: 'knowledge-config', action: 'set', requested: kc.mode, previous: before, saved: true, effectiveOverriddenBy: overridden ? info.origin : null, ...info, cwd }));
+      toStdout(pretty({ command: 'knowledge-config', action: 'show', ...info, cwd }));
       return EXIT.OK;
     }
     toStdout(
-      `knowledge store mode for this directory: ${before} -> ${kc.mode}  (saved per-directory)\n` +
-      `  scope:   ${kc.mode === 'none' ? 'disabled here' : kc.mode === 'project' ? 'this directory only' : 'shared across all directories'}\n` +
-      `  saved:   per-directory (${cwd})\n` +
+      `knowledge store mode: ${info.mode}   (source: ${info.origin})\n` +
+      `  scope:   ${info.mode === 'none' ? 'disabled here' : info.mode === 'project' ? 'this directory only' : 'shared across all directories'}\n` +
       `  db dir:  ${info.dbDir}\n` +
-      (overridden
-        ? `\nNOTE: the effective mode here is still '${info.mode}' because a higher-precedence ${info.origin} overrides it. Clear that source for this setting to take effect.\n`
-        : ''),
+      `\nchange it for THIS directory:  ${BINARY_NAME} knowledge-config set <none|project|global>\n` +
+      `change the machine-wide default: set PI_RESEARCH_KNOWLEDGE_STORE_MODE=<mode> in ${resolvedConfigPaths().configEnv}\n`,
     );
     return EXIT.OK;
+  } catch (err) {
+    return reportError(err, 'knowledge-config', kc.json);
   }
-
-  // show
-  const info = describeKnowledgeStoreMode(cwd, 'cli');
-  if (kc.json) {
-    toStdout(pretty({ command: 'knowledge-config', action: 'show', ...info, cwd }));
-    return EXIT.OK;
-  }
-  toStdout(
-    `knowledge store mode: ${info.mode}   (source: ${info.origin})\n` +
-    `  scope:   ${info.mode === 'none' ? 'disabled here' : info.mode === 'project' ? 'this directory only' : 'shared across all directories'}\n` +
-    `  db dir:  ${info.dbDir}\n` +
-    `\nchange it for THIS directory:  ${BINARY_NAME} knowledge-config set <none|project|global>\n` +
-    `change the machine-wide default: set PI_RESEARCH_KNOWLEDGE_STORE_MODE=<mode> in ${resolvedConfigPaths().configEnv}\n`,
-  );
-  return EXIT.OK;
 }
 
 // ---------------------------------------------------------------------------
@@ -1058,21 +1122,25 @@ COMMANDS
     --model <provider/id>        Model for this run (outranks PI_RESEARCH_MODEL; satisfies the required-model check).
     --exclude-tools <a,b>        Disable internal tools (e.g. security_search,stackexchange).
     --initial-links <url ...>    Seed URLs to investigate first; requires a query (-- ends options).
-    --config <path>              Use this config file instead of the base config.env.
+    --config <path>              Layer this config file on top (highest file precedence; base
+                                 config.env keys it does not set still apply; env vars still win).
     --json                       Emit a JSON object instead of a markdown report.
 
   knowledge "<q1>" ["<q2>" ...]  Search local knowledge store before live research (up to 5 queries).
-    --config <path>              Use this config file instead of the base config.env.
+    --config <path>              Layer this config file on top (highest file precedence; base
+                                 config.env keys it does not set still apply; env vars still win).
     --json                       Emit a JSON object.
 
   knowledge-config [show]        Show the knowledge-store mode for this directory + its source.
-    --config <path>              Use this config file instead of the base config.env.
+    --config <path>              Layer this config file on top (highest file precedence; base
+                                 config.env keys it does not set still apply; env vars still win).
     --json                       Emit a JSON object.
   knowledge-config set <mode>    Set the mode for THIS directory (none | project | global);
                                  persisted per-directory. Takes effect on the next run.
 
   status                         Show detected config, model/key, and readiness.
-    --config <path>              Use this config file instead of the base config.env.
+    --config <path>              Layer this config file on top (highest file precedence; base
+                                 config.env keys it does not set still apply; env vars still win).
     --json                       Emit a JSON object.
 
   skill [status]                 Show where the agent skill is installed across your coding agents.
@@ -1118,6 +1186,20 @@ EXIT CODES
 `;
 }
 
+/**
+ * Read a value-taking option's argument, rejecting the next FLAG as a value.
+ * Truthiness alone let `--model --json` run a full research session against the
+ * literal model "--json" (failing minutes-deep at exit 70 with the --json output
+ * contract silently dropped) instead of failing fast at exit 64.
+ */
+function takeOptionValue(rest: (string | undefined)[], valueIndex: number, flag: string): string {
+  const v = rest[valueIndex];
+  if (v === undefined || v.startsWith('--')) {
+    throw new UsageError(`${flag} requires a value.`);
+  }
+  return v;
+}
+
 export function parseArgs(argv: string[]): ParsedArgs {
   const out: ParsedArgs = {};
   const args = argv.slice(2);
@@ -1140,10 +1222,21 @@ export function parseArgs(argv: string[]): ParsedArgs {
   const rest = args.slice(1);
 
   if (cmd === 'status') {
-    const json = rest.includes('--json');
+    // Same unknown-option rejection loop as the other subcommands. The previous
+    // ad-hoc rest.includes('--json') accepted anything — `status --jsn` and
+    // `status --json=true` exited 0 with human output instead of failing fast.
+    let json = false;
     let configPath: string | undefined;
-    const ci = rest.indexOf('--config');
-    if (ci !== -1 && rest[ci + 1]) configPath = rest[ci + 1];
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === '--json') json = true;
+      else if (a === '--config') configPath = takeOptionValue(rest, ++i, '--config');
+      else if (a?.startsWith('--')) {
+        throw new UsageError(`unknown option for status: ${a}. Valid options: --json, --config <path>.`);
+      } else if (a !== undefined) {
+        throw new UsageError(`unexpected argument "${a}" after "status".`);
+      }
+    }
     out.command = 'status';
     out.status = { json };
     out.configPath = configPath;
@@ -1157,7 +1250,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
     for (let i = 0; i < rest.length; i++) {
       const a = rest[i];
       if (a === '--json') json = true;
-      else if (a === '--config' && rest[i + 1]) configPath = rest[++i];
+      else if (a === '--config') configPath = takeOptionValue(rest, ++i, '--config');
       else if (a?.startsWith('--')) {
         throw new UsageError(`unknown option for knowledge: ${a}`);
       } else if (a !== undefined) {
@@ -1179,7 +1272,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
     for (let i = 0; i < rest.length; i++) {
       const a = rest[i];
       if (a === '--json') json = true;
-      else if (a === '--config' && rest[i + 1]) configPath = rest[++i];
+      else if (a === '--config') configPath = takeOptionValue(rest, ++i, '--config');
       else if (a?.startsWith('--')) {
         throw new UsageError(`unknown option for knowledge-config: ${a}`);
       } else if (a !== undefined) {
@@ -1263,11 +1356,11 @@ export function parseArgs(argv: string[]): ParsedArgs {
         if (isNaN(n) || n < 0 || n > 3) throw new UsageError('--depth must be an integer 0–3.');
         depth = n;
       } else if (a === '--model') {
-        model = rest[++i];
-        if (!model) throw new UsageError('--model requires a value.');
+        model = takeOptionValue(rest, ++i, '--model');
       } else if (a === '--exclude-tools') {
-        const v = rest[++i];
-        excludeTools = v ? v.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+        const v = takeOptionValue(rest, ++i, '--exclude-tools');
+        excludeTools = v.split(',').map((s) => s.trim()).filter(Boolean);
+        if (excludeTools.length === 0) excludeTools = undefined;
       } else if (a === '--initial-links') {
         // Consume until the next flag or end. Validate each entry: these are templated
         // verbatim into the researcher's "investigate these first" evidence block, so
@@ -1289,8 +1382,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
         }
         i = j - 1;
       } else if (a === '--config') {
-        configPath = rest[++i];
-        if (!configPath) throw new UsageError('--config requires a path.');
+        configPath = takeOptionValue(rest, ++i, '--config');
       } else if (a === '--json') {
         json = true;
       } else if (a?.startsWith('--')) {
@@ -1380,14 +1472,63 @@ export function _markCancellationForTests(sig?: NodeJS.Signals): void {
   cancellationSignal = sig ?? null;
 }
 
+/**
+ * When the FIRST cancelling signal was handled (epoch ms), or null before one
+ * arrives. Module-scoped rather than a main() closure so the duplicate-vs-force
+ * decision below is directly testable through the seams underneath.
+ */
+let firstSignalAtMs: number | null = null;
+
+/**
+ * How long after the first signal a repeat still reads as a MECHANICAL
+ * duplicate. The skill launcher forwards every cancelling signal to this
+ * process — but with stdio:'inherit' a tty Ctrl-C has ALREADY delivered SIGINT
+ * to the whole foreground group, so the forwarded copy lands within
+ * milliseconds of the first. A human's second Ctrl-C at a stuck cleanup comes
+ * seconds later; 1s cleanly separates the two.
+ */
+const SIGNAL_FORCE_EXIT_GRACE_MS = 1_000;
+
+export type SignalDisposition = 'begin-cleanup' | 'absorb-duplicate' | 'force-exit';
+
+/**
+ * Decide what a delivered cancelling signal means, latching the first arrival.
+ * Exported as the test seam for the duplicate-absorption contract: the race
+ * windows (a forwarded duplicate landing mid-safeShutdown) cannot be timed
+ * reliably through a spawned CLI, so tests drive the decision directly —
+ * mirroring the _markCancellationForTests seam above.
+ */
+export function _signalDisposition(now: number = Date.now()): SignalDisposition {
+  if (firstSignalAtMs === null) {
+    firstSignalAtMs = now;
+    return 'begin-cleanup';
+  }
+  return now - firstSignalAtMs > SIGNAL_FORCE_EXIT_GRACE_MS ? 'force-exit' : 'absorb-duplicate';
+}
+
+export function _resetSignalDispositionForTests(): void {
+  firstSignalAtMs = null;
+}
+
 async function main(argv: string[]): Promise<number> {
   // Register signal handlers so SIGINT/SIGTERM always trigger SDK shutdown
   // before the process exits. safeShutdown() is idempotent — safe to call
   // before SDK init (it no-ops) and safe to call from multiple signals.
-  let _signalCleanupDone = false;
   const onSignal = (sig: string) => {
-    if (_signalCleanupDone) return;
-    _signalCleanupDone = true;
+    switch (_signalDisposition()) {
+      case 'absorb-duplicate':
+        // The launcher's forwarded copy of a signal the tty already delivered
+        // to the whole foreground group — cleanup is running; swallow it.
+        return;
+      case 'force-exit':
+        // A repeat WELL after the first is a human (or an escalating harness)
+        // at a stuck cleanup: honour it immediately, on the true 128+N.
+        toStderr(`\n[pi-research] ${sig} again — force exit\n`);
+        process.exit(exitCodeForSignal(sig as NodeJS.Signals));
+        return;
+      case 'begin-cleanup':
+        break;
+    }
     cancellationRequested = true;
     cancellationSignal = sig as NodeJS.Signals;
     toStderr(`\n[pi-research] ${sig} — cleaning up…\n`);
@@ -1404,8 +1545,15 @@ async function main(argv: string[]): Promise<number> {
     // exit status depend on whether this handler beat a force-kill.
     void safeShutdown().finally(() => flushAndExit(exitCodeForSignal(sig as NodeJS.Signals)));
   };
-  process.once('SIGINT', () => onSignal('SIGINT'));
-  process.once('SIGTERM', () => onSignal('SIGTERM'));
+  // process.on, NOT process.once: a once-handler is CONSUMED by its first
+  // delivery, restoring the default disposition — and the launcher forwards
+  // every cancelling signal it receives, so a tty Ctrl-C (delivered group-wide
+  // by the terminal AND re-forwarded by the launcher) had its duplicate kill
+  // this process instantly, mid-safeShutdown, skipping browser/embedder
+  // teardown. Persistent handlers absorb duplicates via _signalDisposition,
+  // which still preserves a human force-quit escape after the grace window.
+  process.on('SIGINT', () => onSignal('SIGINT'));
+  process.on('SIGTERM', () => onSignal('SIGTERM'));
   // SIGHUP (terminal closed) and, on Windows, SIGBREAK (Ctrl+Break). Without these
   // the run dies without cancelling: no abort of the in-flight research, no browser
   // or embedding-server teardown, and no 128+N exit code. On Windows it matters
@@ -1414,9 +1562,9 @@ async function main(argv: string[]): Promise<number> {
   // The SDK already registers both (see _addSignalHandlers); the CLI did not, which
   // left the SDK's handler to tear the container down underneath a live orchestrator
   // — exactly the race the CLI installs its own handlers to avoid.
-  process.once('SIGHUP', () => onSignal('SIGHUP'));
+  process.on('SIGHUP', () => onSignal('SIGHUP'));
   if (process.platform === 'win32') {
-    process.once('SIGBREAK', () => onSignal('SIGBREAK'));
+    process.on('SIGBREAK', () => onSignal('SIGBREAK'));
   }
 
   let parsed: ParsedArgs;
@@ -1432,7 +1580,17 @@ async function main(argv: string[]): Promise<number> {
   // help/version are pure and need no credentials/config.
   const noBridge = new Set(['help', 'version']);
   if (!noBridge.has(parsed.command ?? '')) {
-    bridgeConfigEnv(parsed.configPath);
+    try {
+      bridgeConfigEnv(parsed.configPath);
+    } catch (err) {
+      if (err instanceof ConfigFileError) {
+        // An explicit --config that does not apply is a setup error: silently
+        // running on ambient config and reporting success would mask the typo.
+        toStderr(`\nError: ${err.message}\n`);
+        return EXIT.CONFIG;
+      }
+      throw err;
+    }
     // Self-heal cross-harness skill installs on every engine-touching CLI run. The
     // CLI — not the interactive pi extension — is the surface that skill invocations
     // from Claude Code / Codex / OpenClaw actually drive, so without this an update