@lincoln504/pi-research 0.1.13 → 1.0.1

package/src/types/research-panel-types.ts

@@ -0,0 +1,61 @@
+/**
+ * Research Panel Types
+ *
+ * Type definitions for the research TUI panel.
+ */
+
+/**
+ * Local Theme interface — mirrors pi-tui Theme.fg()
+ */
+export interface Theme {
+  fg: (color: any, text: string) => string;
+}
+
+export interface SliceState {
+  id: string;
+  label: string; // Displayed label: "1", "2", "3", etc.
+  completed: boolean;
+  queued: boolean;
+  tokens?: number; // Tokens for this specific agent
+  cost?: number;   // Cost for this specific agent
+  status?: string; // Optional status message like "Searching..."
+  /** Active flash color — set by flashSlice, cleared by timeout. Always present. */
+  flash: 'green' | 'red' | null;
+  /** Terminal outcome: true if this researcher failed (retries exhausted / no links).
+   *  Rendered distinctly (error color + "failed" marker) so a failed researcher is not
+   *  visually identical to a successful one — a completed slice is otherwise drawn muted. */
+  failed?: boolean;
+}
+
+export interface ResearchProgress {
+  /** Total tool calls expected across all researchers in the initial plan. */
+  expected: number;
+  /** Actual tool calls completed so far. */
+  made: number;
+}
+
+export interface ResearchPanelState {
+  sessionId: string;
+  /** Alias for sessionId — used by the orchestrator */
+  researchId: string;
+  query: string;
+  slices: Map<string, SliceState>;
+  modelName: string;
+  /** True when the research is actively searching (queueing/executing search tool) */
+  isSearching?: boolean;
+  /** Optional progress bar data. Set after planning completes. */
+  progress?: ResearchProgress;
+  /** Animation frame counter for traveling wave effect during search */
+  waveFrame?: number;
+  /** Last-visit frame per position for wave animation decay */
+  waveColors?: number[];
+  /** Timer for wave animation */
+  waveTimer?: NodeJS.Timeout | null;
+  /** Flag indicating whether completed researchers should be cleared */
+  needsClear?: boolean;
+  /** 1-2 word topic title derived from the query after the coordinator LLM responds */
+  title?: string;
+  /** Whether the current research phase can accept steering messages.
+   * True during search/researcher phases. False during coordinator/evaluator LLM calls and after completion. */
+  steeringAcceptable?: boolean;
+}

package/src/utils/circuit-breaker.ts

