@lincoln504/pi-research 1.1.0 → 1.2.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
 // ---------------------------------------------------------------------------
@@ -137,9 +177,19 @@ function makeProgressObserver(): HeadlessObserverOptions {
         case 'evaluation_decision':
           toStderr(`  • evaluator: ${data?.action}\n`);
           break;
-        case 'tokens_consumed':
-          if (data?.cost) toStderr(`  • tokens: ${data?.tokens ?? 0} ($${Number(data.cost).toFixed(4)})\n`);
+        case 'tokens_consumed': {
+          // A truthiness check on cost used to gate this whole line, so a model with
+          // an all-zero price table suppressed the TOKEN count as well — the run
+          // looked like it consumed nothing. Tokens stand on their own; cost is
+          // appended whenever it is a number, including 0.
+          const consumed = Number(data?.tokens ?? 0);
+          const costVal = typeof data?.cost === 'number' ? data.cost : undefined;
+          if (consumed > 0 || costVal !== undefined) {
+            const costPart = costVal === undefined ? '' : ` ($${costVal.toFixed(4)})`;
+            toStderr(`  • tokens: ${consumed}${costPart}\n`);
+          }
           break;
+        }
         case 'complete':
           toStderr(`  • complete (${data?.result?.length ?? 0} chars)\n`);
           break;
@@ -180,20 +230,33 @@ 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> = {};
+  // 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>();
   for (const filePath of [basePath, cliOverlayPath]) {
     try {
       if (!fs.existsSync(filePath)) continue;
-      Object.assign(merged, parseDotEnv(fs.readFileSync(filePath, 'utf-8')));
+      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);
+      }
       loaded = true;
     } catch {
       // ignore unreadable 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;
     }
@@ -853,9 +916,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') ||
@@ -869,20 +948,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;
     }
@@ -890,6 +976,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) {
@@ -1014,10 +1107,14 @@ CONFIGURE
   Run \`${BINARY_NAME} status\` to see exactly what is detected.
 
 EXIT CODES
-  0  success
-  64 bad arguments
-  78 not configured — message prints the exact locations to fix
-  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)
 `;
 }
 
@@ -1257,6 +1354,32 @@ 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;
+}
+
 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
