@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/README.md

@@ -24,12 +24,13 @@ After installation, keep asking Pi normal coding questions. The agent can:
 - **Map an unfamiliar repository** — understand workspaces, packages, entry points, dependencies, and local `CLAUDE.md` or `AGENTS.md` instructions before editing.
 - **Navigate precisely with LSP** — identify the exact symbol at a source location and inspect its type, definition, enclosing declaration, and nearby diagnostics.
 - **Follow relationships across LSP and AST evidence** — find references, implementations, and outgoing calls without guessing from matching text.
-- **Search parsed code structure** — query AST definitions, types, interfaces, classes, methods, enums, imports, exports, and call sites.
+- **Search parsed code structure** — query AST definitions, types, interfaces, classes, methods, enums, imports, exports, and call sites. One owned Structural Worker keeps Pi responsive. Tool cancellation and the shared AST deadline propagate through an atomic cancellation flag into Worker reads, parser progress, and query progress.
+- **Correlate diagnostics** — each public `code_*` call gets one session-local opaque Debug Operation ID. Directly owned workflow, LSP, AST Scan, and Structural Worker events share it without changing normal Tool results.
 - **Check live project health** — inspect language-server status and current errors or warnings, with an option to refresh stale diagnostics.
 - **Refactor safely** — preview language-aware renames and extractions before applying them. Plans are rejected if the files changed in the meantime.
 - **See uncertainty clearly** — results distinguish “nothing found” from incomplete or unavailable analysis and disclose omitted matches.
 
-When Pi recognizes a workspace, the agent also receives an architecture overview near the start of the session, so it can orient before spending turns opening files.
+When Pi recognizes a workspace, the agent also receives a compact architecture overview near the start of the session, so it can orient before spending turns opening files. The overview contains manifest facts (module names, one-line descriptions, declared topology, declared entrypoints, and detected languages), is labeled as untrusted repository evidence, and is controlled by the `code-intelligence.overviewEnabled` setting in `/supi-settings`.
 
 ## Example requests
 
