@mrclrchtr/supi-code-intelligence 5.0.0 → 6.0.0

package/README.md

@@ -30,7 +30,7 @@ After installation, keep asking Pi normal coding questions. The agent can:
 - **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
 
@@ -127,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/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "5.0.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/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 {

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-lsp/README.md

@@ -37,17 +37,26 @@ The table records an initialize-handshake audit performed on 2026-08-21 against
 | 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 (`textDocument.diagnostic.dynamicRegistration: true`). A server that declares a valid `diagnosticProvider` in its initialize result gets pull diagnostics; a server that registers `textDocument/diagnostic` after initialization gets pull diagnostics for as long as its registration stays active. Registration parameters are validated and malformed values reject the request without enabling pull. Other registration methods are ignored. Protocol support is separate from the configured mode: a server may support pull yet stay in SuPi's push mode because the built-in configuration does not enable it.
+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, a document still unconfirmed after the settle window is closed and reopened over the protocol so the server publishes on `didOpen` (clean files get no push on `didChange` at all). The reopen keeps the cache entry and version history intact and does not restart the server.
+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 only when every document in the requested scope has confirmed evidence. It keeps cached diagnostics as partial evidence and shows the same coverage counts in summary and detailed views; a refresh attempt does not prove fresh evidence by itself.
+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.
 