@@ -0,0 +1,146 @@
+import { logger } from '../logger.ts';
+import { metrics } from './metrics.ts';
+
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+export interface CircuitBreakerOptions {
+  /** How many consecutive failures to open the circuit (default: 5) */
+  failureThreshold?: number;
+  /** How long to wait before testing recovery in HALF_OPEN state (default: 30000ms) */
+  resetTimeoutMs?: number;
+  /** How many successful calls needed in HALF_OPEN to close the circuit (default: 1) */
+  halfOpenMaxCalls?: number;
+  /** Optional name for logging */
+  name?: string;
+  /** 
+   * Function to determine if an error should count towards failure limit.
+   * If it returns false, the error is passed through without tripping the breaker.
+   * (default: counts all errors) 
+   */
+  isTransientError?: (error: unknown) => boolean;
+}
+
+export class CircuitBreaker {
+  private state: CircuitState = 'CLOSED';
+  private failureCount = 0;
+  private successCount = 0;
+  private nextAttemptTime = 0;
+  // Number of trial calls currently executing in HALF_OPEN. Caps concurrent probes so a burst of
+  // parallel callers doesn't all hit a still-recovering dependency the instant the breaker half-opens.
+  private halfOpenInFlight = 0;
+  private options: Required<CircuitBreakerOptions>;
+
+  constructor(options: CircuitBreakerOptions = {}) {
+    this.options = {
+      failureThreshold: options.failureThreshold ?? 5,
+      resetTimeoutMs: options.resetTimeoutMs ?? 30000,
+      halfOpenMaxCalls: options.halfOpenMaxCalls ?? 1,
+      name: options.name ?? 'CircuitBreaker',
+      isTransientError: options.isTransientError ?? (() => true),
+    };
+  }
+
+  async execute<T>(action: () => Promise<T>): Promise<T> {
+    const startTime = Date.now();
+    metrics.increment('circuit_breaker_calls_total', 1, { breaker: this.options.name, state: this.state });
+    
+    if (this.state === 'OPEN') {
+      if (Date.now() >= this.nextAttemptTime) {
+        this.transitionTo('HALF_OPEN');
+      } else {
+        metrics.increment('circuit_breaker_rejected_total', 1, { breaker: this.options.name, reason: 'open' });
+        throw new Error(`CircuitBreaker '${this.options.name}' is OPEN. Fast-failing to prevent cascading failure.`);
+      }
+    }
+
+    // HALF_OPEN admission control: allow only halfOpenMaxCalls trial calls to execute at once and
+    // fast-fail the rest. Without this, once the first caller flips OPEN→HALF_OPEN every other
+    // concurrent caller sees state !== 'OPEN', skips the gate, and hits the still-down dependency
+    // simultaneously — defeating the single-trial probe and immediately re-opening the breaker.
+    let admittedAsProbe = false;
+    if (this.state === 'HALF_OPEN') {
+      if (this.halfOpenInFlight >= this.options.halfOpenMaxCalls) {
+        metrics.increment('circuit_breaker_rejected_total', 1, { breaker: this.options.name, reason: 'half_open_probe_limit' });
+        throw new Error(`CircuitBreaker '${this.options.name}' is HALF_OPEN (trial in progress). Fast-failing to limit probes.`);
+      }
+      this.halfOpenInFlight++;
+      admittedAsProbe = true;
+    }
+
+    try {
+      const result = await action();
+      const duration = Date.now() - startTime;
+      metrics.observe('circuit_breaker_call_duration_ms', duration, { breaker: this.options.name, status: 'success' });
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      metrics.observe('circuit_breaker_call_duration_ms', duration, { breaker: this.options.name, status: 'error' });
+      if (this.options.isTransientError(error)) {
+        this.onFailure(error);
+      }
+      throw error;
+    } finally {
+      if (admittedAsProbe) this.halfOpenInFlight = Math.max(0, this.halfOpenInFlight - 1);
+    }
+  }
+
+  private onSuccess() {
+    metrics.increment('circuit_breaker_success_total', 1, { breaker: this.options.name, state: this.state });
+    if (this.state === 'HALF_OPEN') {
+      this.successCount++;
+      if (this.successCount >= this.options.halfOpenMaxCalls) {
+        this.transitionTo('CLOSED');
+      }
+    } else if (this.state === 'CLOSED') {
+      // Reset consecutive failures on success
+      this.failureCount = 0;
+    }
+  }
+
+  private onFailure(error: unknown) {
+    this.failureCount++;
+    const errMsg = error instanceof Error ? error.message : String(error);
+    metrics.increment('circuit_breaker_failures_total', 1, { breaker: this.options.name, state: this.state });
+    
+    if (this.state === 'HALF_OPEN') {
+      logger.warn(`[CircuitBreaker] '${this.options.name}' failed during HALF_OPEN state: ${errMsg}`);
+      this.transitionTo('OPEN');
+    } else if (this.state === 'CLOSED') {
+      if (this.failureCount >= this.options.failureThreshold) {
+        logger.error(`[CircuitBreaker] '${this.options.name}' reached failure threshold (${this.failureCount}): ${errMsg}`);
+        this.transitionTo('OPEN');
+      }
+    }
+  }
+
+  private transitionTo(newState: CircuitState) {
+    logger.warn(`[CircuitBreaker] '${this.options.name}' transitioning from ${this.state} to ${newState}`);
+    metrics.increment('circuit_breaker_state_transitions_total', 1, { breaker: this.options.name, from: this.state, to: newState });
+    metrics.setGauge('circuit_breaker_state', newState === 'CLOSED' ? 0 : newState === 'OPEN' ? 1 : 2, { breaker: this.options.name });
+    this.state = newState;
+    if (newState === 'OPEN') {
+      this.nextAttemptTime = Date.now() + this.options.resetTimeoutMs;
+    } else if (newState === 'HALF_OPEN') {
+      this.successCount = 0;
+      this.halfOpenInFlight = 0;
+    } else if (newState === 'CLOSED') {
+      this.failureCount = 0;
+      this.successCount = 0;
+    }
+  }
+
+  public getState(): CircuitState {
+    return this.state;
+  }
+
+  public reset(): void {
+    metrics.increment('circuit_breaker_resets_total', 1, { breaker: this.options.name });
+    this.state = 'CLOSED';
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.halfOpenInFlight = 0;
+    this.nextAttemptTime = 0;
+    metrics.setGauge('circuit_breaker_state', 0, { breaker: this.options.name });
+  }
+}