@@ -126,7 +127,7 @@ Open the status view to see detected languages, running or missing servers, and
 /supi-ci-status
 ```
 
-Use `/supi-settings` to disable language servers you do not need or change the instruction filenames surfaced during directory orientation. The defaults are `CLAUDE.md` and `AGENTS.md`.
+Use `/supi-settings` to disable language servers you do not need, change the instruction filenames surfaced during directory orientation (defaults `CLAUDE.md` and `AGENTS.md`), or disable the first-turn architecture overview with `overviewEnabled`.
 
 [workspace-orientation]: https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-code-intelligence/assets/workspace-orientation.png
 [symbol-inspection]: https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-code-intelligence/assets/symbol-inspection.png

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

@@ -22,6 +22,8 @@ Read-only provider methods return `CodeQueryResult<T>`:
 
 This keeps successful zero-result facts distinct from routing, transport, and provider failures.
 
+Semantic and structural provider methods also accept optional `CodeRequestControl` metadata. It contains a caller `AbortSignal`, an absolute Unix-epoch deadline, and an optional opaque Debug Operation ID. Adapters preserve the same object. The ID does not change cancellation semantics. Canonical helpers identify cancellation and deadline expiry across bundled package copies. Cooperative structural substrates apply the control; unsupported substrates can preserve it without applying behavior.
+
 ## License
 
 MIT

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "4.10.0",
+  "version": "6.0.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

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

@@ -9,6 +9,7 @@
 // Capability interfaces and availability states
 export type {
   CapabilityState,
+  CodeRequestControl,
   SemanticProvider,
   StructuralProvider,
   StructuralResult,
@@ -21,6 +22,13 @@ export {
   partialCodeQuery,
   unavailableCodeQuery,
 } from "./query-result.ts";
+export {
+  CodeRequestDeadlineError,
+  isCodeRequestDeadlineError,
+  isCodeRequestInterrupted,
+  isCodeRequestInterruption,
+  throwIfCodeRequestInterrupted,
+} from "./request-control.ts";
 // Shared canonical types
 export type {
   CalleeDepth,
@@ -34,6 +42,7 @@ export type {
   DeclarationNesting,
   DisambiguationCandidate,
   DocumentCodeSymbol,
+  DocumentEditPrecondition,
   ExportData,
   FileEdit,
   ImportData,

package/node_modules/@mrclrchtr/supi-code-runtime/src/capability/types.ts

@@ -43,6 +43,16 @@ export type CapabilityState =
 
 // ── Provider interfaces ────────────────────────────────────────────────
 
+/** Request control that adapters preserve and cooperative providers apply. */
+export interface CodeRequestControl {
+  /** Opaque Debug Operation ID for work directly owned by one public Tool call. */
+  readonly operationId?: string;
+  /** Caller cancellation signal, when one exists. */
+  readonly signal?: AbortSignal;
+  /** Absolute wall-clock deadline in Unix epoch milliseconds. */
+  readonly deadline?: number;
+}
+
 /**
  * Semantic analysis capability backed by a language server (LSP).
  *
@@ -51,16 +61,31 @@ export type CapabilityState =
  * null values are completed observations rather than capability failures.
  */
 export interface SemanticProvider {
-  references(filePath: string, position: CodePosition): Promise<CodeQueryResult<CodeLocation[]>>;
+  references(
+    filePath: string,
+    position: CodePosition,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<CodeLocation[]>>;
   implementation(
     filePath: string,
     position: CodePosition,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<CodeLocation[]>>;
-  documentSymbols(filePath: string): Promise<CodeQueryResult<DocumentCodeSymbol[]>>;
-  workspaceSymbols(query: string): Promise<CodeQueryResult<CodeSymbol[]>>;
+  documentSymbols(
+    filePath: string,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<DocumentCodeSymbol[]>>;
+  workspaceSymbols(
+    query: string,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<CodeSymbol[]>>;
 
   /** Optional definition capability with explicit completed-empty semantics. */
-  definition?(filePath: string, position: CodePosition): Promise<CodeQueryResult<CodeLocation[]>>;
+  definition?(
+    filePath: string,
+    position: CodePosition,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<CodeLocation[]>>;
 
   /**
    * Optional hover capability. A completed `null` data value means the
@@ -69,6 +94,7 @@ export interface SemanticProvider {
   hover?(
     filePath: string,
     position: CodePosition,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<{ contents: string; range?: SourceRange } | null>>;
 
   /**
@@ -79,7 +105,7 @@ export interface SemanticProvider {
    * organize imports, dead-code cleanup, etc.) without exposing that branching
    * to callers.
    */
-  refactor?(request: RefactorRequest): Promise<RefactorResult>;
+  refactor?(request: RefactorRequest, control?: CodeRequestControl): Promise<RefactorResult>;
 
   /**
    * Optional rename capability. When present, the provider supports
@@ -88,7 +114,12 @@ export interface SemanticProvider {
    * This remains a lower-level substrate helper for providers that expose
    * symbol rename independently of their general refactor planner.
    */
-  rename?(file: string, position: CodePosition, newName: string): Promise<RefactorResult>;
+  rename?(
+    file: string,
+    position: CodePosition,
+    newName: string,
+    control?: CodeRequestControl,
+  ): Promise<RefactorResult>;
 
   /**
    * Optional code actions capability. When present, the provider
@@ -96,7 +127,11 @@ export interface SemanticProvider {
    *
    * Kept as a low-level substrate helper and for lightweight introspection.
    */
-  codeActions?(file: string, position: CodePosition): Promise<RefactorResult[]>;
+  codeActions?(
+    file: string,
+    position: CodePosition,
+    control?: CodeRequestControl,
+  ): Promise<RefactorResult[]>;
 }
 
 /**
@@ -111,14 +146,19 @@ export interface StructuralProvider {
     file: string,
     line: number,
     character: number,
-    depth?: CalleeDepth,
+    depthOrOptions?: CalleeDepth | { depth?: CalleeDepth; control?: CodeRequestControl },
   ): Promise<CodeResult<CalleesData>>;
-  exports(file: string): Promise<CodeResult<ExportData[]>>;
-  outline(file: string): Promise<CodeResult<OutlineData[]>>;
-  imports(file: string): Promise<CodeResult<ImportData[]>>;
-  nodeAt(file: string, line: number, character: number): Promise<CodeResult<NodeAtData>>;
+  exports(file: string, control?: CodeRequestControl): Promise<CodeResult<ExportData[]>>;
+  outline(file: string, control?: CodeRequestControl): Promise<CodeResult<OutlineData[]>>;
+  imports(file: string, control?: CodeRequestControl): Promise<CodeResult<ImportData[]>>;
+  nodeAt(
+    file: string,
+    line: number,
+    character: number,
+    control?: CodeRequestControl,
+  ): Promise<CodeResult<NodeAtData>>;
   /** Find all call-site identifiers in a file. Returns name + start line for each match. */
-  callSites(file: string): Promise<CodeResult<CallSite[]>>;
+  callSites(file: string, control?: CodeRequestControl): Promise<CodeResult<CallSite[]>>;
 }
 
 /** Convenience alias for `CodeResult` used in structural contexts. */

package/node_modules/@mrclrchtr/supi-code-runtime/src/request-control.ts

@@ -0,0 +1,47 @@
+import type { CodeRequestControl } from "./capability/types.ts";
+
+/** Error raised when an absolute code-request deadline has elapsed. */
+export class CodeRequestDeadlineError extends Error {
+  constructor() {
+    super("Code request deadline exceeded");
+    this.name = "CodeRequestDeadlineError";
+  }
+}
+
+/** Test whether request cancellation or its absolute deadline has elapsed. */
+export function isCodeRequestInterrupted(
+  control: CodeRequestControl | undefined,
+  now: () => number = Date.now,
+): boolean {
+  return (
+    control?.signal?.aborted === true ||
+    (control?.deadline !== undefined && now() >= control.deadline)
+  );
+}
+
+/** Throw the caller abort reason or a canonical absolute-deadline error. */
+export function throwIfCodeRequestInterrupted(
+  control: CodeRequestControl | undefined,
+  now: () => number = Date.now,
+): void {
+  control?.signal?.throwIfAborted();
+  if (control?.deadline !== undefined && now() >= control.deadline) {
+    throw new CodeRequestDeadlineError();
+  }
+}
+
+/** Identify an absolute-deadline error across bundled package copies. */
+export function isCodeRequestDeadlineError(error: unknown): error is Error {
+  return (
+    error instanceof CodeRequestDeadlineError ||
+    (error instanceof Error && error.name === "CodeRequestDeadlineError")
+  );
+}
+
+/** Identify an error caused by the supplied request control. */
+export function isCodeRequestInterruption(
+  error: unknown,
+  control: CodeRequestControl | undefined,
+): boolean {
+  return isCodeRequestDeadlineError(error) || control?.signal?.aborted === true;
+}

package/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts

@@ -149,11 +149,18 @@ export interface FileEdit {
   newText: string;
 }
 
+/** A document-state precondition established when semantic edits are normalized. */
+export type DocumentEditPrecondition =
+  | { file: string; kind: "open-document-version"; version: number }
+  | { file: string; kind: "disk-content" };
+
 /**
  * A precise workspace edit — one or more file edits to apply atomically.
  */
 export interface WorkspaceEdit {
   edits: FileEdit[];
+  /** Document state that the semantic provider validated before it made this plan. */
+  documentPreconditions?: DocumentEditPrecondition[];
 }
 
 /**
@@ -202,7 +209,12 @@ export interface DisambiguationCandidate {
  * - `unavailable`: refactoring not possible
  */
 export type RefactorResult =
-  | { kind: "precise"; edits: WorkspaceEdit }
+  | {
+      kind: "precise";
+      edits: WorkspaceEdit;
+      /** Provider roots authorized by the semantic route. Consumers canonicalize before storage. */
+      authorizedMutationRoots: string[];
+    }
   | { kind: "ambiguous"; candidates: DisambiguationCandidate[] }
   | { kind: "unavailable"; reason: string };
 

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -28,6 +28,7 @@ pnpm add @mrclrchtr/supi-core
 - `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
 - `loadSupiConfigForScope()` — load one scope at a time for settings UIs
 - `writeSupiConfig()` — persist values
