feat(vscode): poll every minute until every stack is running

Author: fi3ework

docs/adr/0005-not-installed-recovery-by-polling.md

@@ -18,9 +18,9 @@ The result is not explained by pnpm symlinks: the hoisted core was an ordinary d
 
 The watcher's original rationale was also factually wrong. At Microsoft VS Code commit [`008427a`](https://github.com/microsoft/vscode/commit/008427a901bf4aa79b47f175ccc8da1731750f78), the default `files.watcherExclude` contains only `.git/objects`, `.git/subtree-cache`, and `.hg/store`, each at the root and one directory below; it does not exclude `node_modules` ([`files.contribution.ts:294-310`](https://github.com/microsoft/vscode/blob/008427a901bf4aa79b47f175ccc8da1731750f78/src/vs/workbench/contrib/files/browser/files.contribution.ts#L294-L310)). The failure is the absent pnpm per-file event observed above, not a VS Code default exclude.
 
-**Decision.** The extension shell owns one recursive 10-second timer. It exists only while any live controller's raw folder/project state says dependencies are not installed, enters the shell's existing serialized queue, and forces the same detection notification as a lockfile event even when the detection signature is unchanged. The three stacks reuse their existing dependency-change paths: lint reconciles open documents and refreshes config dependencies, fmt restarts failed folder runtimes in place, and Rstest re-resolves shims and retries failed config evaluation. The timer stops as soon as no not-installed state remains. Lockfile watchers stay as the lower-latency path.
+**Decision.** The extension shell owns one recursive 60-second timer. It exists while any live controller's raw folder/project/runtime state is disabled, crashed or version-mismatched, enters the shell's existing serialized queue, and forces the same detection notification as a lockfile event even when the detection signature is unchanged. The three stacks reuse their existing dependency-change paths: lint reconciles open documents and refreshes failed configs, fmt restarts failed folder runtimes in place, and Rstest re-resolves shims and retries failed config evaluation. The timer stops when no failed state remains (running, starting or idle). Lockfile watchers stay as the lower-latency path.
 
-The aggregate status is deliberately not the predicate: a crash or version mismatch can outrank an unrelated missing folder. Polling continues while any raw state is not installed and stops when none is, including when a retry replaces not-installed with a real config error surfaced in status and Output for the user to fix. Warnings are deduplicated per unresolved episode so a persistent missing install does not add a line every ten seconds. The restart hint remains in the status as an explicit fallback.
+The aggregate status is deliberately not the predicate: every owned raw failure needs recovery. A retry landing mid-install can read half-written `node_modules` and fail with a syntax error instead of a missing dependency. Continuing every minute through that real error makes the transient harmless without a provisional-error heuristic. Real errors still replace not-installed in status and Output; persistent error messages and not-installed warnings are deduplicated so retries do not log every minute. The restart hint remains in the status as an explicit fallback.
 
 fmt has one tool-forced limitation. Restarting `rs fmt --lsp` re-runs package resolution, but the server loads project config lazily on the next formatting request. A poll can therefore move the folder to `running` before config loading has been proved; the next format either succeeds or reports the same config failure and returns the folder to `disabled`, which restarts polling.
 
@@ -35,5 +35,5 @@ fmt has one tool-forced limitation. Restarting `rs fmt --lsp` re-runs package re
 
 - Healthy workspaces incur no polling work. An unresolved workspace retries at most once per timer interval, through the existing serialized shell queue.
 - Recovery no longer depends on installer-specific file events; lockfile watchers remain the faster path when they do fire.
-- A new, real config error replaces not-installed and stops its poll. Fixing that error still uses config events or the explicit restart command.
+- A real config error replaces not-installed without stopping recovery. Config events and the explicit restart command remain available alongside the minute poll.
 - fmt cannot prove config recovery at initialize time. Only a later format producing edits ends its warning episode; empty edits are ambiguous because the server uses them for both no-op formatting and failures whose showMessage may already have been sent.

packages/vscode/AGENTS.md