package/src/utils/citation-utils.ts

@@ -0,0 +1,97 @@
+import { parseCitations, lastCitedLinksHeaderIndex, type Citation } from './text-utils.ts';
+import { normalizeUrl } from './shared-links.ts';
+
+export interface GlobalCitation extends Citation {
+  id: number;
+}
+
+/**
+ * Normalizes citations across multiple reports.
+ * 
+ * 1. Extracts all citations from all reports.
+ * 2. Deduplicates URLs and assigns global IDs.
+ * 3. Replaces local citations [N] in each report with global IDs [G].
+ * 4. Removes the local CITED LINKS section from each report.
+ * 
+ * @param reports - Map of researcher ID to report content
+ * @returns Object containing normalized reports and the global citation list
+ */
+export function normalizeCitations(reports: Map<string, string>): {
+  normalizedReports: Map<string, string>;
+  globalCitations: GlobalCitation[];
+} {
+  const globalCitations: GlobalCitation[] = [];
+  const urlToGlobalId = new Map<string, number>();
+  const normalizedReports = new Map<string, string>();
+
+  // First pass: Collect all unique URLs and assign global IDs
+  for (const report of reports.values()) {
+    const citations = parseCitations(report);
+    for (const cit of citations) {
+      const normUrl = normalizeUrl(cit.url);
+      if (!urlToGlobalId.has(normUrl)) {
+        const id = globalCitations.length + 1;
+        urlToGlobalId.set(normUrl, id);
+        globalCitations.push({
+          id,
+          url: cit.url,
+          description: cit.description,
+          source: cit.source,
+        });
+      }
+    }
+  }
+
+  // Second pass: Normalize each report
+  for (const [id, report] of reports.entries()) {
+    const localCitations = parseCitations(report);
+    // Map of local index (1-based) to global ID
+    const localToGlobal = new Map<number, number>();
+    
+    localCitations.forEach((cit, index) => {
+      const globalId = urlToGlobalId.get(normalizeUrl(cit.url));
+      if (globalId !== undefined) {
+        // Key by the number the report actually WROTE for this entry (e.g. `[3]`), not its list
+        // position. A report that numbers CITED LINKS non-sequentially (or has an entry dropped as
+        // an implausible URL) would otherwise remap inline [N] to the wrong global id or leave it
+        // dangling. Fall back to position when a written number is unavailable.
+        const localKey = cit.number ?? (index + 1);
+        localToGlobal.set(localKey, globalId);
+      }
+    });
+
+    // Remove the trailing CITED LINKS section before renumbering — but only a real
+    // line-leading, all-caps header, never an incidental "cited links" mention in
+    // prose (an unanchored split there would drop real findings before the
+    // evaluator ever sees them).
+    const headerIdx = lastCitedLinksHeaderIndex(report);
+    let content = headerIdx >= 0 ? report.slice(0, headerIdx) : report;
+
+    // Replace [N] with [GlobalID]
+    // Also handle [N][M] combinations
+    content = content.replace(/\[(\d+)\]/g, (match, p1) => {
+      const localId = parseInt(p1, 10);
+      const globalId = localToGlobal.get(localId);
+      return globalId !== undefined ? `[${globalId}]` : match;
+    });
+
+    normalizedReports.set(id, content.trim());
+  }
+
+  return { normalizedReports, globalCitations };
+}
+
+/**
+ * Formats the global citation list into a CITED LINKS section string.
+ */
+export function formatCitedLinks(citations: GlobalCitation[]): string {
+  if (citations.length === 0) return '';
+
+  const links = citations.map(cit => {
+    const sourcePart = cit.source ? ` [Source: ${cit.source}]` : '';
+    const descPart = cit.description ? ` — ${cit.description}` : '';
+    return `[${cit.id}] ${cit.url}${sourcePart}${descPart}`;
+  });
+
+  return `CITED LINKS\n${links.join('\n')}`;
+}

package/src/utils/disk-space-checker.ts