+- `replaceSupiConfigSection()` — replace one nested section while preserving other sections
 - `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
@@ -49,6 +50,7 @@ Config file locations:
 
 - context-provider registry for `/supi-context`
 - debug-event registry and monotonic phase timers for producers that want shared debug capture
+- optional Debug Operation IDs for exact, directly owned public Tool-call correlation; ambient events stay uncorrelated
 - settings registry used by `/supi-settings`
 
 ### Project and session helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.10.0",
+  "version": "6.0.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {
@@ -53,7 +53,7 @@
     "./api": "./src/api.ts",
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
-    "./debug": "./src/debug-registry.ts",
+    "./debug": "./src/debug.ts",
     "./evidence-badge": "./src/evidence-badge.ts",
     "./footer-registry": "./src/footer-registry.ts",
     "./llm": "./src/llm.ts",

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -11,7 +11,7 @@ export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./debug-registry.ts";
+export * from "./debug.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./evidence-badge.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel

package/node_modules/@mrclrchtr/supi-core/src/config/config.ts

@@ -148,6 +148,37 @@ export function writeSupiConfig(
   fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
 }
 
+/**
+ * Replace one complete config section while preserving other sections.
+ *
+ * This is useful for nested settings that must remove stale keys as part of
+ * one update. An empty section is removed from the config file.
+ */
+export function replaceSupiConfigSection(
+  loc: SupiConfigLocation,
+  value: Record<string, unknown>,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+  const existing = readJsonFile(configPath) ?? {};
+
+  if (Object.keys(value).length > 0) existing[loc.section] = value;
+  else delete existing[loc.section];
+
+  const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
+  if (content) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, content, "utf-8");
+    return;
+  }
+
+  try {
+    fs.unlinkSync(configPath);
+  } catch {
+    // File may not exist.
+  }
+}
+
 /**
  * Remove a key from a config section.
  * Used by `interval default` to remove the project override.

package/node_modules/@mrclrchtr/supi-core/src/config.ts

@@ -1,10 +1,12 @@
 // supi-core config domain — config loading.
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
+  getSupiConfigPath,
   loadSupiConfig,
   loadSupiConfigForScope,
   loadSupiConfigSectionForScope,
   readJsonFile,
   removeSupiConfigKey,
+  replaceSupiConfigSection,
   writeSupiConfig,
 } from "./config/config.ts";

package/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -4,9 +4,6 @@
 // supi-debug extension owns policy/configuration and exposes events through a
 // command/tool while this module stays dependency-free for producers.
 
-// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
-export * from "./debug-timing.ts";
-
 export type DebugLevel = "debug" | "info" | "warning" | "error";
 export type DebugAgentAccess = "off" | "sanitized" | "raw";
 export interface DebugRegistryConfig {
@@ -25,6 +22,8 @@ export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
 };
 
 export interface DebugEventInput {
+  /** Opaque identity for events directly owned by one public Tool call. */
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -42,6 +41,8 @@ export interface DebugEvent extends DebugEventInput {
 }
 
 export interface DebugEventQuery {
+  /** Match one exact Debug Operation ID. */
+  operationId?: string;
   source?: string;
   level?: DebugLevel;
   category?: string;
@@ -53,6 +54,7 @@ export interface DebugEventQuery {
 export interface DebugEventView {
   id: number;
   timestamp: number;
+  operationId?: string;
   source: string;
   level: DebugLevel;
   category: string;
@@ -84,6 +86,7 @@ interface DebugRegistryState {
 }
 
 const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-core/debug-registry");
+const DEBUG_OPERATION_ID_RE = /^op-[A-Za-z0-9_-]{21}[AQgw]$/;
 const SECRET_KEY_RE = /(?:token|password|passwd|secret|api[_-]?key|authorization|credential)/i;
 const ENV_SECRET_RE =
   /\b([A-Za-z0-9_]*(?:token|password|passwd|secret|api[_-]?key|authorization|credential)[A-Za-z0-9_]*)=(?:'[^']*'|"[^"]*"|\S+)/gi;
@@ -135,11 +138,17 @@ export function isDebugLevel(value: unknown): value is DebugLevel {
   return value === "debug" || value === "info" || value === "warning" || value === "error";
 }
 
-/** Match a debug event against the supported source, level, and category filters. */
+/** Return whether a value has the exact 16-byte base64url Debug Operation ID form. */
+export function isDebugOperationId(value: unknown): value is string {
+  return typeof value === "string" && DEBUG_OPERATION_ID_RE.test(value);
+}
+
+/** Match a debug event against the supported exact filters. */
 export function matchesDebugEventQuery(
-  event: Pick<DebugEventView, "source" | "level" | "category">,
-  query: Pick<DebugEventQuery, "source" | "level" | "category">,
+  event: Pick<DebugEventView, "operationId" | "source" | "level" | "category">,
+  query: Pick<DebugEventQuery, "operationId" | "source" | "level" | "category">,
 ): boolean {
+  if (query.operationId && event.operationId !== query.operationId) return false;
   if (query.source && event.source !== query.source) return false;
   if (query.level && event.level !== query.level) return false;
   if (query.category && event.category !== query.category) return false;
@@ -197,6 +206,7 @@ function toSanitizedView(event: DebugEvent): DebugEventView {
   return {
     id: event.id,
     timestamp: event.timestamp,
+    operationId: event.operationId,
     source: event.source,
     level: event.level,
     category: event.category,
@@ -216,6 +226,9 @@ export function subscribeDebugEvents(listener: DebugEventListener): () => void {
 /** Record a session-local debug event if debugging is enabled. */
 export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
   const state = getState();
+  if (input.operationId !== undefined && !isDebugOperationId(input.operationId)) {
+    return null;
+  }
   if (!state.config.enabled) {
     return null;
   }

package/node_modules/@mrclrchtr/supi-core/src/debug.ts

@@ -0,0 +1,9 @@
+// Debug domain entry for `@mrclrchtr/supi-core/debug`.
+//
+// Kept separate from debug-registry.ts so debug-timing.ts can import the
+// registry without creating an import cycle through the barrel re-export.
+
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-registry.ts";
+// biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
+export * from "./debug-timing.ts";

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -11,7 +11,7 @@ export * from "./config.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
-export * from "./debug-registry.ts";
+export * from "./debug.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./footer-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel

package/node_modules/@mrclrchtr/supi-core/src/settings/settings-registry.ts

@@ -41,7 +41,10 @@ export interface SettingsApplyResult {
  */
 export interface SettingsModule {
   id: string;
+  /** Human-readable section label shown in the UI. */
   label: string;
+  /** Optional label that groups this module within its section. */
+  subsection?: string;
   read(context: SettingsContext): Promise<SettingsSnapshot>;
   apply(request: SettingsActionRequest): Promise<SettingsApplyResult>;
 }

package/node_modules/@mrclrchtr/supi-lsp/README.md

@@ -16,9 +16,97 @@ This package is library-only. It registers no model-callable tools; `@mrclrchtr/
 npm install @mrclrchtr/supi-lsp
 ```
 
+## Language-server support
+
+The runtime starts an installed server when the project contains a matching file type and, where configured, a root marker. Some built-in servers use extension-based discovery without a root marker. Built-in command names must be on `PATH`; a configured absolute command path is also supported. This table describes diagnostic support, not the full semantic feature set. A push server can still provide hover, definitions, references, symbols, and refactors.
+
+The table records an initialize-handshake audit performed on 2026-08-21 against the locally installed server versions. The handshake is authoritative and can report a different mode after an upgrade; treat rows marked `unverified` as unknown until a probe confirms them. Pull-capability facts come from the official LSP specification (pull diagnostics are a 3.17 feature; 3.18 is the current specification at microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification).
+
+| Language | Server binary | Pull diagnostics (probe) | Built-in SuPi mode | Notes |
+|---|---|---|---|---|
+| TypeScript / JavaScript | `typescript-language-server` 5.3.0 | No (confirmed) | Push | No `diagnosticProvider` in the initialize result. |
+| Python | `pyright-langserver` 1.1.411 | Dynamic-only pull (confirmed) | Pull | No static `diagnosticProvider` in the initialize result; registers `textDocument/diagnostic` dynamically after `initialized`. The #320 handshake inspected only the initialize result and missed the registration. |
+| Rust | `rust-analyzer` 0.0.0 (2026-08-10) | No (confirmed) | Push | No `diagnosticProvider` in the initialize result. |
+| Go | `gopls` v0.23.0 | Conditional (confirmed) | Push | Default is push; `initializationOptions.pullDiagnostics: true` makes gopls advertise `diagnosticProvider`. Keep push while golang/go#70199 stays open; initial pull support tracked in golang/go#53275. gopls v0.23.0 pull reports omit the `kind` discriminator (`""`) and `resultId`; SuPi tolerates the empty-kind full report. |
+| C / C++ | `clangd` 21.0.0 | No (confirmed) | Push | No `diagnosticProvider` in the initialize result. |
+| Ruby | `ruby-lsp` 0.26.10 | No (confirmed) | Push | No `diagnosticProvider`. The server also refuses to start in a project that has a `Gemfile` without a `Gemfile.lock`. |
+| Java | `jdtls` | Unverified | Push | Probe limitation: the wrapper needs a workspace launch configuration; the version probe did not respond. |
+| Kotlin | `kotlin-lsp` LS-262.9593.0 | Static pull (confirmed) | Pull | Statically advertises `diagnosticProvider` in the initialize result, but only when started with `--stdio`; the built-in configuration provides the argument. |
+| Bash | `bash-language-server` 5.6.0 | No (confirmed) | Push | No `diagnosticProvider` in the initialize result. |
+| HTML | `vscode-html-language-server` | No (confirmed) | Push | No `diagnosticProvider` in the initialize result. |
+| SQL | `sql-language-server` 1.7.1 | No (confirmed) | Push | No `diagnosticProvider` in the initialize result. |
+| R | `R` 4.6.1 (languageserver) | No (confirmed) | Push | No `diagnosticProvider` in the initialize result. |
+
+SuPi advertises static and dynamic pull support. It advertises server-requested refresh support too:
+
+- `textDocument.diagnostic.dynamicRegistration: true`
+- `workspace.diagnostics.refreshSupport: true`
+
+A server gets pull diagnostics when it declares a valid `diagnosticProvider` during initialization. A server also gets pull diagnostics after it registers `textDocument/diagnostic`. The pull support stays active until the server removes the registration. SuPi validates registration parameters. Invalid parameters do not enable pull support. SuPi ignores other registration methods.
+
+When a server sends `workspace/diagnostic/refresh`, SuPi returns `null` immediately. It then refreshes the owning client's tracked documents in the background. The refresh covers open, cached, and failed tracked documents. SuPi does not add workspace-wide `workspace/diagnostic` pulls.
+
+Protocol support is separate from the configured mode. A server may support pull diagnostics and still use SuPi's push mode because the built-in configuration does not enable pull mode.
+
+The LSP 3.18 specification adds `Diagnostic.message` markup content, guarded by the client capability `textDocument.diagnostic.markupMessageSupport`; SuPi's validator already accepts plaintext and markdown messages but does not advertise the capability. Other 3.18 features (snippet text edits, inline completion, folding-range refresh, multi-range formatting) are outside the diagnostic surface and are not implemented.
+
+Pull diagnostics use `textDocument/diagnostic`, so the client can tie a report to the current request. Push diagnostics are asynchronous and can omit a document version. After a workspace change, SuPi may report push-only diagnostics as partial or unavailable when it cannot prove that the result matches the current document. It does not treat missing fresh evidence as a clean file.
+
+Unversioned pushes are accepted for an open document when they arrive after the document's sync moment (the client-side instant the `didChange` or `didOpen` that produced them was sent) and are re-stamped with the current synchronization; unversioned pushes for closed or untracked URIs, and pushes that arrive before a sync moment, stay fail-closed. On push-only routes, the first valid publication for a synchronization is tentative. A later valid publication for the same synchronization confirms it, and every publication restarts the quiet period. If no publication arrives, the existing bounded reopen path may ask the server to publish on `didOpen`; a tentative timeout does not reopen that document. In a mixed batch, silent documents can still use the reopen path. Non-empty tentative diagnostics are visible as partial evidence, but they do not enter the confirmed path. An empty tentative publication cannot establish a clean file and stays unavailable until a diagnostic republish arrives. Repeated unchanged queries share the tentative publication's wait age instead of starting a new full wait. A late republish promotes the cache without a new refresh.
+
+Server readiness follows LSP work-done progress: a created progress token is pending and never blocks readiness; an observed `begin` marks active work and makes the client not ready until its `end` or the bounded per-token timeout.
+
+A workspace diagnostic refresh returns exact coverage counts for requested, confirmed, unconfirmed, failed, and removed tracked documents. `code_health` marks tracked-file diagnostics as complete when each requested document is confirmed or known to be removed. It shows non-empty tentative diagnostics as partial entries, reports the same coverage counts in summary and detailed views, and explains when a diagnostic republish is needed. A refresh attempt does not prove fresh evidence by itself. A removed file is reported by the refresh that finds it and is not retained in later tracked-file snapshots.
+
+An explicit recovery pass restarts a push-only client only on a protocol-stall signal (a readiness stall, or repeated JSON-RPC request failures) — never on unconfirmed evidence alone, because the reopen-resync fallback recovers unconfirmed documents without discarding warm server state. It never restarts a pull-capable client because push evidence is absent, and it never restarts a client during passive health display. Each client route restarts at most once per workspace invalidation generation. The replacement process has a fixed startup bound of 5 seconds; exceeding the bound fails closed as start-failed without retry. Recovery telemetry records the outcome, elapsed time, attempted clients, restart count, the bounded server names involved, and the stall signal that triggered a restart, without changing the evidence semantics of the result.
+
+### Optional diagnostic configuration
+
+Configuration overrides merge with the built-in server definitions. Use `.pi/supi/config.json` for one project or `~/.pi/agent/supi/config.json` for all projects:
+
+```json
+{
+  "lsp": {
+    "servers": {
+      "go": {
+        "initializationOptions": {
+          "pullDiagnostics": true
+        }
+      }
+    }
+  }
+}
+```
+
+Gopls pull diagnostics stay opt-in while golang/go#70199 is open; without the option the built-in Go configuration stays in push mode. Kotlin's `--stdio` argument is already part of the built-in configuration and needs no override.
+
+### Custom server configuration
+
+A custom server needs a command and at least one file type:
+
+```json
+{
+  "lsp": {
+    "servers": {
+      "custom": {
+        "command": "custom-lsp",
+        "args": ["--stdio"],
+        "fileTypes": ["custom"],
+        "env": { "CUSTOM_LSP_LOG": "debug" },
+        "initializationOptions": { "mode": "project" }
+      }
+    }
+  }
+}
+```
+
+File types do not include a leading dot. If `rootMarkers` is omitted, the server uses the session root.
+
+The `lsp.enabled` and `lsp.active` settings are deprecated and ignored. Disable one language with `lsp.servers.<language>.enabled: false`. Use `/supi-ci-status` from `@mrclrchtr/supi-code-intelligence` to see detected, running, and missing servers.
+
 ## What it provides
 
-- `LspRuntimeController` for workspace lifecycle and status
+- `LspRuntimeController` for workspace lifecycle, status, and transition subscriptions
 - `WorkspaceLspRuntime` for routing, readiness, semantic operations, tracked files, diagnostics, and recovery
 - explicit ready, pending, inactive, disabled, and unavailable registry states
 - a `SemanticProvider` adapter for `supi-code-runtime`
@@ -33,7 +121,8 @@ Clients, `LspManager`, and the default runtime implementation remain internal.
 - language-server detection and startup
 - shutdown
 - settings and missing-server inventory
-- publishing workspace runtime state
+- publishing workspace runtime state and aggregate lifecycle transitions
+- projecting concrete client readiness into semantic capability state
 
 `WorkspaceLspRuntime` owns:
 
@@ -43,7 +132,21 @@ Clients, `LspManager`, and the default runtime implementation remain internal.
 - diagnostics, summaries, refresh, and recovery
 - project-server inventory and file support checks
 
-This separation keeps lifecycle/status distinct from workspace operations.
+This separation keeps lifecycle and status distinct from workspace operations. Each controller transition has a monotonic generation and an aggregate server snapshot. Semantic capability is ready while at least one concrete client is ready. A crash or late progress event moves capability back to pending only after the final ready client is lost. The ready runtime owner stays available for lazy routing.
+
+### LSP debug telemetry identity
+
+Retained and persisted LSP debug events may identify local workspaces, servers, files, and requests for protocol diagnosis. All LSP producers share one identity vocabulary:
+
+- `cwd` — absolute workspace root (event level)
+- `server` — configured server name, e.g. `typescript`
+- `file` — workspace-relative path
+- `method` — exact LSP method, e.g. `textDocument/hover`
+- `root` — server root, absolute where present
+
+`runtime.transition` events carry `cwd` and a bounded `servers` array (name, status, ready; at most 16 entries) alongside the aggregate counts. `readiness.*` events carry `cwd`, `server`, and `root`; their messages and data never embed raw progress-token values. `request.timing` events carry the exact `method`, `server`, and `cwd`, plus the JSON-RPC error code: the server-reported code for failed requests, and the defined constant `-32095` (`LSP_REQUEST_TIMEOUT_ERROR_CODE`) for local timeouts; cancellations carry no code. `diagnostics.timing` events carry `cwd`, `server`, and a workspace-relative `file` for `sync-file` operations; `refresh-open` stays aggregate. `runtime.recovery` events carry `cwd` and bounded attempted/restarted server names; a cancelled pass records the server names still running at cancellation, while restart identity requires the pass result. `capability.transition` events fire only on semantic ready↔pending transitions and carry `cwd` and the ready state — never for initialize, registration, or unregistration traffic. Code-intelligence events (`code-operation.*`, `workflow.timing`, `ast-scan.timing`) carry `cwd` only.
+
+Identity strings — `cwd`, `server`, `file`, `method`, and `root` — are bounded to 512 UTF-16 code units (marker included; truncation appends `…`) and server lists to 16 entries. No raw protocol dumps, request/response params, diagnostic text, progress tokens, or unbounded file lists are recorded; `openFiles` stays a count. Identity fields are intentionally **not** secret-redacted — the debug registry still redacts secret keys and values, but server names, workspace-relative files, and method names pass through unredacted so local protocol failures stay diagnosable. The supi-debug package documents this disclosure for retained and persisted events.
 
 ## Example
 
@@ -65,6 +168,8 @@ if (state.kind === "ready") {
 
 Runtime methods use raw 0-based LSP positions. `toLspPosition()` converts user-facing 1-based coordinates. Read-only semantic and diagnostic methods return `CodeQueryResult<T>` so completed empty protocol responses remain distinct from partial or unavailable requests. A ready runtime owner may contain only lazy routes: workspace semantic readiness requires at least one active ready client, while file readiness requires the routed client for that file to start successfully. Empty client sets and failed routes are unavailable, not vacuously ready.
 
+Semantic and explicit diagnostic operations accept optional shared `CodeRequestControl` metadata. The semantic adapter preserves the exact value through `WorkspaceLspRuntime`. The signal maps to LSP protocol cancellation (`$/cancelRequest`) and the absolute deadline bounds every request and readiness wait. The opaque Debug Operation ID reaches sanitized request and diagnostic timing events. Ambient readiness, lifecycle, capability, and push-diagnostic events have no Debug Operation ID.
+
 ## Startup performance
 
 Detected servers start concurrently. In a polyglot workspace, disable unneeded languages in `.pi/supi/config.json` or `~/.pi/agent/supi/config.json`:
@@ -110,6 +215,7 @@ See [`docs/adr/0016-workspace-lsp-runtime-interface.md`](../../docs/adr/0016-wor
 - `src/config/` — server configuration and protocol types
 - `src/diagnostics/` — stale diagnostics and workspace sentinels
 - `src/manager/` — package-internal server pool and routing, diagnostic, and recovery mechanics
-- `src/provider/` — semantic and refactor adapters
+- `src/provider/` — semantic, mapping, and refactor adapters
 - `src/session/runtime-controller.ts` — lifecycle/status
-- `src/session/runtime-registry.ts` — `WorkspaceLspRuntime` and registry
+- `src/session/workspace-lsp-runtime.ts` — `WorkspaceLspRuntime` contracts
+- `src/session/runtime-registry.ts` — runtime implementation and registry