@@ -1265,6 +1388,8 @@ async function main(argv: string[]): Promise<number> {
   const onSignal = (sig: string) => {
     if (_signalCleanupDone) return;
     _signalCleanupDone = true;
+    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
@@ -1274,10 +1399,25 @@ 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'));
+  // 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.once('SIGHUP', () => onSignal('SIGHUP'));
+  if (process.platform === 'win32') {
+    process.once('SIGBREAK', () => onSignal('SIGBREAK'));
+  }
 
   let parsed: ParsedArgs;
   try {

package/src/config.ts

@@ -14,6 +14,7 @@ import { getConfigDirName } from './utils/host-config.ts';
 import { Type, type Static } from 'typebox';
 import { Value } from 'typebox/value';
 import { normalizeWorkspacePath } from './utils/text-utils.ts';
+import { replaceFileSync } from './utils/atomic-replace.ts';
 
 /**
  * Validates configuration schema using TypeBox.
@@ -501,7 +502,7 @@ export function describeKnowledgeStoreMode(
     let registryHasKey = false;
     try {
       const registry = loadProjectSettingsRegistry();
-      registryHasKey = registry[normalizeWorkspacePath(cwd)]?.[KEY] !== undefined;
+      registryHasKey = findRegistryEntry(registry, normalizeWorkspacePath(cwd))?.[KEY] !== undefined;
     } catch { /* unreadable registry → not the origin */ }
     if (registryHasKey) origin = 'this directory (project settings)';
     else if (iface && fileHasKey(getInterfaceEnvFilePath(iface))) origin = `${iface}.env overlay`;
@@ -546,12 +547,48 @@ export function parseDotEnv(content: string): Record<string, string> {
  * Load environment variables from global and local files.
  * Order: Global File < Interface overlay < Legacy .env < Centralized Registry (WINS)
  */
+/**
+ * Look up a directory's entry in the project-settings registry, tolerating case.
+ *
+ * On Windows and on macOS's default (case-insensitive) filesystem, `C:\\Users\\Bob\\Proj`
+ * and `c:\\users\\bob\\proj` are the SAME directory but different object keys, so a shell
+ * that reports a different casing than the one the settings were saved under made those
+ * settings silently vanish. normalizeWorkspacePath only resolves and strips a trailing
+ * separator; it does not fold case, and it must not start doing so — the key it produces
+ * is persisted, so folding it would orphan every entry already on disk.
+ *
+ * Resolving at READ time instead fixes the lookup without touching stored data: exact
+ * match first (the only path taken on Linux, and the fast path everywhere), then a
+ * case-insensitive scan as a fallback.
+ */
+function findRegistryKey(
+  registry: Record<string, Record<string, string>>,
+  normalizedCwd: string,
+): string | undefined {
+  if (registry[normalizedCwd] !== undefined) return normalizedCwd;
+  // Only case-insensitive filesystems can produce this mismatch; skip the scan elsewhere.
+  if (process.platform !== 'win32' && process.platform !== 'darwin') return undefined;
+  const lowered = normalizedCwd.toLowerCase();
+  for (const key of Object.keys(registry)) {
+    if (key.toLowerCase() === lowered) return key;
+  }
+  return undefined;
+}
+
+function findRegistryEntry(
+  registry: Record<string, Record<string, string>>,
+  normalizedCwd: string,
+): Record<string, string> | undefined {
+  const key = findRegistryKey(registry, normalizedCwd);
+  return key === undefined ? undefined : registry[key];
+}
+
 function loadEnvFiles(cwd: string, iface?: ConfigInterface): Record<string, string> {
   const merged: Record<string, string> = {};
   const globalPath = getGlobalEnvFilePath();
   const registry = loadProjectSettingsRegistry();
   const normalizedCwd = normalizeWorkspacePath(cwd);
-  const homeRegistry = registry[normalizeWorkspacePath(os.homedir())];
+  const homeRegistry = findRegistryEntry(registry, normalizeWorkspacePath(os.homedir()));
 
   // 1. ONE-TIME MIGRATION: Populate config.env from HOME registry if missing
   try {
@@ -613,15 +650,17 @@ function loadEnvFiles(cwd: string, iface?: ConfigInterface): Record<string, stri
         Object.entries(legacyEnv).filter(([k]) => LOCAL_SCOPE_KEYS.has(k))
       );
       const existingLocal = Object.fromEntries(
-        Object.entries(registry[normalizedCwd] ?? {}).filter(([k]) => LOCAL_SCOPE_KEYS.has(k))
+        Object.entries(findRegistryEntry(registry, normalizedCwd) ?? {}).filter(([k]) => LOCAL_SCOPE_KEYS.has(k))
       );
       if (Object.keys(legacyLocal).length > 0 && JSON.stringify(existingLocal) !== JSON.stringify(legacyLocal)) {
         logger.info(`[config] Migrating legacy .pi-research.env settings from ${cwd} to central registry...`);
         // Persist under the registry lock, reading the latest on-disk state so a concurrent
         // write isn't lost; also reflect the merge in the in-memory `registry` used just below.
-        registry[normalizedCwd] = { ...registry[normalizedCwd], ...legacyLocal };
+        const mergeKey = findRegistryKey(registry, normalizedCwd) ?? normalizedCwd;
+        registry[mergeKey] = { ...registry[mergeKey], ...legacyLocal };
         updateProjectSettingsRegistry((disk) => {
-          disk[normalizedCwd] = { ...disk[normalizedCwd], ...legacyLocal };
+          const diskKey = findRegistryKey(disk, normalizedCwd) ?? normalizedCwd;
+          disk[diskKey] = { ...disk[diskKey], ...legacyLocal };
         });
       }
     } catch (err) {
@@ -633,8 +672,9 @@ function loadEnvFiles(cwd: string, iface?: ConfigInterface): Record<string, stri
   //    LOCAL_SCOPE_KEYS are applied (and may override), never user-scoped keys — those belong to
   //    config.env. Any non-local key present here is stale pollution (e.g. a pre-fix legacy
   //    migration) and is ignored rather than allowed to override the user's global settings.
-  if (registry[normalizedCwd]) {
-    for (const [key, val] of Object.entries(registry[normalizedCwd])) {
+  const cwdEntry = findRegistryEntry(registry, normalizedCwd);
+  if (cwdEntry) {
+    for (const [key, val] of Object.entries(cwdEntry)) {
       if (LOCAL_SCOPE_KEYS.has(key)) {
         // Don't interpolate values in warnings — a config key could carry a secret and
         // redactSecrets won't catch short/non-standard tokens. Key + winner is enough.
@@ -763,7 +803,11 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
     // Read-merge-write under one lock so a concurrent local write to another directory
     // isn't lost (the merge onto the existing entry happens against the latest on-disk state).
     updateProjectSettingsRegistry((registry) => {
-      registry[normalizedCwd] = { ...(registry[normalizedCwd] ?? {}), ...newValues };
+      // Merge into the entry that already represents THIS directory, even if it was
+      // written with different casing on a case-insensitive filesystem. Writing a
+      // second key would leave the earlier settings stranded and unreachable.
+      const key = findRegistryKey(registry, normalizedCwd) ?? normalizedCwd;
+      registry[key] = { ...(registry[key] ?? {}), ...newValues };
     });
 
     logger.debug(`[config] Saved project settings for ${normalizedCwd} to central registry.`);
@@ -870,15 +914,12 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
     const tmpPath = `${p}.tmp.${process.pid}.${Date.now()}`;
     fs.writeFileSync(tmpPath, outLines.join('\n'), { encoding: 'utf-8', mode: 0o600 });
     try {
-      fs.renameSync(tmpPath, p);
-    } catch (renameErr) {
-      if (process.platform === 'win32') {
-        fs.copyFileSync(tmpPath, p);
+      if (replaceFileSync(tmpPath, p) === 'copied') {
         try { fs.unlinkSync(tmpPath); } catch { /* best effort */ }
-      } else {
-        try { fs.unlinkSync(tmpPath); } catch { /* best effort */ }
-        throw renameErr;
       }
+    } catch (renameErr) {
+      try { fs.unlinkSync(tmpPath); } catch { /* best effort */ }
+      throw renameErr;
     }
     // Tighten regardless of how the file came to exist (fresh rename, Windows copy over
     // an existing file, or a pre-hardening 0644 file that the rename replaced-in-place).

package/src/constants.ts

@@ -177,3 +177,34 @@ export const RESEARCHER_LAUNCH_DELAY_MS = 1500;
 export const MAX_QUERIES_PER_RESEARCHER_LEVEL_1 = 10;
 export const MAX_QUERIES_PER_RESEARCHER_LEVEL_2 = 15;
 export const MAX_QUERIES_PER_RESEARCHER_LEVEL_3 = 20;
+
+/**
+ * Tools excluded from every researcher unless the caller says otherwise.
+ *
+ * `grep` is developer-only: during WEB research a high-capability model otherwise
+ * spends turns searching the local filesystem instead of the internet.
+ */
+export const DEFAULT_EXCLUDED_TOOLS: readonly string[] = ['grep'];
+
+/**
+ * Resolve the effective researcher exclusion list.
+ *
+ * An EMPTY array is "no preference", not "exclude nothing". The two front-ends
+ * express no-preference differently — the pi extension always builds an array
+ * (`[...new Set([...])]`, often empty) while the CLI omits the key entirely — so a
+ * plain truthiness test made the same user input mean opposite things: grep was
+ * available in the extension and excluded on the CLI, regardless of depth.
+ *
+ * `configDisabled` (PI_RESEARCH_DISABLED_TOOLS) is strictly ADDITIVE. Folding it in
+ * as a replacement meant disabling any unrelated tool silently ENABLED grep, so a
+ * subtract-only setting could grant a capability.
+ */
+export function resolveExcludedTools(
+  callerExclusions: readonly string[] | undefined,
+  configDisabled: readonly string[] = [],
+): string[] {
+  const base = callerExclusions && callerExclusions.length > 0
+    ? callerExclusions
+    : DEFAULT_EXCLUDED_TOOLS;
+  return [...new Set([...base, ...configDisabled])];
+}

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

@@ -120,7 +120,12 @@ export interface IKnowledgeStore extends IService {
   /** Extended operations */
   addDocuments(docs: StoreDocument[]): Promise<void>;
   deleteByUrl(url: string): Promise<void>;
-  deleteByUrlAndType(url: string, ingestionType: string): Promise<void>;
+  /**
+   * @param olderThan When set, only rows with `timestamp < olderThan` are removed —
+   *   lets a refresh insert its replacement first and prune the superseded rows
+   *   afterwards, so a failed insert can never leave the URL with nothing.
+   */
+  deleteByUrlAndType(url: string, ingestionType: string, olderThan?: number): Promise<void>;
   isStoreClosed?(): boolean;
 
   /**

package/src/core/interfaces/state-manager-interfaces.ts

@@ -18,7 +18,7 @@ export interface IStateManager extends IService {
   getBrowserServer(): Promise<{ port: number; pid: number; schedulerId?: string; authSecret?: string } | null>;
   setBrowserServer(port: number, pid: number, schedulerId?: string, authSecret?: string): Promise<void>;
   clearBrowserServer(): Promise<void>;
-  getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string } | null>;
+  getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string; authSecret?: string } | null>;
   clearEmbeddingServer(): Promise<void>;
   isPidAlive(pid: number, expectedSchedulerId?: string, skipLock?: boolean): Promise<boolean>;
   acquireGpuLock(sessionId?: string, timeoutMs?: number): Promise<boolean>;

package/src/core/llm/model-registry-factory.ts

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

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

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