@lincoln504/pi-research 1.2.0 → 1.3.1

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

package/src/config.ts

@@ -302,6 +302,82 @@ function sleepSync(ms: number): void {
  * could both read the same pre-change snapshot and clobber each other's entry (a lost update).
  * `mutate` receives the latest on-disk registry and edits it in place.
  */
+/**
+ * Age past which a leftover reclaim file (see the failed-restore branch below) is
+ * swept. Well beyond the 30s lock-staleness threshold, so a reclaim file another
+ * contender is still inspecting mid-steal is never yanked out from under it.
+ */
+const RECLAIM_FILE_SWEEP_AGE_MS = 120_000;
+
+/**
+ * Sweep reclaim files left behind by an earlier steal whose ABA restore lost the
+ * path race (that branch leaves them in place ON PURPOSE — see below). Runs only
+ * at steal time, which is already the rare contended path, so normal acquires
+ * pay nothing.
+ */
+function sweepLeftoverReclaimFiles(lockPath: string): void {
+  try {
+    const dir = path.dirname(lockPath);
+    const prefix = `${path.basename(lockPath)}.stale-`;
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.startsWith(prefix)) continue;
+      const p = path.join(dir, name);
+      try {
+        if (Date.now() - fs.statSync(p).mtimeMs > RECLAIM_FILE_SWEEP_AGE_MS) fs.unlinkSync(p);
+      } catch { /* raced with another sweeper — ignore */ }
+    }
+  } catch { /* hygiene only — never block the steal */ }
+}
+
+/**
+ * Reclaim a lock file already judged stale, without the unlink race.
+ *
+ * A direct `unlinkSync(lockPath)` lets two contenders both judge the SAME lock
+ * stale: the slower one then unlinks the winner's freshly created lock, and both
+ * enter the critical section — the exact lost update the lock exists to prevent.
+ * Rename is atomic, so exactly one contender wins the steal; the inode check then
+ * catches the narrower ABA case where the path already holds a NEW lock created
+ * after the caller's stat, and `linkSync` restores it without clobbering (link
+ * fails EEXIST if yet another lock took the path meanwhile).
+ *
+ * Callers always `continue` their O_EXCL acquire loop afterwards — this helper
+ * never grants the lock, it only makes the steal single-winner.
+ */
+function stealStaleLock(lockPath: string, judgedStale: fs.Stats): void {
+  sweepLeftoverReclaimFiles(lockPath);
+  const reclaimPath = `${lockPath}.stale-${process.pid}-${Date.now()}`;
+  try {
+    fs.renameSync(lockPath, reclaimPath);
+  } catch {
+    return; // Another contender already stole it — re-enter the acquire loop.
+  }
+  try {
+    const claimed = fs.statSync(reclaimPath);
+    if (claimed.ino !== judgedStale.ino) {
+      // We grabbed a lock created after our staleness judgment — put it back.
+      try {
+        fs.linkSync(reclaimPath, lockPath);
+      } catch {
+        // A newer lock claimed the path before the restore (EEXIST). Do NOT
+        // unlink the reclaim file: it is the displaced FRESH lock's inode —
+        // falling through to the unlink below permanently destroyed a live
+        // holder's lock (and the post-mortem evidence of this race). Leaving it
+        // costs one stale file, collected by the age-gated sweep above.
+        return;
+      }
+    }
+  } catch { /* ignore */ }
+  try { fs.unlinkSync(reclaimPath); } catch { /* ignore */ }
+}
+
+/**
+ * Test seam: stealStaleLock's race windows (a contender's O_EXCL create landing
+ * between the rename and the linkSync restore) cannot be interleaved through the
+ * public save/update API — the code is synchronous with no yield points — so
+ * tests drive the helper directly.
+ */
+export const _stealStaleLockForTests = stealStaleLock;
+
 function updateProjectSettingsRegistry(mutate: (registry: Record<string, Record<string, string>>) => void): void {
   const registryPath = getProjectSettingsRegistryPath();
   const dir = path.dirname(registryPath);
@@ -327,7 +403,7 @@ function updateProjectSettingsRegistry(mutate: (registry: Record<string, Record<
           try {
             const stats = fs.statSync(lockPath);
             if (Date.now() - stats.mtimeMs > 30000) {
-              fs.unlinkSync(lockPath);
+              stealStaleLock(lockPath, stats);
               continue;
             }
           } catch { /* ignore */ }
@@ -841,7 +917,7 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
         try {
           const stats = fs.statSync(lockPath);
           if (Date.now() - stats.mtimeMs > 30000) {
-            fs.unlinkSync(lockPath);
+            stealStaleLock(lockPath, stats);
             continue;
           }
         } catch { /* ignore */ }

package/src/core/interfaces/health-check-interfaces.ts

@@ -5,46 +5,10 @@
 import type { IService } from '../service-registry.ts';
 
 /**
- * Health check result
+ * Health check registry interface
  */
-export interface HealthCheckResult {
-  success: boolean;
-  searchOk: boolean;
-  scrapeOk: boolean;
-  error?: string;
-  timestamp: string;
-}
-
-/**
- * Health check cache state
- */
-export interface HealthCheckCache {
-  pending: Promise<HealthCheckResult> | null;
-  failureCount: number;
-  backoffUntil: number;
-}
-
-/**
- * Health check service interface
- */
-export interface IHealthCheckService extends IService {
-  getPendingCheck(): Promise<HealthCheckResult> | null;
-  setPendingCheck(promise: Promise<HealthCheckResult> | null): void;
-  getFailureCount(): number;
-  incrementFailureCount(): void;
-  resetFailureCount(): void;
-  getBackoffUntil(): number;
-  setBackoffUntil(timestamp: number): void;
-  clear(): void;
-  isBackoffActive(): boolean;
-  getBackoffRemainingMs(): number;
-  }
-
-  /**
-  * Health check registry interface
-  */
-  export interface IHealthRegistryService extends IService {
+export interface IHealthRegistryService extends IService {
   register(name: string, check: (options?: { force?: boolean }) => Promise<{ healthy: boolean; error?: string; diagnostic?: Record<string, any> }>, options?: { timeoutMs?: number; critical?: boolean }): void;
   isCritical(componentName: string): boolean;
   runAll(options?: { force?: boolean }): Promise<{ status: 'healthy' | 'degraded' | 'unhealthy'; components: any[]; timestamp: string }>;
-  }
+}

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

@@ -66,6 +66,14 @@ export interface UpdatePlanOptions {
   previousPlan: ResearchPlan | null;
   totalResearchersPlanned: number;
   mustSynthesize?: boolean;
+  /** The caller's live round budget (base complexity max plus any steering-driven
+   *  extension), e.g. from DeepResearchOrchestrator's extended `maxRounds`. When
+   *  omitted, updatePlanForRound falls back to the base complexity-table value —
+   *  which understates the budget once steering has extended it, skewing the
+   *  round-phase-guidance ratio (and its EARLY/MIDDLE/LATE branch selection)
+   *  toward LATE too early. Optional and additive: existing callers that don't
+   *  pass it keep the prior behavior unchanged. */
+  maxRounds?: number;
   observer?: ResearchObserver;
   excludeTools?: string[];
   steeringMessages?: string[];

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

@@ -8,7 +8,6 @@
 export const ServiceNames = {
   SCHEDULER: 'scheduler',
   SCHEDULER_FACTORY: 'scheduler-factory',
-  HEALTH_CHECK_CACHE: 'health-check-cache',
   STATE_MANAGER: 'state-manager',
   KNOWLEDGE_STORE: 'knowledge-store',
   WRITER_QUEUE: 'writer-queue',