@lincoln504/pi-research 1.1.2 → 1.3.0

package/src/cli.ts

@@ -22,6 +22,7 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -84,8 +85,47 @@ export const EXIT = {
    * re-running a broken command.
    */
   TEMPFAIL: 75,
+  /**
+   * The run was CANCELLED via a programmatic abort (the caller's AbortSignal),
+   * with no OS signal involved. 130 — 128+SIGINT — is the conventional
+   * "interrupted" code and the natural default when there is no signal number to
+   * derive one from.
+   *
+   * A cancellation caused by an actual SIGNAL does NOT use this constant: see
+   * exitCodeForSignal below, which reports the true 128+N.
+   *
+   * Distinct from SOFTWARE for the same reason TEMPFAIL is: a deliberate stop is
+   * not a fault. Reported as SOFTWARE (70), a cancel matched the skill contract's
+   * "runtime error — suggest one retry for transient failures", so an agent
+   * relaying the result would offer to re-run the very research the user had just
+   * interrupted, and a --json consumer could not tell a cancel from a crash.
+   */
+  CANCELLED: 130,
 } as const;
 
+/**
+ * Exit code for a run stopped by `sig`, following the POSIX 128+N convention that
+ * a shell uses when reporting a signal-terminated child (SIGINT → 130,
+ * SIGTERM → 143, SIGHUP → 129, SIGQUIT → 131).
+ *
+ * Why derive it per-signal instead of returning a single "cancelled" code: this
+ * process INSTALLS handlers for those signals, so it is never actually killed by
+ * them — it catches them and exits deliberately. If it exited a flat 130, the code
+ * a wrapper observes would depend on whether our handler won the race against a
+ * force-kill: handler wins → 130, handler loses → the shell's 143. Deriving 128+N
+ * makes the handler transparent, so the same user action reports the same number
+ * either way.
+ *
+ * Every value lands in 129..143, safely inside the 0-255 range a POSIX wait status
+ * preserves — nothing here can be truncated to a false 0. Windows does not
+ * implement the 128+N convention at all (its exit codes are 32-bit and carry no
+ * signal semantics), so there these are simply our documented contract values.
+ */
+export function exitCodeForSignal(sig: NodeJS.Signals): number {
+  const signum = (os.constants.signals as Record<string, number | undefined>)[sig];
+  return typeof signum === 'number' ? 128 + signum : EXIT.CANCELLED;
+}
+
 // ---------------------------------------------------------------------------
 // Output helpers
 // ---------------------------------------------------------------------------
@@ -169,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
@@ -190,20 +243,52 @@ export function bridgeConfigEnv(explicitConfigPath?: string): { path: string; lo
   // iteration and the "don't clobber the real environment" guard would then
   // block the overlay's value — cli.env could never override config.env.
   const merged: Record<string, string> = {};
-  for (const filePath of [basePath, cliOverlayPath]) {
+  // Keys whose winning value came from an EXPLICIT --config file (not the
+  // default base, not the cli.env overlay). Project-scoped keys are only
+  // bridged for these — see below.
+  const fromExplicitBase = new Set<string>();
+  // 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;
-      Object.assign(merged, parseDotEnv(fs.readFileSync(filePath, 'utf-8')));
+      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);
+      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)) {
-    // Skip per-directory (project-scoped) keys: promoting them into process.env would make
-    // config.env out-rank the per-directory registry, defeating a per-cwd override. They are
-    // still applied as a lower-precedence file layer by getConfig()/loadEnvFiles().
-    if (isProjectScopedKey(k)) continue;
+    // Skip per-directory (project-scoped) keys from the AMBIENT files: promoting them into
+    // process.env would make config.env out-rank the per-directory registry, defeating a
+    // per-cwd override. They are still applied as a lower-precedence file layer by
+    // getConfig()/loadEnvFiles(). An EXPLICIT --config file is different: getConfig never
+    // reads that path, so skipping its keys silently dropped them (a depth or
+    // knowledge-mode set in `--config ci.env` simply did not apply) — and a file the user
+    // named on this exact invocation outranking the per-directory registry is the intent.
+    if (isProjectScopedKey(k) && !fromExplicitBase.has(k)) continue;
     if (process.env[k] === undefined && (k.startsWith('PI_RESEARCH_') || k === 'STACKEXCHANGE_API_KEY' || k === 'GITHUB_TOKEN' || k === 'NVD_API_KEY')) {
       process.env[k] = v;
     }
@@ -461,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);
@@ -534,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
@@ -546,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) {
@@ -568,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; }
@@ -583,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;
   }
@@ -607,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'));
   }
@@ -662,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -863,9 +980,25 @@ export async function reportError(err: unknown, what: string, json?: boolean): P
   // machine as a setup problem would send the user to reconfigure a working install.
   const isCapacity = err instanceof Error && err.name === 'ResearchRunCapacityError';
 
+  // Cancellation. Primary signal is the latch set by the SIGINT/SIGTERM handler —
+  // an exact fact, unlike the message, which varies by whichever subsystem noticed
+  // the abort first ('Aborted' from the search layer, 'Research aborted' /
+  // 'Research cancelled' from the orchestrator). The anchored message signatures
+  // only cover a programmatic abort where no signal arrived. Deliberately NOT
+  // matched: a bare `err.name === 'AbortError'` — internal timeout aborts
+  // (AbortSignal-driven retry/scrape deadlines) throw that name too, and an
+  // escaped one would report "cancelled — do not re-run" for a run nobody
+  // stopped. In the CLI every real cancellation sets the latch or carries these
+  // exact signatures. Checked before everything below: an abort can unwind
+  // through a provider call and surface wording that the config/rate-limit
+  // heuristics would otherwise claim.
+  const isCancellation =
+    cancellationRequested ||
+    (err instanceof Error && /^(aborted|research (aborted|cancelled))$/i.test(msg));
+
   // Auth / model / config-shaped errors → CONFIG exit + config block.
   const isConfigError =