@@ -0,0 +1,55 @@
+/**
+ * Disk Space Checker
+ *
+ * Checks available disk space for logging.
+ */
+
+import * as fs from 'node:fs';
+
+export class DiskSpaceChecker {
+  private readonly MIN_DISK_SPACE_BYTES = 1_048_576; // 1MB minimum
+  private readonly DISK_SPACE_CHECK_INTERVAL_MS = 60_000; // Check every 60 seconds
+  private lastDiskSpaceCheck: number = 0;
+  private hasDiskSpace: boolean = true;
+
+  /**
+   * Check if there is sufficient disk space for logging.
+   * Checks are throttled to avoid excessive filesystem operations.
+   */
+  checkDiskSpace(logDir: string): boolean {
+    const now = Date.now();
+    
+    // Only check periodically (every 60 seconds)
+    if (now - this.lastDiskSpaceCheck < this.DISK_SPACE_CHECK_INTERVAL_MS) {
+      return this.hasDiskSpace;
+    }
+    
+    this.lastDiskSpaceCheck = now;
+    
+    try {
+      // fs.statfsSync is cross-platform on Node >=18.15 (incl. Windows), and the
+      // package floor is Node >=22.19, so it is always available — no wmic/exec
+      // fallback is needed (wmic is removed on Windows 11 24H2 anyway).
+      const stats = fs.statfsSync(logDir);
+      const availableBytes = stats.bavail * stats.bsize;
+
+      if (availableBytes < this.MIN_DISK_SPACE_BYTES) {
+        this.hasDiskSpace = false;
+        // Write directly to stderr — this check runs inside the logger itself,
+        // so using the logger here would create a circular dependency.
+        process.stderr.write(
+          `[pi-research] Insufficient disk space for logging: ` +
+          `${Math.round(availableBytes / 1024 / 1024)}MB available, ` +
+          `minimum ${this.MIN_DISK_SPACE_BYTES / 1024 / 1024}MB required\n`
+        );
+      } else {
+        this.hasDiskSpace = true;
+      }
+    } catch (_error) {
+      // On error, assume OK to avoid blocking logging
+      this.hasDiskSpace = true;
+    }
+    
+    return this.hasDiskSpace;
+  }
+}

package/src/utils/error-tracker.ts