@@ -71,6 +80,28 @@ Configuration overrides merge with the built-in server definitions. Use `.pi/sup
 
 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

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "5.0.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-lsp/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-lsp/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 {

package/node_modules/@mrclrchtr/supi-lsp/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-lsp/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-lsp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "Language Server Protocol runtime for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,8 @@
     "vscode-jsonrpc": "^9.0.0",
     "vscode-languageserver-protocol": "^3.18.0",
     "vscode-languageserver-types": "^3.18.0",
-    "@mrclrchtr/supi-code-runtime": "5.0.0",
-    "@mrclrchtr/supi-core": "5.0.0"
+    "@mrclrchtr/supi-code-runtime": "6.0.0",
+    "@mrclrchtr/supi-core": "6.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

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

@@ -8,7 +8,16 @@ export {
   hasDeprecatedLspKeys,
   loadLspSettings,
 } from "./config/lsp-settings.ts";
-export { clearTsconfigCache } from "./config/tsconfig-scope.ts";
+export {
+  clearTsconfigCache,
+  type FileScopeDecision,
+  type FileScopeStatus,
+  getFileScopeDecision,
+  invalidateTsconfigCacheForConfig,
+  invalidateTsconfigCacheForConfigDir,
+  isProjectConfigFileName,
+  type ScopeDecisionBasis,
+} from "./config/tsconfig-scope.ts";
 export type {
   CodeAction,
   Diagnostic,
@@ -28,6 +37,7 @@ export type {
 } from "./config/types.ts";
 export { FileChangeType } from "./config/types.ts";
 export { toLspPosition, toOneBasedPosition } from "./coordinates.ts";
+export { TENTATIVE_PUSH_UNAVAILABLE_REASON } from "./diagnostics/evidence.ts";
 export { isLikelyStaleDiagnostic } from "./diagnostics/stale-diagnostics.ts";
 export {
   scanWorkspaceSentinels,
@@ -50,6 +60,7 @@ export type {
   RecoverDiagnosticsResult,
   RoutedMutationResponse,
   SemanticReadinessResult,
+  WorkspaceDiagnosticReport,
   WorkspaceDiagnosticSnapshot,
   WorkspaceDiagnosticSummaryEntry,
   WorkspaceLspDiagnosticSurface,

package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-cache.ts

@@ -2,6 +2,7 @@ import type { PublishDiagnosticsParams } from "../config/types.ts";
 import { uriToFile } from "../utils.ts";
 import {
   type DiagnosticCacheEntry,
+  isTentativePushEntry,
   isValidPublishDiagnosticsParams,
 } from "./client-diagnostic-evidence.ts";
 import type { ClientDiagnosticSnapshot, OpenDocumentState } from "./client-document-state.ts";
@@ -20,27 +21,44 @@ interface ApplyPushOptions {
 }
 
 /**
- * Apply one valid push publication and return whether it can release current waiters.
+ * Apply one valid push publication.
  *
- * Fail-closed policy (ADR 0020): unversioned pushes are rejected for closed
- * and untracked URIs and for arrivals before the URI's sync moment; versioned
- * pushes for a URI closed by a lifecycle operation are rejected because their
- * version cannot be verified. An unversioned push that arrives after the sync
- * moment of an open document is accepted and re-stamped with that document's
- * current synchronization state.
+ * Returns whether the publication was accepted and whether it promoted a
+ * tentative entry to confirmed. Fail-closed policy (ADR 0020): unversioned
+ * pushes are rejected for closed and untracked URIs and for arrivals before
+ * the URI's sync moment; versioned pushes for a URI closed by a lifecycle
+ * operation are rejected because their version cannot be verified. An
+ * unversioned push that arrives after the sync moment of an open document
+ * is accepted and re-stamped with that document's current synchronization
+ * state. The first valid publication for a synchronization is tentative; a
+ * later valid publication for the same synchronization ID and evidence
+ * revision promotes the cache to confirmed (ADR 0021).
  */
-export function applyPushDiagnostics(options: ApplyPushOptions): boolean {
-  if (!isValidPublishDiagnosticsParams(options.params)) return false;
+export function applyPushDiagnostics(options: ApplyPushOptions): {
+  accepted: boolean;
+  promoted: boolean;
+} {
+  if (!isValidPublishDiagnosticsParams(options.params)) return { accepted: false, promoted: false };
   const openDocument = options.openDocuments.get(options.params.uri);
   if (options.params.version !== undefined) {
-    if (!Number.isInteger(options.params.version)) return false;
-    if (openDocument && options.params.version !== openDocument.version) return false;
-    if (!openDocument && options.closedVersionedBarrier) return false;
+    if (!Number.isInteger(options.params.version)) return { accepted: false, promoted: false };
+    if (openDocument && options.params.version !== openDocument.version) {
+      return { accepted: false, promoted: false };
+    }
+    if (!openDocument && options.closedVersionedBarrier)
+      return { accepted: false, promoted: false };
   }
-  if (!Array.isArray(options.params.diagnostics)) return false;
-  if (!acceptUnversionedPush(options, openDocument)) return false;
-  options.store.set(options.params.uri, buildPushCacheEntry(options, openDocument));
-  return true;
+  if (!Array.isArray(options.params.diagnostics)) return { accepted: false, promoted: false };
+  if (!acceptUnversionedPush(options, openDocument)) return { accepted: false, promoted: false };
+  const entry = buildPushCacheEntry(options, openDocument);
+  const previous = options.store.get(options.params.uri);
+  const promoted =
+    entry.source === "push" &&
+    entry.publications !== undefined &&
+    entry.publications >= 2 &&
+    isTentativePushEntry(previous);
+  options.store.set(options.params.uri, entry);
+  return { accepted: true, promoted };
 }
 
 /** Gate one unversioned push publication against the sync-moment policy. */
@@ -69,13 +87,27 @@ function buildPushCacheEntry(
 ): DiagnosticCacheEntry {
   const currentRevision = openDocument?.evidenceRevision === options.evidenceRevision;
   const unversioned = options.params.version === undefined && openDocument !== undefined;
+  const synchronizationId =
+    unversioned || currentRevision ? openDocument?.synchronizationId : undefined;
+  const evidenceRevision = openDocument?.evidenceRevision;
+  const previous = options.store.get(options.params.uri);
+  // A later valid publication for the same synchronization ID and evidence
+  // revision continues the entry's publication count: a confirmed pull
+  // entry keeps the synchronization confirmed, and a tentative push entry
+  // is promoted. Any other publication starts a fresh count.
+  const sameSynchronization =
+    synchronizationId !== undefined &&
+    previous?.synchronizationId === synchronizationId &&
+    previous.evidenceRevision === evidenceRevision;
+  const publications = sameSynchronization ? Math.min((previous.publications ?? 1) + 1, 2) : 1;
   return {
     diagnostics: options.params.diagnostics,
     receivedAt: Date.now(),
     source: "push",
-    synchronizationId: unversioned || currentRevision ? openDocument?.synchronizationId : undefined,
-    evidenceRevision: openDocument?.evidenceRevision,
+    synchronizationId,
+    evidenceRevision,
     version: options.params.version,
+    publications,
   };
 }
 
@@ -119,17 +151,18 @@ function collectOpenDocumentFreshness(options: {
   const uris = new Set<string>();
   for (const [uri, document] of options.openDocuments) {
     uris.add(uri);
+    const entry = options.store.get(uri);
     const fileState = getDiagnosticFileState(uriToFile(uri));
-    const current = hasCurrentDiagnosticEvidence(
-      document,
-      options.store.get(uri),
-      options.evidenceRevision,
-    );
+    const current = hasCurrentDiagnosticEvidence(document, entry, options.evidenceRevision);
     const failed = options.failedDocuments.has(uri);
+    // A current tentative push maps to unconfirmed, not to a new public
+    // status: it matches the synchronization but cannot confirm it yet, so
+    // it must not claim current snapshot or document state (issue #351).
+    const tentative = current && isTentativePushEntry(entry);
     documents.push({
       uri,
-      current: fileState === "present" && current && !failed,
-      status: statusForDocument(fileState, current, failed),
+      current: fileState === "present" && current && !failed && !tentative,
+      status: statusForDocument(fileState, current, failed, tentative),
     });
   }
   return { documents, uris };
@@ -174,10 +207,12 @@ function statusForDocument(
   fileState: ReturnType<typeof getDiagnosticFileState>,
   current: boolean,
   failed: boolean,
+  tentative: boolean,
 ): "confirmed" | "unconfirmed" | "failed" | "removed" {
   if (fileState === "removed") return "removed";
   if (fileState === "unreadable" || failed) return "failed";
-  return current ? "confirmed" : "unconfirmed";
+  if (tentative || !current) return "unconfirmed";
+  return "confirmed";
 }
 
 function collectCachedDiagnostics(options: {
@@ -197,9 +232,13 @@ function collectCachedDiagnostics(options: {
       entry,
       options.evidenceRevision,
     );
-    current &&= entryCurrent;
+    // A current tentative error is useful partial evidence. Keep its entry
+    // non-current so it cannot establish a clean or settled result (ADR 0021).
+    const tentative = entryCurrent && isTentativePushEntry(entry);
+    const confirmed = entryCurrent && !tentative;
+    current &&= confirmed;
     if (entry.diagnostics.length > 0) {
-      entries.push({ uri, diagnostics: entry.diagnostics, current: entryCurrent });
+      entries.push({ uri, diagnostics: entry.diagnostics, current: confirmed });
     }
   }
   return { entries, current };

package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-collection.ts

@@ -3,10 +3,12 @@ import {
   type CodeRequestControl,
   completedCodeQuery,
   isCodeRequestInterruption,
+  partialCodeQuery,
   throwIfCodeRequestInterrupted,
   unavailableCodeQuery,
 } from "@mrclrchtr/supi-code-runtime/api";
 import type { Diagnostic } from "../config/types.ts";
+import { TENTATIVE_PUSH_UNAVAILABLE_REASON } from "../diagnostics/evidence.ts";
 import {
   type DiagnosticSynchronization,
   incompleteDiagnosticResult,
@@ -25,6 +27,8 @@ interface FileDiagnosticCollectionOptions {
   readonly waiters: DiagnosticWaitRegistry;
   readonly current: () => boolean;
   readonly freshPush: () => boolean;
+  /** Receive time of a current tentative push that is already cached. */
+  readonly currentPushReceivedAt: () => number | undefined;
   readonly diagnostics: () => Diagnostic[];
   readonly pullDiagnostics: (timeoutMs: number, signal: AbortSignal) => Promise<boolean>;
   /** Observe the push wait outcome without finishing the observer; the caller finishes once. */
@@ -58,22 +62,75 @@ export async function collectSynchronizedFileDiagnostics(
     return completedCodeQuery(options.diagnostics());
   }
 
-  const push = await options.waiters.waitForPush(
-    options.request.uri,
-    Math.max(0, options.maxWaitMs - (Date.now() - options.syncStart)),
-    control,
-  );
+  const push = await waitForConfirmedPush(options, control);
   if (options.onPushWait) options.onPushWait(push);
   else options.observer.pushWaitCompleted(1, push);
-  if (push === "published" && options.freshPush()) {
+  if (push === "published") {
     return completedCodeQuery(options.diagnostics());
   }
+  if (push === "tentative") {
+    // A current tentative error is useful partial evidence, but an empty
+    // publication cannot establish that the document is clean (ADR 0021).
+    const diagnostics = options.diagnostics();
+    return diagnostics.length > 0
+      ? partialCodeQuery(diagnostics, TENTATIVE_PUSH_UNAVAILABLE_REASON)
+      : unavailableCodeQuery(TENTATIVE_PUSH_UNAVAILABLE_REASON);
+  }
   return incompleteDiagnosticResult(
     options.cachedDiagnostics,
     push === "released" ? "released" : "timed-out",
   );
 }
 
+/**
+ * Wait until a confirmed push publication settles the synchronization.
+ *
+ * Every accepted publication releases the waiter. A confirmed push ends the
+ * wait as "published". A publication that stays tentative (no republish
+ * arrived for the same synchronization) ends as "tentative" when the budget
+ * expires. A wait with no publication at all keeps the waiter's
+ * "timed-out", and a lifecycle release stays "released".
+ */
+async function waitForConfirmedPush(
+  options: FileDiagnosticCollectionOptions,
+  control?: CodeRequestControl,
+): Promise<DiagnosticPushWaitOutcome> {
+  // A tentative publication may already sit in the cache when the wait
+  // starts (ADR 0021). Do not grant repeated callers a new full wait window:
+  // bound them by the first operation window or the cached publication age.
+  const initialPushReceivedAt = options.currentPushReceivedAt();
+  const waitDeadline = Math.min(
+    options.syncStart + options.maxWaitMs,
+    initialPushReceivedAt === undefined
+      ? Number.POSITIVE_INFINITY
+      : initialPushReceivedAt + options.maxWaitMs,
+  );
+  let observedPublication = initialPushReceivedAt !== undefined;
+  for (;;) {
+    throwIfCodeRequestInterrupted(control);
+    // A republish can arrive after the previous wait released but before the
+    // next waiter registers; re-check the store on every loop pass.
+    if (options.freshPush()) return "published";
+    const push = await options.waiters.waitForPush(
+      options.request.uri,
+      Math.max(0, waitDeadline - Date.now()),
+      control,
+    );
+    // A lifecycle release ends the wait definitively: a tentative
+    // publication observed earlier must not reclassify the release.
+    if (push === "released") return "released";
+    // A promotion can land while the timed-out waiter tears down; the cache
+    // must complete the wait before the timeout classifies the outcome.
+    if (options.freshPush()) return "published";
+    if (push === "timed-out") {
+      return observedPublication || options.currentPushReceivedAt() !== undefined
+        ? "tentative"
+        : "timed-out";
+    }
+    observedPublication = true;
+  }
+}
+
 async function collectPullEvidence(
   options: FileDiagnosticCollectionOptions,
   control?: CodeRequestControl,

package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-evidence.ts

@@ -163,6 +163,25 @@ export interface DiagnosticCacheEntry {
   evidenceRevision?: number;
   version?: number;
   resultId?: string;
+  /**
+   * Valid publications observed for the entry's synchronization. The first
+   * valid publication for a synchronization is tentative; a later valid
+   * publication promotes the entry to confirmed (ADR 0021). A confirmed
+   * pull entry counts as the first publication when a push continues the
+   * same synchronization, so that push keeps the confirmation. Pull
+   * entries as such carry no count and are confirmed on arrival.
+   */
+  publications?: number;
+}
+
+/**
+ * Test whether one push entry is still tentative for its synchronization.
+ *
+ * A pull entry confirms on arrival; a push entry confirms only after a
+ * later valid publication for the same synchronization (ADR 0021).
+ */
+export function isTentativePushEntry(entry: DiagnosticCacheEntry | undefined): boolean {
+  return Boolean(entry && entry.source === "push" && (entry.publications ?? 1) < 2);
 }
 
 /** One document synchronization that needs current diagnostic evidence. */
@@ -204,6 +223,7 @@ export function hasFreshPush(
   const entry = store.get(synchronization.uri);
   return Boolean(
     entry?.source === "push" &&
+      !isTentativePushEntry(entry) &&
       entry.synchronizationId === synchronization.synchronizationId &&
       (synchronization.evidenceRevision === undefined ||
         entry.evidenceRevision === synchronization.evidenceRevision) &&
@@ -211,8 +231,11 @@ export function hasFreshPush(
   );
 }
 
-/** Test whether pull or push evidence confirms the supplied synchronization. */
-export function hasFreshEvidence(
+/**
+ * Test whether stored evidence matches a synchronization without a
+ * confirmation gate. A tentative push matches here but cannot confirm.
+ */
+export function hasCurrentEvidence(
   store: ReadonlyMap<string, DiagnosticCacheEntry>,
   synchronization: DiagnosticSynchronization,
   currentEvidenceRevision?: number,
@@ -227,8 +250,26 @@ export function hasFreshEvidence(
   );
 }
 
-/** Return the latest cache update that confirms one of the synchronizations. */
-export function latestFreshEvidenceReceivedAt(
+/** Test whether pull or push evidence confirms the supplied synchronization. */
+export function hasFreshEvidence(
+  store: ReadonlyMap<string, DiagnosticCacheEntry>,
+  synchronization: DiagnosticSynchronization,
+  currentEvidenceRevision?: number,
+): boolean {
+  return (
+    hasCurrentEvidence(store, synchronization, currentEvidenceRevision) &&
+    !isTentativePushEntry(store.get(synchronization.uri))
+  );
+}
+
+/**
+ * Return the latest cache update that matches one of the synchronizations.
+ *
+ * Every accepted publication restarts the settle quiet period, tentative
+ * publications included, so this helper does not apply the confirmation
+ * gate (ADR 0021).
+ */
+export function latestCurrentEvidenceReceivedAt(
   store: ReadonlyMap<string, DiagnosticCacheEntry>,
   synchronizations: DiagnosticSynchronization[],
   currentEvidenceRevision?: number,
@@ -236,7 +277,7 @@ export function latestFreshEvidenceReceivedAt(
   let latest = 0;
   for (const synchronization of synchronizations) {
     const entry = store.get(synchronization.uri);
-    if (hasFreshEvidence(store, synchronization, currentEvidenceRevision)) {
+    if (hasCurrentEvidence(store, synchronization, currentEvidenceRevision)) {
       latest = Math.max(latest, entry?.receivedAt ?? 0);
     }
   }

package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-host.ts

@@ -9,6 +9,7 @@ export interface ClientDiagnosticsHost {
   cwd?: string;
   isOperational(): boolean;
   supportsPullDiagnostics(): boolean;
+  usesIncrementalDocumentSync(): boolean;
   sendNotification(method: string, params: unknown): void;
   pullDocumentDiagnostics(request: DiagnosticPullRequest): Promise<DocumentDiagnosticReport | null>;
 }