@@ -9,7 +9,7 @@ One extension replacing the standalone `rstack.rslint` and `rstack.rstest` exten
 - **Tracked upstream state.** `stacks/lint` is synced to web-infra-dev/rslint `packages/vscode-extension` at **39536fd6** (#1617 — per-document core resolution, `CoreResolver` + `RuntimeManager`, `corePath`, PnP removed) and **892482e0** (#1630 — `configPath` on `rslint/configRefresh`). Targeted later ports are **84f9c9b5** (#1967 — languageclient-owned live LSP tracing) and **b7176723** (#1951 — remove legacy JSON config watching); the Unicode BOM E2E comes from **5fc197a5** (#1560), with its native-config fixture shape from **b7176723**. `CoreResolver.ts` / `RuntimeManager.ts` / `WorkspaceDocumentRouter.ts` / `Rslint.ts` are the files to diff when syncing further; record the new commits here when you do.
 - **Ahead of upstream — offer these back when syncing** (bug fixes, not adaptations): (1) `RuntimeManager.reconcile` resolves the document's core **before** sweeping pending uses (`planDocumentCore`), so a reconcile landing on the key a pending start is already producing adopts that start instead of tearing it down mid-`initialize` — the teardown made vscode-languageclient force-notify ("couldn't create connection to server") whenever the register-time pass, a detection change and `didOpen` landed inside one worker startup window (`tests/stacks/lint/runtimeManager.test.ts`). (2) `Rslint.close()` gives a still-Starting language client a bounded chance to settle before tearing down its transport, so a legitimate mid-start close (document closed during start, core key changed) stops cleanly instead of triggering the same force-notified toasts. (3) The registry-harness E2E gives its never-settling startup operation 500ms to begin and accepts only the in-flight timeout message, so a stalled runner cannot satisfy the assertion through the already-expired path (`e2e/lint/suite/registry-harness.test.ts`). (4) `Project.retryFailedConfig()` keeps a failed Rstest project and retries its config evaluation in place with one single-flight promise, so repeated dependency-change passes neither overlap workers nor repeat an unchanged not-installed warning.
 
-- **Targeted Rstest lifecycle port:** `RstestApi.getNormalizedConfig()` closes its worker in `finally`, including rejected config evaluation, matching web-infra-dev/rstest `packages/vscode/src/master.ts` at `d82db4fc31a61ee74b2a74917f14a458e1bca419`. This fixes a leak in our older copy; it is already fixed upstream. Dependency passes retry only projects with a not-installed latch under their core or config-import source; real config errors retain config-edit/restart recovery.
+- **Targeted Rstest lifecycle port:** `RstestApi.getNormalizedConfig()` closes its worker in `finally`, including rejected config evaluation, matching web-infra-dev/rstest `packages/vscode/src/master.ts` at `d82db4fc31a61ee74b2a74917f14a458e1bca419`. This fixes a leak in our older copy; it is already fixed upstream. Dependency passes retry failed projects, including real config errors, while preserving single-flight loading and worker cleanup.
 
 ## The nine adaptations
 
@@ -27,7 +27,7 @@ One extension replacing the standalone `rstack.rslint` and `rstack.rstest` exten
 
 - **Pre-1.0.0 the extension breaks freely.** No compatibility is owed with earlier unpublished states of this extension — settings, command ids and behavior may change without deprecation paths, and dead compat code for them is removed, not kept. No settings migration exists either — not for earlier states of this extension, and not for the two retired standalone extensions (removed in #15; users re-enter their settings under `rstack.*`). Testing and fixtures track only the latest published releases, pinned exactly and bumped by Renovate; a green E2E run speaks only for those releases. `SUPPORT_MATRIX` floors are the minimum versions the extension accepts: each entry is the lowest release evidence shows works with the current code, and its comment records that evidence. Move a floor only when a change makes older releases stop working, never because a devDependency or fixture moved. Raising a floor needs no transition story; the status names the required version.
 - **The three tools are treated uniformly by default.** Detection, dependency-change retry, restart semantics, version gating and status reporting follow one shared pattern across the lint/test/fmt stacks; a stack diverges only when its tool forces it, and the divergence is recorded here as a gotcha. When adding behavior to one stack, first ask whether it belongs to all three. This is about behavior, not code — the upstream copies still must not be deduplicated.
-- **Not installed is a state, not an error — uniformly.** A folder or project whose dependencies are not installed (no `rstack`, no `@rstest/core`, no `@rslint/core`, a config importing a package that is not there) is the normal state of a fresh clone and of scaffolded templates beside their generator (`create-rstack`'s `template-*`, which declare their own dependencies and are never installed). Every stack reports it the same way: a `disabled` status whose reason keeps the restart command as an explicit fallback, one `warn` line per unresolved episode in the output channel without a stack trace, never a `crashed` status and never a notification. The shell owns one 10-second recursive poll while any controller's raw folder/project state is not installed; it enters the existing serialized queue, forces the same detection notification as a lockfile event, and stops when no such state remains (ADR 0005). The words come from one place, `shared/notInstalled.ts` (the `formatVersionMismatch` precedent) — each stack keeps its own status machinery, none its own wording; the restart hint is derived from `stackCommandTitle`, which `tests/extension.test.ts` checks against the manifest. Rstest classifies config-import failures in its worker (`missingDependencyCauseOf`: Node's `code`, a bare package specifier, and for a subpath a walk-up proving the package really is absent) because IPC drops the `code`; Rslint makes the same code-gated decision where its worker still has structured loader results and sends a dedicated verdict to the editor; fmt intercepts only the exact `rs fmt cannot format this workspace:` Error notification and applies the shared message classifier. A typo'd relative import or a missing subpath of an installed package stays a real error in all three.
+- **Not installed is a state, not an error — uniformly.** A folder or project whose dependencies are not installed (no `rstack`, no `@rstest/core`, no `@rslint/core`, a config importing a package that is not there) is the normal state of a fresh clone and of scaffolded templates beside their generator (`create-rstack`'s `template-*`, which declare their own dependencies and are never installed). Every stack reports it the same way: a `disabled` status whose reason keeps the restart command as an explicit fallback, one `warn` line per unresolved episode in the output channel without a stack trace, never a `crashed` status and never a notification. The shell owns one 60-second recursive poll while any controller's raw folder/project/runtime state is disabled, crashed or version-mismatched; it enters the existing serialized queue, forces the same detection notification as a lockfile event, and stops when no failed state remains (ADR 0005). A mid-install retry can read half-written `node_modules` and produce a real syntax error; continuing through failed states makes that transient harmless without a provisional-error heuristic. Real errors remain visible in status and Output, deduplicated by message rather than logged every minute. The words come from one place, `shared/notInstalled.ts` (the `formatVersionMismatch` precedent) — each stack keeps its own status machinery, none its own wording; the restart hint is derived from `stackCommandTitle`, which `tests/extension.test.ts` checks against the manifest. Rstest classifies config-import failures in its worker (`missingDependencyCauseOf`: Node's `code`, a bare package specifier, and for a subpath a walk-up proving the package really is absent) because IPC drops the `code`; Rslint makes the same code-gated decision where its worker still has structured loader results and sends a dedicated verdict to the editor; fmt intercepts only the exact `rs fmt cannot format this workspace:` Error notification and applies the shared message classifier. A typo'd relative import or a missing subpath of an installed package stays a real error in all three.
 - One stack failing to register or crashing must never take another stack (or the shell) down.
 - The shell always activates; per-folder config detection decides which stacks start, and re-runs on config/lockfile changes without a window reload. The per-stack enable settings are coarse kill switches only.
 - Reconciles and restarts share one serialized queue (`enqueue`); a reconcile leaves a live stack alone, so the restart path — the commands, and the full pass any relevant settings change triggers — is the only thing that rebuilds one. Do not add a second queue.

packages/vscode/src/extension.ts

@@ -28,7 +28,7 @@ const STACK_FACTORIES: Readonly<Record<StackId, StackControllerFactory>> = {
 /** Stacks that run project-loading children on the shared User Node runtime. */
 const USER_NODE_STACKS: readonly StackId[] = ['rslint', 'rstest', 'fmt'];
 
-const DEFAULT_DEPENDENCY_POLL_INTERVAL_MS = 10_000;
+const DEFAULT_DEPENDENCY_POLL_INTERVAL_MS = 60_000;
 
 const errorMessage = (error: unknown): string =>
   error instanceof Error ? (error.stack ?? error.message) : String(error);
@@ -229,14 +229,14 @@ class ExtensionShell {
     return (
       !this.#disposed &&
       [...this.#controllers.values()].some((controller) =>
-        controller.hasNotInstalledState(),
+        controller.hasFailedState(),
       )
     );
   }
 
   /**
    * Starts one recursive timer only while a live controller owns a
-   * not-installed state. The timer enters the same shell queue as every
+   * failed state. The timer enters the same shell queue as every
    * reconcile/restart, then sends the same forced detection event as a
    * lockfile change; each stack therefore reuses its existing retry path.
    */

packages/vscode/src/stacks/fmt/index.ts

@@ -163,6 +163,7 @@ class FmtFolderRuntime {
   #configPath: string | undefined;
   readonly #packageEpisode = new NotInstalledEpisode();
   readonly #configDependencyEpisode = new NotInstalledEpisode();
+  #startError: string | undefined;
   suppressedShowMessages = 0;
   #closing = false;
   #disposed = false;
@@ -451,9 +452,17 @@ class FmtFolderRuntime {
           error instanceof Error ? error.message : String(error)
         }`,
       );
-      context.output.error('Failed to start the rs fmt language server', error);
+      const message = error instanceof Error ? error.message : String(error);
+      if (this.#startError !== message) {
+        this.#startError = message;
+        context.output.error(
+          'Failed to start the rs fmt language server',
+          error,
+        );
+      }
       return;
     }
+    this.#startError = undefined;
     context.output.info(`rs fmt language server started for ${folderRoot}`);
   }
 
@@ -804,9 +813,9 @@ class FmtController implements StackController {
     );
   }
 
-  hasNotInstalledState(): boolean {
-    return [...this.#runtimes.values()].some(
-      (runtime) => runtime.state === 'disabled',
+  hasFailedState(): boolean {
+    return [...this.#runtimes.values()].some((runtime) =>
+      isFailedFmtState(runtime.state),
     );
   }
 

packages/vscode/src/stacks/lint/Rslint.ts

@@ -324,6 +324,7 @@ export class Rslint implements Disposable {
   private advisory: string | undefined;
   private readonly configDependencyEpisode = new NotInstalledEpisode();
   private configRefreshFailed = false;
+  private configError: string | undefined;
   private startPromise: Promise<void> | undefined;
   private startOperation: Promise<void> | undefined;
   private clientStartPromise: Promise<void> | undefined;
@@ -378,11 +379,15 @@ export class Rslint implements Disposable {
       this.configRefreshFailed = true;
       this.report({ kind: 'crashed', detail: notification.message });
       this.configDependencyEpisode.clear();
-      this.logger.error(
-        `Failed to refresh config discovery: ${notification.message}`,
-      );
+      if (this.configError !== notification.message) {
+        this.configError = notification.message;
+        this.logger.error(
+          `Failed to refresh config discovery: ${notification.message}`,
+        );
+      }
       return;
     }
+    this.configError = undefined;
     const wasFailed = this.configRefreshFailed;
     this.configRefreshFailed = false;
     if (notification.kind === 'ok') {
@@ -715,7 +720,8 @@ export class Rslint implements Disposable {
   }
 
   public retryConfigDependency(): Promise<void> | undefined {
-    if (!this.hasConfigDependencyFailure()) return undefined;
+    if (!this.hasConfigDependencyFailure() && !this.configRefreshFailed)
+      return undefined;
     return this.requestConfigRefresh('dependency-change');
   }
 

packages/vscode/src/stacks/lint/index.ts

@@ -193,10 +193,13 @@ class RslintController implements StackController {
           // lints, so its consequence says what it keeps, not "will not".
           const missing = missingPackageOf(error);
           const status = statusForRslintStartFailure(error);
+          const attributed = resolved
+            ? attributeToCore(status, resolved.installation.packageDirectory)
+            : status;
+          const previous = this.#folderStates
+            .get(folderKeyOf(workspaceFolder))
+            ?.failures.get(document.uri.toString());
           if (missing !== undefined) {
-            const previous = this.#folderStates
-              .get(folderKeyOf(workspaceFolder))
-              ?.failures.get(document.uri.toString());
             if (
               previous?.kind !== 'disabled' ||
               previous.reason !==
@@ -210,7 +213,12 @@ class RslintController implements StackController {
               );
               logger.warn(warning);
             }
-          } else {
+          } else if (
+            previous?.kind !== attributed.kind ||
+            !('detail' in previous) ||
+            !('detail' in attributed) ||
+            previous.detail !== attributed.detail
+          ) {
             logger.error(
               formatCoreSelectionFailure(document.uri.toString(), keeping),
               error,
@@ -224,9 +232,7 @@ class RslintController implements StackController {
             folderKeyOf(workspaceFolder),
             'failures',
             document.uri.toString(),
-            resolved
-              ? attributeToCore(status, resolved.installation.packageDirectory)
-              : status,
+            attributed,
           );
         },
         onDocumentSettled: (document) => {
@@ -400,10 +406,13 @@ class RslintController implements StackController {
     );
   }
 
-  hasNotInstalledState(): boolean {
+  hasFailedState(): boolean {
     return [...this.#folderStates.values()].some((states) =>
       [...states.runtimes.values(), ...states.failures.values()].some(
-        (state) => state.kind === 'disabled',
+        (state) =>
+          state.kind === 'disabled' ||
+          state.kind === 'crashed' ||
+          state.kind === 'version-mismatch',
       ),
     );
   }

packages/vscode/src/stacks/test/index.ts

@@ -556,8 +556,8 @@ class RstestController implements StackController {
     return this.#rstest.buildExports();
   }
 
-  hasNotInstalledState(): boolean {
-    return status.hasNotInstalled();
+  hasFailedState(): boolean {
+    return status.hasFailed();
   }
 
   dispose(): void {