@@ -0,0 +1,265 @@
+/**
+ * Error Tracker - Session-Scoped Error Pattern Tracking
+ *
+ * Provides automatic error pattern detection and grouping for research operations.
+ * Session-scoped (in-memory) storage that's cleared between research runs.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Error context information for tracking where errors occur
+ */
+export interface ErrorContext {
+  researchId?: string;
+  mode?: string;
+  component?: string;
+  operation?: string;
+  toolName?: string;
+  phase?: string;
+  sessionId?: string;
+  url?: string;
+  domain?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Error pattern with aggregated information
+ */
+export interface ErrorPattern {
+  signature: string;
+  message: string;
+  count: number;
+  firstSeen: string;
+  lastSeen: string;
+  contexts: ErrorContext[];
+  domainCounts: Map<string, number>;
+}
+
+/**
+ * Complete error report with aggregated statistics
+ */
+export interface ErrorReport {
+  totalErrors: number;
+  uniquePatterns: number;
+  patterns: ErrorPattern[];
+  byDomain: Map<string, number>;
+  byType: Map<string, number>;
+}
+
+// Storage for isolation between concurrent research runs
+const trackerStorage = new AsyncLocalStorage<ErrorTracker>();
+
+/**
+ * Run a function with a specific ErrorTracker bound to the async context.
+ */
+export function runWithTracker<T>(tracker: ErrorTracker, fn: () => T): T {
+  return trackerStorage.run(tracker, fn);
+}
+
+/**
+ * Session-scoped error tracker with pattern detection
+ */
+export class ErrorTracker {
+  private patterns = new Map<string, ErrorPattern>();
+  private readonly MAX_CONTEXTS_PER_PATTERN = 10;
+  // Bound total memory. The global singleton is never clear()'d, so out-of-run errors (logger,
+  // scrapers, healthcheck) would otherwise grow these maps without limit over a long-lived host.
+  private readonly MAX_PATTERNS = 500;
+  private readonly MAX_DOMAINS_PER_PATTERN = 100;
+
+  /**
+   * Normalize an error message to extract a stable signature.
+   * Removes UUIDs, numbers (except HTTP status codes), URLs, and normalizes whitespace.
+   *
+   * @param message - The error message to normalize
+   * @returns A normalized signature for grouping similar errors
+   */
+  public extractSignature(message: string): string {
+    return message
+      // Remove UUIDs (8-4-4-4-12 hex format)
+      .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '<UUID>')
+      // Remove numbers (except HTTP status codes like 200, 301, 302, 403, 404, 500, 503)
+      .replace(/\b(?![12]\d{2}\b|[3-5]\d{2}\b)\d+\b/g, '<NUM>')
+      // Remove URLs
+      .replace(/https?:\/\/[^\s]+/g, '<URL>')
+      // Normalize whitespace to single spaces
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  /**
+   * Track an error with optional context.
+   * Groups similar errors by normalized signature and maintains a rolling buffer of contexts.
+   *
+   * @param error - The error to track (Error object, string message, or unknown)
+   * @param context - Optional context information about where the error occurred
+   */
+  public trackError(error: Error | string | unknown, context: ErrorContext = {}): void {
+    let message: string;
+    
+    if (error instanceof Error) {
+      message = error.message;
+    } else if (typeof error === 'string') {
+      message = error;
+    } else {
+      // Convert unknown error to string
+      message = String(error);
+    }
+    
+    const signature = this.extractSignature(message);
+    const now = new Date().toISOString();
+
+    let pattern = this.patterns.get(signature);
+    if (!pattern) {
+      // Evict the least-frequent pattern before adding a new one at the cap, so the map stays
+      // bounded while retaining the highest-signal (most frequent) patterns.
+      if (this.patterns.size >= this.MAX_PATTERNS) {
+        this.evictLeastFrequentPattern();
+      }
+      pattern = {
+        signature,
+        message,
+        count: 0,
+        firstSeen: now,
+        lastSeen: now,
+        contexts: [],
+        domainCounts: new Map<string, number>(),
+      };
+      this.patterns.set(signature, pattern);
+    }
+
+    pattern.count++;
+    pattern.lastSeen = now;
+
+    // Track domain count if available. Cap distinct domains per pattern: existing domains keep
+    // incrementing, but once at the cap new distinct domains are dropped to bound memory.
+    if (context.domain) {
+      const existing = pattern.domainCounts.get(context.domain);
+      if (existing !== undefined) {
+        pattern.domainCounts.set(context.domain, existing + 1);
+      } else if (pattern.domainCounts.size < this.MAX_DOMAINS_PER_PATTERN) {
+        pattern.domainCounts.set(context.domain, 1);
+      }
+    }
+
+    // Add context to rolling buffer (keep only last 10)
+    pattern.contexts.push(context);
+    if (pattern.contexts.length > this.MAX_CONTEXTS_PER_PATTERN) {
+      pattern.contexts.shift();
+    }
+
+  }
+
+  /**
+   * Generate a complete error report with sorted patterns and domain/type breakdowns.
+   *
+   * @returns An ErrorReport with aggregated error information
+   */
+  public getReport(): ErrorReport {
+    const patterns = Array.from(this.patterns.values());
+    let totalErrors = 0;
+
+    for (const pattern of patterns) {
+      totalErrors += pattern.count;
+    }
+
+    // Sort patterns by frequency (most frequent first)
+    patterns.sort((a, b) => b.count - a.count);
+
+    const byDomain = this.getErrorsByDomain();
+    const byType = this.getErrorsByType();
+
+    return {
+      totalErrors,
+      uniquePatterns: patterns.length,
+      patterns,
+      byDomain,
+      byType,
+    };
+  }
+
+  /**
+   * Group errors by domain from context information.
+   *
+   * @returns A Map of domain names to error counts
+   */
+  public getErrorsByDomain(): Map<string, number> {
+    const totalDomainCounts = new Map<string, number>();
+
+    for (const pattern of this.patterns.values()) {
+      for (const [domain, count] of pattern.domainCounts.entries()) {
+        totalDomainCounts.set(domain, (totalDomainCounts.get(domain) ?? 0) + count);
+      }
+    }
+
+    return totalDomainCounts;
+  }
+
+  /**
+   * Group errors by type (first part of signature before colon or first few words).
+   *
+   * @returns A Map of error types to error counts
+   */
+  public getErrorsByType(): Map<string, number> {
+    const typeCounts = new Map<string, number>();
+
+    for (const pattern of this.patterns.values()) {
+      // Extract type: first part of signature before colon, or first 3 words
+      const parts = pattern.signature.split(':');
+      let type = parts[0]?.trim() ?? 'Unknown';
+      
+      if (type === pattern.signature) {
+        // No colon found, use first 3 words
+        const words = pattern.signature.split(' ');
+        const firstWords = words.slice(0, 3).filter(w => w.length > 0);
+        type = firstWords.length > 0 ? firstWords.join(' ') : 'Unknown';
+      }
+
+      typeCounts.set(type, (typeCounts.get(type) ?? 0) + pattern.count);
+    }
+
+    return typeCounts;
+  }
+
+  /**
+   * Evict the least-frequent pattern to keep the map bounded (see MAX_PATTERNS). O(n) but only
+   * runs when a new signature is added while already at the cap.
+   */
+  private evictLeastFrequentPattern(): void {
+    let victimKey: string | undefined;
+    let victimCount = Infinity;
+    for (const [key, p] of this.patterns) {
+      if (p.count < victimCount) {
+        victimCount = p.count;
+        victimKey = key;
+      }
+    }
+    if (victimKey !== undefined) {
+      this.patterns.delete(victimKey);
+    }
+  }
+
+  /**
+   * Clear all tracked errors (called between research runs).
+   */
+  public clear(): void {
+    this.patterns.clear();
+  }
+}
+
+/**
+ * Global singleton instance that proxies to the context-bound instance if available,
+ * enabling session-scoped error isolation while falling back to a shared global tracker.
+ */
+const globalInstance = new ErrorTracker();
+export const errorTracker: ErrorTracker = new Proxy(globalInstance, {
+  get(target, prop, receiver) {
+    const currentTracker = trackerStorage.getStore() ?? target;
+    const value = Reflect.get(currentTracker, prop, receiver);
+    if (typeof value === 'function') {
+      return value.bind(currentTracker);
+    }
+    return value;
+  }
+});

package/src/utils/host-config.ts

@@ -0,0 +1,45 @@
+/**
+ * Host pi configuration access — resolved LAZILY.
+ *
+ * `@earendil-works/pi-coding-agent` is provided by the host pi process and is
+ * NOT reliably present in this extension's own module-resolution scope when pi
+ * runs the extension (though declared as a regular dependency, it resolves
+ * against the host, not the extension's own `node_modules`). A
+ * top-level `import { CONFIG_DIR_NAME } from '@earendil-works/pi-coding-agent'`
+ * is hoisted and executed on module load, so any *standalone* bundle that
+ * transitively imports such a module — most importantly the poolifier-spawned
+ * `thread-worker.mjs`, which resolves modules relative to its own file and
+ * cannot see pi's global install — crashes with ERR_MODULE_NOT_FOUND before a
+ * single line of its own code runs.
+ *
+ * Resolving the value through this helper instead keeps the host package out of
+ * every module's load-time graph: the `require()` happens on first call, inside
+ * a try/catch, and degrades to pi's own stable default where the host package
+ * is not resolvable (i.e. inside the worker thread).
+ */
+import { createRequire } from 'node:module';
+
+let _configDirName: string | undefined;
+
+/**
+ * The host pi config directory name (e.g. `.pi`).
+ *
+ * Resolution order: explicit env override (`PI_RESEARCH_CONFIG_DIR_NAME`) →
+ * the host `@earendil-works/pi-coding-agent` package (only where it is actually
+ * resolvable, i.e. the main pi process) → the stable default `.pi`.
+ */
+export function getConfigDirName(): string {
+  if (_configDirName !== undefined) return _configDirName;
+  const override = process.env['PI_RESEARCH_CONFIG_DIR_NAME'];
+  if (override) return (_configDirName = override);
+  try {
+    const require = createRequire(import.meta.url);
+    const host = require('@earendil-works/pi-coding-agent') as { CONFIG_DIR_NAME?: string };
+    _configDirName = host.CONFIG_DIR_NAME || '.pi';
+  } catch {
+    // Host package not resolvable in this context (e.g. the browser worker
+    // thread) — fall back to pi's own stable default.
+    _configDirName = '.pi';
+  }
+  return _configDirName;
+}