@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/node_modules/@mrclrchtr/supi-lsp/src/session/{service-registry.ts → runtime-registry.ts}

@@ -1,12 +1,16 @@
-// Shared session-scoped LSP service registry.
-// Peer extensions can import `getSessionLspService` from the package root
-// to reuse the active LSP runtime without starting duplicate servers.
+// Shared session-scoped LSP service registry reused by peer extensions.
 
+import {
+  type CodeQueryResult,
+  mapCodeQueryResult,
+  unavailableCodeQuery,
+} from "@mrclrchtr/supi-code-runtime/api";
 import { createSessionStateRegistry } from "@mrclrchtr/supi-core/session";
 import type {
   CodeAction,
   Diagnostic,
   DocumentSymbol,
+  FileEvent,
   Hover,
   Location,
   LocationLink,
@@ -19,11 +23,16 @@ import type {
 } from "../config/types.ts";
 import type { LspManager } from "../manager/manager.ts";
 import { resolveSessionPath } from "../utils.ts";
+import { raceReadinessValue } from "./readiness.ts";
 
 function isRange(value: Position | Range): value is Range {
   return "start" in value && "end" in value;
 }
 
+function unavailableFileQuery<T>(operation: string, file: string): CodeQueryResult<T> {
+  return unavailableCodeQuery(`No routed LSP client could complete ${operation} for ${file}.`);
+}
+
 /** Workspace diagnostic summary grouped by file. */
 export interface WorkspaceDiagnosticSummaryEntry {
   file: string;
@@ -43,7 +52,8 @@ export interface OutstandingDiagnosticSummaryEntry {
 
 /** Result from a workspace diagnostic recovery pass. */
 export interface RecoverDiagnosticsResult {
-  refreshedClients: number;
+  /** Active clients targeted by the best-effort refresh, not confirmed successful refreshes. */
+  attemptedClients: number;
   restartedClients: number;
   staleAssessment: {
     suspected: boolean;
@@ -52,9 +62,9 @@ export interface RecoverDiagnosticsResult {
   };
 }
 
-export type SessionLspServiceState =
-  | { kind: "ready"; service: SessionLspService }
-  | { kind: "inactive"; service: SessionLspService }
+export type WorkspaceLspRuntimeState =
+  | { kind: "ready"; runtime: WorkspaceLspRuntime }
+  | { kind: "inactive"; runtime: WorkspaceLspRuntime }
   | { kind: "pending" }
   | { kind: "disabled" }
   | { kind: "unavailable"; reason: string };
@@ -65,59 +75,116 @@ export type SemanticReadinessResult =
   | { kind: "unavailable"; reason: string };
 
 /**
- * Public wrapper around {@link LspManager} that exposes stable semantic operations.
+ * Workspace-scoped LSP interface that owns routing, readiness, semantic operations,
+ * diagnostics, and recovery without exposing clients or the mutable manager.
  * File path inputs may be absolute or session-cwd-relative; a leading `@` is stripped
  * to match pi's built-in path-tool convention. Position arguments use raw 0-based LSP
  * coordinates; use `toLspPosition()` from `@mrclrchtr/supi-lsp/api` when starting from
  * user-facing 1-based line and character values.
  */
-export class SessionLspService {
+export interface WorkspaceLspRuntime {
+  hover(filePath: string, position: Position): Promise<CodeQueryResult<Hover | null>>;
+  definition(
+    filePath: string,
+    position: Position,
+  ): Promise<CodeQueryResult<Location | Location[] | LocationLink[] | null>>;
+  references(filePath: string, position: Position): Promise<CodeQueryResult<Location[]>>;
+  implementation(
+    filePath: string,
+    position: Position,
+  ): Promise<CodeQueryResult<Location | Location[] | LocationLink[] | null>>;
+  documentSymbols(
+    filePath: string,
+  ): Promise<CodeQueryResult<DocumentSymbol[] | SymbolInformation[]>>;
+  workspaceSymbol(query: string): Promise<CodeQueryResult<SymbolInformation[] | WorkspaceSymbol[]>>;
+  rename(filePath: string, position: Position, newName: string): Promise<WorkspaceEdit | null>;
+  codeActions(filePath: string, positionOrRange: Position | Range): Promise<CodeAction[] | null>;
+  /** Succeeds only when the concrete routed client exists and is query-ready. */
+  waitUntilReadyForFile(
+    filePath: string,
+    options?: { timeoutMs?: number },
+  ): Promise<SemanticReadinessResult>;
+  /** Succeeds only when at least one concrete workspace client is active and query-ready. */
+  waitUntilReadyForWorkspace(options?: { timeoutMs?: number }): Promise<SemanticReadinessResult>;
+  getProjectServers(): ProjectServerInfo[];
+  isSupportedSourceFile(filePath: string): boolean;
+  trackFile(filePath: string): Promise<boolean>;
+  closeFile(filePath: string): void;
+  pruneMissingFiles(): readonly string[];
+  noteWorkspaceChanges(changes: FileEvent[]): void;
+  fileDiagnostics(filePath: string, maxSeverity?: number): Promise<CodeQueryResult<Diagnostic[]>>;
+  refreshOpenDiagnostics(options?: { maxWaitMs?: number; quietMs?: number }): Promise<void>;
+  getWorkspaceDiagnosticSummary(): WorkspaceDiagnosticSummaryEntry[];
+  getOutstandingDiagnostics(
+    maxSeverity?: number,
+  ): Array<{ file: string; diagnostics: Diagnostic[] }>;
+  getOutstandingDiagnosticSummary(maxSeverity?: number): OutstandingDiagnosticSummaryEntry[];
+  recoverDiagnostics(options?: {
+    restartIfStillStale?: boolean;
+    maxWaitMs?: number;
+    quietMs?: number;
+  }): Promise<RecoverDiagnosticsResult>;
+}
+
+class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
   constructor(private readonly manager: LspManager) {}
 
+  static createOwner(manager: LspManager) {
+    const runtime = new DefaultWorkspaceLspRuntime(manager);
+    return { runtime: runtime as WorkspaceLspRuntime, shutdown: () => runtime.#shutdown() };
+  }
+
   // ── Semantic lookups ────────────────────────────────────────────────
 
-  async hover(filePath: string, position: Position): Promise<Hover | null> {
+  async hover(filePath: string, position: Position): Promise<CodeQueryResult<Hover | null>> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
-    if (!client) return null;
+    if (!client) return unavailableFileQuery("hover", resolvedPath);
     return client.hover(resolvedPath, position);
   }
 
   async definition(
     filePath: string,
     position: Position,
-  ): Promise<Location | Location[] | LocationLink[] | null> {
+  ): Promise<CodeQueryResult<Location | Location[] | LocationLink[] | null>> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
-    if (!client) return null;
+    if (!client) return unavailableFileQuery("definition", resolvedPath);
     return client.definition(resolvedPath, position);
   }
 
-  async references(filePath: string, position: Position): Promise<Location[] | null> {
+  async references(filePath: string, position: Position): Promise<CodeQueryResult<Location[]>> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
-    if (!client) return null;
-    return client.references(resolvedPath, position);
+    if (!client) return unavailableFileQuery("references", resolvedPath);
+    return mapCodeQueryResult(
+      await client.references(resolvedPath, position),
+      (data) => data ?? [],
+    );
   }
 
   async implementation(
     filePath: string,
     position: Position,
-  ): Promise<Location | Location[] | LocationLink[] | null> {
+  ): Promise<CodeQueryResult<Location | Location[] | LocationLink[] | null>> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
-    if (!client) return null;
+    if (!client) return unavailableFileQuery("implementation", resolvedPath);
     return client.implementation(resolvedPath, position);
   }
 
-  async documentSymbols(filePath: string): Promise<DocumentSymbol[] | SymbolInformation[] | null> {
+  async documentSymbols(
+    filePath: string,
+  ): Promise<CodeQueryResult<DocumentSymbol[] | SymbolInformation[]>> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath);
-    if (!client) return null;
-    return client.documentSymbols(resolvedPath);
+    if (!client) return unavailableFileQuery("document symbols", resolvedPath);
+    return mapCodeQueryResult(await client.documentSymbols(resolvedPath), (data) => data ?? []);
   }
 
-  async workspaceSymbol(query: string): Promise<SymbolInformation[] | WorkspaceSymbol[] | null> {
+  async workspaceSymbol(
+    query: string,
+  ): Promise<CodeQueryResult<SymbolInformation[] | WorkspaceSymbol[]>> {
     return this.manager.workspaceSymbol(query);
   }
 
@@ -167,7 +234,18 @@ export class SessionLspService {
       };
     }
 
-    return raceReadiness(this.manager.waitUntilFileReady(resolvedPath), options.timeoutMs);
+    const readiness = await raceReadinessValue(
+      this.manager.waitUntilFileReady(resolvedPath),
+      options.timeoutMs,
+    );
+    if (readiness.kind !== "resolved") return readiness;
+    if (readiness.value === null) {
+      return {
+        kind: "unavailable",
+        reason: "The routed LSP client could not be started for this file",
+      };
+    }
+    return { kind: "ready" };
   }
 
   /**
@@ -177,11 +255,20 @@ export class SessionLspService {
   async waitUntilReadyForWorkspace(
     options: { timeoutMs?: number } = {},
   ): Promise<SemanticReadinessResult> {
-    return raceReadiness(this.manager.waitUntilWorkspaceReady(), options.timeoutMs);
+    const readiness = await raceReadinessValue(
+      this.manager.waitUntilWorkspaceReady(),
+      options.timeoutMs,
+    );
+    if (readiness.kind !== "resolved") return readiness;
+    if (readiness.value === 0) {
+      return {
+        kind: "unavailable",
+        reason: "No active LSP clients are ready for this workspace",
+      };
+    }
+    return { kind: "ready" };
   }
 
-  // ── Project / runtime awareness ─────────────────────────────────────
-
   getProjectServers(): ProjectServerInfo[] {
     return this.manager.getKnownProjectServers([]);
   }
@@ -191,15 +278,51 @@ export class SessionLspService {
     return this.manager.canServeFile(this.resolveFilePath(filePath));
   }
 
-  // ── Diagnostics ─────────────────────────────────────────────────────
+  /** Track a file in its routed client without exposing that client. */
+  async trackFile(filePath: string): Promise<boolean> {
+    const resolvedPath = this.resolveFilePath(filePath);
+    return (await this.manager.ensureFileOpen(resolvedPath)) !== null;
+  }
+
+  /** Stop tracking a file and clear its cached diagnostics. */
+  closeFile(filePath: string): void {
+    this.manager.closeFile(this.resolveFilePath(filePath));
+  }
+
+  /** Remove missing files from runtime tracking. */
+  pruneMissingFiles(): readonly string[] {
+    return this.manager.pruneMissingFiles();
+  }
+
+  /** Notify routed clients of workspace file changes and reset pull state. */
+  noteWorkspaceChanges(changes: FileEvent[]): void {
+    this.manager.clearAllPullResultIds();
+    this.manager.notifyWorkspaceFileChanges(changes);
+  }
+
+  async #shutdown(): Promise<void> {
+    await this.manager.shutdownAll();
+  }
+
+  // ── Diagnostics and recovery ────────────────────────────────────────
 
   /** Sync a file through LSP and return diagnostics up to the supplied severity threshold. */
-  async fileDiagnostics(filePath: string, maxSeverity: number = 4): Promise<Diagnostic[] | null> {
+  async fileDiagnostics(
+    filePath: string,
+    maxSeverity: number = 4,
+  ): Promise<CodeQueryResult<Diagnostic[]>> {
     const resolvedPath = this.resolveFilePath(filePath);
-    if (!this.manager.canServeFile(resolvedPath)) return null;
+    if (!this.manager.canServeFile(resolvedPath)) {
+      return unavailableFileQuery("diagnostics", resolvedPath);
+    }
     return this.manager.syncFileAndGetDiagnostics(resolvedPath, maxSeverity);
   }
 
+  /** Re-sync every open document and wait for diagnostics to settle. */
+  async refreshOpenDiagnostics(options?: { maxWaitMs?: number; quietMs?: number }): Promise<void> {
+    await this.manager.refreshOpenDiagnostics(options);
+  }
+
   /** Get a lightweight workspace diagnostic summary for all tracked files. */
   getWorkspaceDiagnosticSummary(): WorkspaceDiagnosticSummaryEntry[] {
     return this.manager.getDiagnosticSummary();
@@ -231,51 +354,20 @@ export class SessionLspService {
   }
 }
 
-// ── Registry ──────────────────────────────────────────────────────────
+export function createWorkspaceLspRuntimeOwner(manager: LspManager) {
+  return DefaultWorkspaceLspRuntime.createOwner(manager);
+}
 
 const WAIT_INTERVAL_MS = 25;
-const DEFAULT_SEMANTIC_READY_TIMEOUT_MS = 15_000;
-const registry = createSessionStateRegistry<SessionLspServiceState>("supi-lsp/session-registry");
-
-async function raceReadiness(
-  readiness: Promise<unknown>,
-  timeoutMs: number | undefined,
-): Promise<SemanticReadinessResult> {
-  const effectiveTimeoutMs = timeoutMs ?? DEFAULT_SEMANTIC_READY_TIMEOUT_MS;
-  let timer: ReturnType<typeof setTimeout> | null = null;
-
-  try {
-    await Promise.race([
-      readiness,
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(
-          () => reject(new Error("semantic-readiness-timeout")),
-          effectiveTimeoutMs,
-        );
-      }),
-    ]);
-    return { kind: "ready" };
-  } catch (error) {
-    if (timer) clearTimeout(timer);
-    if (error instanceof Error && error.message === "semantic-readiness-timeout") {
-      return { kind: "timeout" };
-    }
-    return {
-      kind: "unavailable",
-      reason: error instanceof Error ? error.message : String(error),
-    };
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
-}
+const registry = createSessionStateRegistry<WorkspaceLspRuntimeState>("supi-lsp/session-registry");
 
 /** Publish the LSP service state for a session cwd. */
-export function setSessionLspServiceState(cwd: string, state: SessionLspServiceState): void {
+export function setWorkspaceLspRuntimeState(cwd: string, state: WorkspaceLspRuntimeState): void {
   registry.set(cwd, state);
 }
 
 /** Acquire the LSP service state for a session cwd. */
-export function getSessionLspService(cwd: string): SessionLspServiceState {
+export function getWorkspaceLspRuntime(cwd: string): WorkspaceLspRuntimeState {
   return (
     registry.get(cwd) ?? {
       kind: "unavailable",
@@ -285,22 +377,22 @@ export function getSessionLspService(cwd: string): SessionLspServiceState {
 }
 
 /** Wait briefly for a pending session-scoped LSP service to become ready. */
-export async function waitForSessionLspService(
+export async function waitForWorkspaceLspRuntime(
   cwd: string,
   timeoutMs: number = 250,
-): Promise<SessionLspServiceState> {
+): Promise<WorkspaceLspRuntimeState> {
   const deadline = Date.now() + Math.max(0, timeoutMs);
-  let state = getSessionLspService(cwd);
+  let state = getWorkspaceLspRuntime(cwd);
 
   while (state.kind === "pending" && Date.now() < deadline) {
     await new Promise((resolve) => setTimeout(resolve, WAIT_INTERVAL_MS));
-    state = getSessionLspService(cwd);
+    state = getWorkspaceLspRuntime(cwd);
   }
 
   return state;
 }
 
 /** Remove the LSP service state for a session cwd. */
-export function clearSessionLspService(cwd: string): void {
+export function clearWorkspaceLspRuntime(cwd: string): void {
   registry.clear(cwd);
 }

package/node_modules/@mrclrchtr/supi-tree-sitter/README.md

@@ -29,6 +29,7 @@ This package provides the parser-backed structural substrate consumed by `@mrclr
 - an owned parsing session API for direct library consumers
 - a `StructuralProvider` adapter published through `./provider/tree-sitter-provider`
 - structural extraction helpers for outline/import/export/node/callee/call-site analysis inside the library surface
+- operation-specific extension discovery through `getStructuralSearchSupportedExtensions()`
 
 It does **not** register pi tools or commands on its own.
 
@@ -49,6 +50,8 @@ Coordinates in the library APIs use **1-based** line and character columns. Char
 - R (`.r`)
 - SQL (`.sql`)
 
+Parser support is broader than extractor support. Outline, import, and export collection currently support JavaScript/TypeScript-family grammars. Call-site collection supports every listed family except HTML and SQL. Consumers performing a bulk structural scan should use `getStructuralSearchSupportedExtensions(operation)` rather than treating every parseable extension as eligible.
+
 ## Architecture
 
 `@mrclrchtr/supi-tree-sitter` is the **structural substrate** in SuPi's
@@ -101,6 +104,7 @@ if (state.kind === "ready") {
 - `src/index.ts` — re-export surface
 - `src/session/runtime.ts` — parser and query runtime
 - `src/session/session.ts` — runtime-backed service helpers and owned session API
+- `src/operation-support.ts` — authoritative operation-specific extension support
 - `src/session/service-registry.ts` — shared session-scoped structural service registry
 - `src/provider/tree-sitter-provider.ts` — `StructuralProvider` adapter consumed by `@mrclrchtr/supi-code-intelligence`
 - `src/tool/outline.ts`, `src/tool/imports.ts`, `src/tool/exports.ts`, `src/tool/node-at.ts`, `src/tool/callees.ts`, `src/tool/call-sites.ts` — structural analyses exposed through the library surface

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/README.md

@@ -8,6 +8,14 @@ This is a **library-only package** — it has no pi extension surface, no user-f
 
 - `@mrclrchtr/supi-code-runtime/api` — shared canonical types, capability interfaces, workspace runtime registry, and typed request context
 
+Read-only provider methods return `CodeQueryResult<T>`:
+
+- `completed` — collection completed; `data` may be empty or `null`
+- `partial` — usable data was collected, but one or more provider branches failed
+- `unavailable` — no result was established; includes a reason
+
+This keeps successful zero-result facts distinct from routing, transport, and provider failures.
+
 ## License
 
 MIT

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -48,13 +48,8 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "@types/node": "25.9.5",
-    "vitest": "4.1.10"
-  },
   "main": "src/api.ts",
   "exports": {
-    "./abort-utils": "./src/abort-utils.ts",
     "./api": "./src/api.ts",
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
@@ -75,7 +70,6 @@
     "./status-spinner": "./src/status-spinner.ts",
     "./terminal": "./src/terminal.ts",
     "./tool-framework": "./src/tool-framework.ts",
-    "./prompt-surface": "./src/prompt-surface.ts",
-    "./types": "./src/types.ts"
+    "./prompt-surface": "./src/prompt-surface.ts"
   }
 }

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -6,8 +6,6 @@
 // For lighter imports, use one of the domain subpaths directly
 // (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./abort-utils.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
@@ -42,5 +40,3 @@ export * from "./status-spinner.ts";
 export * from "./terminal.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./tool-framework.ts";
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./types.ts";

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/evidence-badge.ts

@@ -22,14 +22,15 @@ export interface EvidenceBadgeInput {
  * |------------------------------------------------------|---------------------------------------|
  * | shown=12, total=12, omitted=0, label="references"   | `12 references`                       |
  * | shown=8,  total=20, omitted=12, label="symbols"     | `8 of 20 symbols (12 omitted)`        |
- * | shown=5,  total=null, reason="timeout", label="matches" | `5 matches — timeout`              |
+ * | shown=5, total=null, omitted=2, reason="timeout" | `5 matches (2 collected omitted; more may exist — timeout)` |
  */
 export function formatEvidenceBadge(input: EvidenceBadgeInput): string {
   const { shownCount, totalCount, omittedCount, partialReason, label } = input;
 
   if (totalCount === null) {
     const reasonSuffix = partialReason ? ` — ${partialReason}` : "";
-    return `${shownCount} ${label}${reasonSuffix}`;
+    const omittedPrefix = (omittedCount ?? 0) > 0 ? `${omittedCount} collected omitted; ` : "";
+    return `${shownCount} ${label} (${omittedPrefix}more may exist${reasonSuffix})`;
   }
 
   if (omittedCount !== null && omittedCount > 0) {

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -6,8 +6,6 @@
 // For lighter imports, use one of the domain subpaths directly
 // (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./abort-utils.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
@@ -36,5 +34,3 @@ export * from "./status-spinner.ts";
 export * from "./terminal.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./tool-framework.ts";
-// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./types.ts";

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/llm.ts

@@ -24,16 +24,6 @@ export interface WithRetryOptions {
   onRetry?: (attempt: number, delayMs: number) => void;
 }
 
-/**
- * Attempt an async operation with retries and exponential backoff.
- *
- * If the signal is already aborted on entry, the operation is skipped entirely.
- * If the signal aborts during a delay, the delay is cancelled immediately.
- *
- * @param fn - The async operation to retry.
- * @param options - Optional configuration for retries, backoff, signal, and callbacks.
- * @returns The result on success, or `null` if all attempts fail or the signal aborts.
- */
 /**
  * Create a promise that resolves after `ms` milliseconds, or rejects if
  * the signal fires before the timeout elapses.

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/path-utils.ts

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 /** Strip pi's optional leading `@` file-path prefix from a tool input. */
 export function stripToolPathPrefix(target: string): string {
@@ -16,25 +17,28 @@ export function resolveToolPath(cwd: string, target: string): string {
   return path.resolve(cwd, stripToolPathPrefix(target));
 }
 
-/** Convert a file path to a file:// URI. */
+/**
+ * Convert a file path to a file:// URI.
+ *
+ * Uses Node's `pathToFileURL` to produce a standards-compliant URI with
+ * proper percent-encoding of spaces, hashes, and other special characters.
+ */
 export function fileToUri(filePath: string): string {
-  const resolved = path.resolve(filePath);
-  if (process.platform === "win32") {
-    return `file:///${resolved.replace(/\\/g, "/")}`;
-  }
-  return `file://${resolved}`;
+  return pathToFileURL(filePath).href;
 }
 
-/** Convert a file:// URI to a file path. */
+/**
+ * Convert a file:// URI to a file path.
+ *
+ * Uses Node's `fileURLToPath` for standards-compliant decoding. Non-file
+ * URIs are passed through unchanged so consumers (such as LSP diagnostic
+ * handling) remain compatible with non-file URI schemes.
+ */
 export function uriToFile(uri: string): string {
   if (!uri.startsWith("file://")) return uri;
-  let filePath = decodeURIComponent(uri.slice(7));
-  if (
-    process.platform === "win32" &&
-    filePath.startsWith("/") &&
-    /^[A-Za-z]:/.test(filePath.slice(1))
-  ) {
-    filePath = filePath.slice(1);
+  try {
+    return fileURLToPath(uri);
+  } catch {
+    return uri;
   }
-  return filePath;
 }

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/settings/settings-action-menu.ts

@@ -34,6 +34,7 @@ export function buildActionMenu(field: ScopedFieldValue, scope: SettingsScope):
     if (choices.length > 0) {
       for (const choice of choices) menu.push({ value: `set:${choice}`, label: choice });
     } else if (field.field.kind === "number") menu.push({ value: "edit", label: "Edit value…" });
+    else if (field.field.kind === "string") menu.push({ value: "edit", label: "Edit value…" });
     else if (field.field.kind === "stringList") menu.push({ value: "edit", label: "Edit values…" });
     else if (field.field.kind === "modelPicker")
       menu.push({ value: "edit", label: "Choose model…" });

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/settings/settings-schema.ts

@@ -86,6 +86,11 @@ export interface NumberField extends BaseField {
   values?: string[];
 }
 
+/** One free-form string. */
+export interface StringField extends BaseField {
+  kind: "string";
+}
+
 /** Comma-separated string list. */
 export interface StringListField extends BaseField {
   kind: "stringList";
@@ -164,6 +169,7 @@ export type SettingsField =
   | BoolField
   | EnumField
   | NumberField
+  | StringField
   | StringListField
   | ModelPickerField
   | CustomField;
@@ -248,6 +254,8 @@ export function formatValue(value: unknown, field: SettingsField): string {
       return value ? "on" : "off";
     case "number":
       return String(value ?? "");
+    case "string":
+      return typeof value === "string" && value ? value : "none";
     case "stringList": {
       const arr = Array.isArray(value) ? value : [];
       return arr.length > 0 ? arr.map(String).join(", ") : "none";
@@ -271,6 +279,7 @@ export function sourceBadge(displayValue: string, source: ValueSource): string {
 
 /** Format the value used to prefill editors and compare concrete choices. */
 export function formatEditValue(value: unknown, field: SettingsField): string {
+  if (field.kind === "string") return typeof value === "string" ? value : "";
   if (field.kind === "stringList") {
     const arr = Array.isArray(value) ? value : [];
     return arr.map(String).join(", ");

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/settings.ts

@@ -26,6 +26,7 @@ export type {
   SettingsField,
   SettingsFieldAction,
   SettingsPersistedChange,
+  StringField,
   StringListField,
   ValueSource,
 } from "./settings/settings-schema.ts";

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "description": "SuPi code-runtime — shared workspace context, capability contracts, and canonical types for the code-understanding stack",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "3.2.0"
+    "@mrclrchtr/supi-core": "4.1.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"