-    !isTaggedResearchStop && !isCapacity && (
+    !isTaggedResearchStop && !isCapacity && !isCancellation && (
     lower.includes('no llm model available') ||
     lower.includes('not found in pi') ||
     lower.includes('no api key') ||
@@ -879,20 +1012,27 @@ export async function reportError(err: unknown, what: string, json?: boolean): P
   // "api key" in its body (e.g. "rate limit exceeded for this api key"), and
   // 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 = isCapacity
-    ? EXIT.TEMPFAIL
-    : isConfigError && !isRateLimit
-      ? EXIT.CONFIG
-      : EXIT.SOFTWARE;
+  const isRateLimit = !isCancellation && (lower.includes('429') || lower.includes('rate limit') || lower.includes('too many requests'));
+  const exitCode = isCancellation
+    ? (cancellationSignal ? exitCodeForSignal(cancellationSignal) : EXIT.CANCELLED)
+    : 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;
+    // and retry without string-matching the human message. Gated on cancellation:
+    // a Ctrl-C landing in the same window a queue-wait expires must never emit
+    // `cancelled: true` alongside `retryable: true` — a consumer honouring the
+    // latter would re-run the research the user just stopped.
+    if ((isCapacity || isRateLimit) && !isCancellation) payload['retryable'] = true;
+    // A cancel is emphatically NOT retryable-by-default: the user asked to stop.
+    if (isCancellation) payload['cancelled'] = true;
     if (process.env['PI_RESEARCH_DEBUG'] === 'true' && err instanceof Error && err.stack) {
       payload['stack'] = err.stack;
     }
@@ -900,6 +1040,13 @@ export async function reportError(err: unknown, what: string, json?: boolean): P
     return exitCode;
   }
 
+  // Cancellation is a completed intention, not a failure — never a stack trace,
+  // and never the word "failed".
+  if (isCancellation) {
+    toStderr(`\npi-research ${what} cancelled.\n`);
+    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) {
@@ -975,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.
@@ -1024,15 +1175,31 @@ CONFIGURE
   Run \`${BINARY_NAME} status\` to see exactly what is detected.
 
 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)
+  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)
+  130 cancelled — Ctrl-C; nothing failed, do not auto-retry
+      (other stop signals report POSIX 128+N: 143 SIGTERM, 129 SIGHUP, 131 SIGQUIT)
+  70  runtime error (network, provider, internal)
 `;
 }
 
+/**
+ * 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);
@@ -1055,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;
@@ -1072,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) {
@@ -1094,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) {
@@ -1178,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
@@ -1204,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('--')) {
@@ -1269,14 +1446,91 @@ const flushAndExit = (code: number): void => {
 // outlives that one run.
 let activeResearchAbortController: AbortController | null = null;
 
+/**
+ * Set once SIGINT/SIGTERM has been handled. Read by reportError so a cancellation
+ * is classified by the fact that we were signalled, not by pattern-matching the
+ * message an aborted subsystem happened to throw.
+ */
+let cancellationRequested = false;
+
+/**
+ * WHICH signal fired — so a cancellation that unwinds through reportError
+ * reports the same 128+N the signal path itself would (SIGTERM → 143, not a
+ * flat 130). reportError races onSignal's own flushAndExit; latching the name
+ * makes both racers agree on the number, and keeps the `exitCode` field in
+ * `--json` from contradicting the actual exit status.
+ */
+let cancellationSignal: NodeJS.Signals | null = null;
+
+/** Test seams for the module-level cancellation latch (set only by onSignal). */
+export function _resetCancellationLatchForTests(): void {
+  cancellationRequested = false;
+  cancellationSignal = null;
+}
+export function _markCancellationForTests(sig?: NodeJS.Signals): void {
+  cancellationRequested = true;
+  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`);
     // Abort the in-flight research run FIRST (synchronously ahead of the shutdown
     // teardown below) so the orchestrator's existing signal-aware cancellation path
@@ -1286,10 +1540,32 @@ async function main(argv: string[]): Promise<number> {
     // Fire-and-forget: we can't await here, but safeShutdown swallows errors
     // and the finally blocks in each command handler also call it. Drain via
     // flushAndExit (not a bare process.exit) so buffered stdout isn't truncated.
-    void safeShutdown().finally(() => flushAndExit(EXIT.SOFTWARE));
+    // 128+N, not a flat CANCELLED: see exitCodeForSignal. Because we handle these
+    // signals rather than dying from them, a fixed code would make the observed
+    // 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
+  // most — SIGTERM is never delivered there (process.kill maps to TerminateProcess),
+  // so Ctrl-C and Ctrl+Break are the only signals that reach this handler at all.
+  // 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.on('SIGHUP', () => onSignal('SIGHUP'));
+  if (process.platform === 'win32') {
+    process.on('SIGBREAK', () => onSignal('SIGBREAK'));
+  }
 
   let parsed: ParsedArgs;
   try {
@@ -1304,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