impel-cli 0.17.9 → 0.17.11

package/bin/impel.js

@@ -1,5 +1,16 @@
 #!/usr/bin/env node
 import { main } from "../src/cli.js";
+import { ensureWindowsStableEntrypointQuietly } from "../src/stableEntrypoint.js";
+
+// Every real impel process starts here — including vendor-driven token/MCP/
+// hook invocations and the post-update `_converge` cascade (which only spawns
+// after postInstallCliVersion verified the install). Refreshing the stable
+// Windows entry point first therefore guarantees managed artifacts always
+// point at a shim that resolves a working install. Global installs only:
+// checkout runs never repoint the machine-wide shim (see stableEntrypoint.js).
+if (process.platform === "win32" && process.env.IMPEL_SKIP_ENTRYPOINT_REFRESH !== "1") {
+  ensureWindowsStableEntrypointQuietly();
+}
 
 main(process.argv.slice(2)).catch((err) => {
   console.error(`impel: ${err?.stack || err?.message || err}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.17.9",
+  "version": "0.17.11",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/src/apps.js

@@ -207,7 +207,9 @@ export function managedAppIdentity(target, tenantId = null, tenantName = null) {
 
 // Bump when the written config/manifest schema changes; a mismatch forces the
 // slow open path (and thus a full config rewrite) after a CLI update.
-export const CURRENT_CONFIG_VERSION = 18;
+// 19: Windows global installs bake the stable %LOCALAPPDATA% entry point into
+// hook/auth/MCP artifacts instead of the npm-prefix bin path.
+export const CURRENT_CONFIG_VERSION = 19;
 
 // Identifies the bundle-BUILDING logic — the asar patches, plist rewrites,
 // helper rebranding, and signing. A vendored bundle is rebuilt only when this
@@ -1119,8 +1121,10 @@ function writeChatGPTConfig(
   const auth = invocations?.auth || { command: paths.tokenHelper, args: null };
   // Finder/Dock-launched apps inherit a minimal PATH without npm/nvm bin
   // directories, so a PATH-relative "impel" never spawns there. Bake the
-  // absolute node + CLI invocation; the launch-time `app refresh` rewrites
-  // this config whenever those paths change.
+  // absolute node + CLI invocation (on Windows global installs the stable
+  // %LOCALAPPDATA% entry point, which survives npm's non-atomic package
+  // replacement); the launch-time `app refresh` rewrites this config whenever
+  // those paths change.
   const mcpInvocation = impelCliInvocation(
     config.tenantId ? ["mcp", "--tenant", config.tenantId] : ["mcp"]
   );

package/src/commands/apps.js

@@ -623,6 +623,23 @@ export async function cmdWindowsApps(argv, overrides = {}) {
 
   try {
     if (action === "open") maybePrintUpdateNotice();
+    // Background token-helper refreshes pass --stale-only; honor the manifest
+    // TTL here like the darwin refresh path does, so every vendor token call
+    // does not become a full catalog fetch + profile rewrite (and its child
+    // process fan-out) on Windows.
+    if (action === "refresh" && flags["stale-only"]) {
+      const stored = loadConfig();
+      if (stored?.pat) {
+        const staleTenantId = flags.tenant
+          ? normalizeTenantId(flags.tenant)
+          : stored.tenantId || null;
+        const stalePaths = appPaths(io.homeDir, staleTenantId, {
+          claudeUserData: io.claudeUserData(io.environment, staleTenantId),
+          tenantName: staleTenantId === stored.tenantId ? stored.tenantName : null,
+        });
+        if (manifestIsFresh(stalePaths, stored)) return true;
+      }
+    }
     const config = await io.selectedConfig(targets, flags.tenant || null);
     const catalog = await withProgress("Fetching the tenant model catalog", () => (
       fetchWindowsCatalog(config, io)

package/src/commands/converge.js

@@ -79,9 +79,22 @@ export async function cmdConverge(argv = [], overrides = {}) {
       return false;
     }
     const label = target === "claude" ? "Claude" : "ChatGPT/Codex";
-    const allowed = confirmed(await io.promptText(
-      `Allow the verified ${label} vendor ${context.mode === "update" ? "update" : "installation"}? [y/N] `,
-    ));
+    // Decline by default after 60s: an unanswered prompt in a forgotten
+    // terminal must not park the whole convergence (with its child processes
+    // and any background respawns) indefinitely. The prompt says so, and the
+    // question is re-asked on the next explicit run. The timer is cleared on
+    // answer (not unref'd) so the auto-decline reliably fires even when the
+    // prompt is the only thing keeping the event loop alive.
+    const allowed = confirmed(await new Promise((resolve) => {
+      const timer = setTimeout(() => resolve(""), io.vendorPromptTimeoutMs ?? 60_000);
+      const settle = (answer) => {
+        clearTimeout(timer);
+        resolve(answer);
+      };
+      Promise.resolve(io.promptText(
+        `Allow the verified ${label} vendor ${context.mode === "update" ? "update" : "installation"}? [y/N] (auto-N in 60s) `,
+      )).then(settle, () => settle(""));
+    }));
     vendorAppDecisions.set(target, allowed);
     return allowed;
   };

package/src/commands/nuke.js

@@ -16,6 +16,7 @@ import { CONFIG_DIR } from "../config.js";
 import { parseFlags } from "../args.js";
 import { promptText } from "../prompt.js";
 import { appProcessPattern } from "../apps.js";
+import { windowsStableEntrypointRoot } from "../selfInvocation.js";
 import { windowsClaudeUserData } from "../windowsApps.js";
 
 // Launcher artifacts the CLI may have written into ~/Applications: the
@@ -121,6 +122,10 @@ function windowsProfileRemnants(appsRoot, environment) {
       // Windows vendor install absent; nothing tenant-scoped to remove.
     }
   }
+  // The stable entry point (%LOCALAPPDATA%\Impel) that managed vendor
+  // artifacts execute; a clean reinstall rewrites it on the next impel run.
+  const entrypointRoot = windowsStableEntrypointRoot(environment);
+  if (entrypointRoot && fs.existsSync(entrypointRoot)) remnants.push(entrypointRoot);
   return remnants;
 }
 
@@ -182,7 +187,7 @@ export async function cmdNuke(argv = [], overrides = {}) {
   if (launchers.length) io.log(`  App launchers and staging artifacts: ${launchers.length}`);
   if (libraryRemnants.length) io.log(`  macOS caches/preferences/state entries: ${libraryRemnants.length}`);
   if (keychainItems.length) io.log(`  Keychain Safe Storage items: ${keychainItems.length}`);
-  if (windowsRemnants.length) io.log(`  Windows managed Claude profiles: ${windowsRemnants.length}`);
+  if (windowsRemnants.length) io.log(`  Windows managed profiles and entry point: ${windowsRemnants.length}`);
   if (configDirExists) io.log(`  CLI state, profiles, vendor cache, and auth: ${io.configDir}`);
   io.log("Vendor apps and native ~/.claude and ~/.codex profiles are not touched.");
 

package/src/commands/sessions.js

@@ -1,7 +1,16 @@
 import { spawn } from "node:child_process";
 
 import { parseFlags } from "../args.js";
-import { collectSessionHook, flushCollectedSession, readHookInput, sessionOutboxStatus } from "../sessionCollector.js";
+import {
+  clearSessionFlushLock,
+  collectSessionHook,
+  flushCollectedSession,
+  readHookInput,
+  sessionFlushLockIsFresh,
+  sessionFlushLockPath,
+  sessionOutboxStatus,
+  touchSessionFlushLock,
+} from "../sessionCollector.js";
 import { loadConfig, redactSecretText } from "../config.js";
 import { impelCliInvocation } from "../selfInvocation.js";
 
@@ -57,11 +66,21 @@ export async function cmdSessions(argv) {
         flush: false,
       });
       if (config && (config.tenantId === flags.tenant || process.env.IMPEL_SESSIONS_DEV_ORG_ID)) {
-        startDetachedFlush({
+        // Hooks fire on every session event; only spawn a flush child when no
+        // live one is already polling this session's outbox (heartbeat lock).
+        const lock = sessionFlushLockPath({
+          tenantId: flags.tenant,
           provider: flags.provider,
-          tenant: flags.tenant,
-          session: String(input.session_id || ""),
+          sessionKey: String(input.session_id || ""),
         });
+        if (!sessionFlushLockIsFresh(lock)) {
+          touchSessionFlushLock(lock);
+          startDetachedFlush({
+            provider: flags.provider,
+            tenant: flags.tenant,
+            session: String(input.session_id || ""),
+          });
+        }
       }
     } catch (error) {
       // Session persistence is observational. A collector outage must never
@@ -83,16 +102,28 @@ export async function cmdSessions(argv) {
     if (!flags.provider || !flags.session || !flags.tenant) return;
     if (!["claude_code", "codex"].includes(flags.provider)) return;
     if (!config || flags.tenant !== config.tenantId && !process.env.IMPEL_SESSIONS_DEV_ORG_ID) return;
+    const lock = sessionFlushLockPath({
+      tenantId: flags.tenant,
+      provider: flags.provider,
+      sessionKey: flags.session,
+    });
     const deadline = Date.now() + 90_000;
-    while (Date.now() < deadline) {
-      const result = await flushCollectedSession({
-        tenantId: flags.tenant,
-        provider: flags.provider,
-        sessionKey: flags.session,
-        config,
-      });
-      if (result.pending === 0) break;
-      await new Promise((resolve) => setTimeout(resolve, result.error || result.busy ? 1000 : 250));
+    try {
+      while (Date.now() < deadline) {
+        // Refresh the heartbeat so hook dispatch keeps skipping extra spawns
+        // while this child is alive.
+        touchSessionFlushLock(lock);
+        const result = await flushCollectedSession({
+          tenantId: flags.tenant,
+          provider: flags.provider,
+          sessionKey: flags.session,
+          config,
+        });
+        if (result.pending === 0) break;
+        await new Promise((resolve) => setTimeout(resolve, result.error || result.busy ? 1000 : 250));
+      }
+    } finally {
+      clearSessionFlushLock(lock);
     }
     return;
   }

package/src/commands/update.js

@@ -1,6 +1,7 @@
 // `impel update` — update the CLI, then let the freshly installed build
 // reconcile every tenant and managed surface from the live control-plane list.
 
+import fs from "node:fs";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -20,6 +21,21 @@ import {
 
 const CLI_BIN = fileURLToPath(new URL("../../bin/impel.js", import.meta.url));
 
+/**
+ * The version now on disk at the package that owns CLI_BIN, read FRESH (never
+ * from this process's cached module graph). After `npm install -g` this is the
+ * ground truth for whether the cascade would re-execute new code.
+ */
+export function postInstallCliVersion() {
+  try {
+    const packagePath = fileURLToPath(new URL("../../package.json", import.meta.url));
+    const version = JSON.parse(fs.readFileSync(packagePath, "utf8"))?.version;
+    return typeof version === "string" && version.trim() ? version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 const HELP = `impel update - update everything Impel in one command
 
 Reinstalls impel-cli from npm, then uses the new build to discover every
@@ -83,7 +99,10 @@ function defaultSelfUpdate(spec) {
 }
 
 // The cascading steps re-execute the (freshly installed) CLI binary so the
-// NEW code performs them, not the process that started the update.
+// NEW code performs them, not the process that started the update. On
+// Windows this is also what refreshes the stable %LOCALAPPDATA% entry point:
+// bin/impel.js rewrites it at startup, so the shim is only ever updated by a
+// build that the postInstallCliVersion guard below already verified.
 export function defaultRunConvergence({
   skipApps = false,
   skipClis = false,
@@ -141,6 +160,7 @@ export async function cmdUpdate(argv, overrides = {}) {
     platform: process.platform,
     progress: withProgress,
     recoverInstall: runInstallRecovery,
+    postInstallVersion: postInstallCliVersion,
     loadConfig,
     ...overrides,
   };
@@ -261,6 +281,21 @@ export async function cmdUpdate(argv, overrides = {}) {
       }
       console.log("CLI: recovery verified the update path.");
     }
+    // npm exiting 0 is NOT proof the RUNNING install was updated: with multiple
+    // Node installs / npm prefixes (common on Windows), the install can land in
+    // a different global prefix while CLI_BIN — the path the cascade re-executes
+    // — still holds the old build. Cascading then runs old code that believes
+    // an update is still pending, which is how unbounded respawn storms start.
+    // Probe the version at CLI_BIN fresh from disk and refuse to cascade on skew.
+    const postInstall = io.postInstallVersion();
+    if (remote && postInstall !== remote) {
+      console.error(`impel update: npm reported success but the running CLI still resolves v${postInstall ?? "?"} (expected v${remote}).`);
+      console.error(`  Running CLI: ${CLI_BIN}`);
+      console.error("  This usually means the `impel` on PATH belongs to a different npm prefix than `npm prefix -g`.");
+      console.error("  Fix: run `npm prefix -g`, confirm it owns the `impel` shim on PATH, then `npm install --global impel-cli@latest` there.");
+      process.exitCode = 1;
+      return;
+    }
     console.log(`CLI: updated${remote ? ` to v${remote}` : ""}.`);
   }
 

package/src/selfInvocation.js

@@ -1,21 +1,71 @@
+import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** Stable entry point used by managed subprocess configs, including on Windows. */
+import { environmentValue } from "./nativeProcess.js";
+
+/** The running package's own bin script, used directly for live child spawns. */
 export const IMPEL_CLI_ENTRYPOINT = fileURLToPath(new URL("../bin/impel.js", import.meta.url));
 
-export function impelCliInvocation(args = []) {
+// Matches a real package install (npm/pnpm/volta all place the package under
+// node_modules/impel-cli; an unsupported project-local install matches too,
+// and the shim's run-time re-resolution still heals it toward a global
+// install). A git checkout or worktree never matches, so development runs
+// keep baking their own path instead of repointing the machine-wide stable
+// entry at a checkout.
+const GLOBAL_INSTALL_RE = /[\\/]node_modules[\\/]impel-cli[\\/]bin[\\/]impel\.js$/iu;
+
+export function runningFromGlobalInstall(entrypoint = IMPEL_CLI_ENTRYPOINT) {
+  return GLOBAL_INSTALL_RE.test(entrypoint);
+}
+
+/** Where the Windows stable entry point lives: outside every npm prefix. */
+export function windowsStableEntrypointPath(environment = process.env) {
+  const localAppData = environmentValue(environment, "LOCALAPPDATA");
+  if (typeof localAppData !== "string" || !localAppData.trim()) return null;
+  return path.join(localAppData, "Impel", "bin", "impel-entry.cjs");
+}
+
+/** The directory `impel nuke` removes to erase the stable entry point. */
+export function windowsStableEntrypointRoot(environment = process.env) {
+  const entrypoint = windowsStableEntrypointPath(environment);
+  return entrypoint ? path.dirname(path.dirname(entrypoint)) : null;
+}
+
+/**
+ * The entry point baked into managed artifacts that vendor apps execute later
+ * (session hooks, Codex auth/MCP commands, Start-menu shortcuts).
+ *
+ * On Windows, `npm install -g` replaces the global package directory
+ * non-atomically, so artifacts that point straight into the npm prefix all
+ * break at once mid-install and vendor retry policies fan out fail-fast
+ * children (the 2026-07 console-window storm). Global installs therefore bake
+ * the stable `impel-entry.cjs` shim, which lives outside the prefix and
+ * re-resolves the current install at run time. Everywhere else — macOS/Linux
+ * (npm swaps are atomic-enough and the sh token helper already re-resolves)
+ * and development checkouts — the running package's own path is used.
+ */
+export function managedCliEntrypoint({
+  platform = process.platform,
+  environment = process.env,
+  entrypoint = IMPEL_CLI_ENTRYPOINT,
+} = {}) {
+  if (platform !== "win32" || !runningFromGlobalInstall(entrypoint)) return entrypoint;
+  return windowsStableEntrypointPath(environment) || entrypoint;
+}
+
+export function impelCliInvocation(args = [], options = {}) {
   return {
     command: process.execPath,
-    args: [IMPEL_CLI_ENTRYPOINT, ...args],
+    args: [managedCliEntrypoint(options), ...args],
   };
 }
 
 export const IMPEL_MANAGED_MCP_ENV = "IMPEL_MANAGED_MCP";
 
-export function impelMcpInvocation(args = []) {
+export function impelMcpInvocation(args = [], options = {}) {
   return {
     type: "stdio",
-    ...impelCliInvocation(["mcp", ...args]),
+    ...impelCliInvocation(["mcp", ...args], options),
     env: { [IMPEL_MANAGED_MCP_ENV]: "1" },
   };
 }

package/src/sessionCollector.js

@@ -471,7 +471,9 @@ function captureTranscript(root, sessionMeta, input) {
 
 function gitValue(cwd, args) {
   try {
-    const result = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 1500, stdio: ["ignore", "pipe", "ignore"] });
+    // windowsHide: this runs inside console-less detached flush children on
+    // Windows, where each git.exe would otherwise allocate a visible console.
+    const result = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 1500, stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
     return result.status === 0 ? result.stdout.trim().slice(0, 2048) : "";
   } catch {
     return "";
@@ -983,6 +985,45 @@ export async function readHookInput(stream = process.stdin) {
   return value;
 }
 
+/**
+ * Heartbeat lock for the detached `sessions flush` child. Hooks fire on every
+ * session event; without this, each event stacks another detached child that
+ * polls the same outbox for up to 90 s — hundreds of concurrent processes on a
+ * busy session. The flush child refreshes the mtime while polling; hook
+ * dispatch skips the spawn while the heartbeat is fresh.
+ */
+export function sessionFlushLockPath({ tenantId, provider, sessionKey }) {
+  // NOT "flush.lock": acquireLock(root, "flush") owns that exact path (as a
+  // directory) for outbox batch mutual exclusion; this heartbeat is a separate,
+  // advisory spawn-rate limiter and must never collide with it.
+  return path.join(sessionDirectory(tenantId, provider, sessionKey), "flush-heartbeat");
+}
+
+export function touchSessionFlushLock(target) {
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(target, `${process.pid}\n`, { mode: 0o600 });
+  } catch {
+    // Lock upkeep is best-effort; a missing lock only allows an extra child.
+  }
+}
+
+export function sessionFlushLockIsFresh(target, maxAgeMs = 15_000, now = Date.now()) {
+  try {
+    return now - fs.statSync(target).mtimeMs < maxAgeMs;
+  } catch {
+    return false;
+  }
+}
+
+export function clearSessionFlushLock(target) {
+  try {
+    fs.rmSync(target, { force: true });
+  } catch {
+    // Stale locks expire via mtime anyway.
+  }
+}
+
 export function sessionOutboxStatus({ tenantId, provider, sessionKey }) {
   const root = sessionDirectory(tenantId, provider, sessionKey);
   return {

package/src/shellEntries.js

@@ -6,7 +6,7 @@ import { spawnSync } from "node:child_process";
 import { appPaths, CLAUDE_CONFIG_ID } from "./apps.js";
 import { redactSecretText } from "./config.js";
 import { environmentValue, nativeCommandInvocation, resolveNativeBinary } from "./nativeProcess.js";
-import { IMPEL_CLI_ENTRYPOINT } from "./selfInvocation.js";
+import { managedCliEntrypoint } from "./selfInvocation.js";
 import { normalizeTenantId } from "./tenants.js";
 import { windowsClaudeUserData } from "./windowsApps.js";
 
@@ -53,7 +53,7 @@ export function registerWindowsTenantShortcut({
   environment = process.env,
   run = spawnSync,
   execPath = process.execPath,
-  cliEntrypoint = IMPEL_CLI_ENTRYPOINT,
+  cliEntrypoint = managedCliEntrypoint({ platform: "win32", environment }),
   iconPath = null,
   mkdirSync = fs.mkdirSync,
 }) {

package/src/skills.js

@@ -212,6 +212,9 @@ export function runSkillCommand(bin, args, env, {
         env: environment,
         stdio: ["ignore", "pipe", "pipe"],
         windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+        // One update run spawns ~150 of these cmd.exe-wrapped plugin commands
+        // across tenants; keep them off-screen on Windows.
+        windowsHide: true,
       });
     } catch (error) {
       resolve({

package/src/stableEntrypoint.js

@@ -0,0 +1,194 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  IMPEL_CLI_ENTRYPOINT,
+  runningFromGlobalInstall,
+  windowsStableEntrypointPath,
+} from "./selfInvocation.js";
+import { redactSecretText } from "./config.js";
+
+/**
+ * Render the stable Windows entry point (`%LOCALAPPDATA%\Impel\bin\impel-entry.cjs`).
+ *
+ * Managed vendor artifacts persist `node <this file> <args…>` instead of a
+ * path inside the npm global prefix. The shim lives outside every prefix so
+ * `npm install -g impel-cli` never deletes it, prefers the baked install it
+ * was written for, re-resolves other well-known global locations when that
+ * install moved, and turns the non-atomic mid-install window into one bounded
+ * slow attempt instead of a fail-fast child per vendor retry.
+ *
+ * The rendered source is dependency-free CJS and must stay runnable on every
+ * supported Node (>=18). Output is deterministic for a given baked path.
+ */
+export function renderStableEntrypoint(cliEntrypoint = IMPEL_CLI_ENTRYPOINT) {
+  return `#!/usr/bin/env node
+"use strict";
+// Managed by impel-cli — stable Impel entry point.
+//
+// Vendor apps (Impel Claude, Impel ChatGPT) persist absolute invocations of
+// this file in their managed profiles. It resolves the current impel-cli
+// global install at run time, so replacing or moving the npm global package
+// never strands the invocations baked into those profiles.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { pathToFileURL } = require("node:url");
+const { spawnSync } = require("node:child_process");
+
+const BAKED_CLI = ${JSON.stringify(cliEntrypoint)};
+const CLI_SUFFIX = path.join("node_modules", "impel-cli", "bin", "impel.js");
+
+function waitBudgetMs() {
+  const raw = Number.parseInt(process.env.IMPEL_ENTRYPOINT_WAIT_MS || "", 10);
+  if (Number.isFinite(raw) && raw >= 0) return Math.min(raw, 60000);
+  return 8000;
+}
+
+function candidateCliPaths() {
+  const environment = process.env;
+  const prefixes = [
+    environment.APPDATA ? path.join(environment.APPDATA, "npm") : null,
+    path.dirname(process.execPath),
+    environment.NVM_SYMLINK || null,
+  ];
+  const candidates = [BAKED_CLI];
+  for (const prefix of prefixes) {
+    if (prefix) candidates.push(path.join(prefix, CLI_SUFFIX));
+  }
+  return Array.from(new Set(candidates));
+}
+
+function isFile(candidate) {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// "Complete enough to import": npm extracts package files one by one, so an
+// existing bin script may still sit in a half-written tree. Requiring the
+// package manifest and main source root too rejects most torn states.
+function isCompleteInstall(cliPath) {
+  try {
+    const root = path.dirname(path.dirname(cliPath));
+    if (!isFile(cliPath) || !isFile(path.join(root, "src", "cli.js"))) return false;
+    return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).name === "impel-cli";
+  } catch {
+    return false;
+  }
+}
+
+function resolveCompleteCli() {
+  for (const candidate of candidateCliPaths()) {
+    if (isCompleteInstall(candidate)) return candidate;
+  }
+  return null;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function main() {
+  // \`npm install -g\` replaces the global package non-atomically; waiting a
+  // bounded moment rides out that window instead of failing instantly at
+  // whatever cadence the calling vendor app retries.
+  const deadline = Date.now() + waitBudgetMs();
+  let cli = resolveCompleteCli();
+  while (!cli && Date.now() < deadline) {
+    await sleep(250);
+    cli = resolveCompleteCli();
+  }
+  // Layout drift in a future package (no src/cli.js) would never satisfy the
+  // completeness probe; fall back to any existing bin script at the deadline.
+  if (!cli) cli = candidateCliPaths().find(isFile) || null;
+  if (!cli) {
+    process.stderr.write(
+      "impel-entry: no impel-cli install found (checked " + candidateCliPaths().join("; ") + "). " +
+      "Run \`npm install -g impel-cli\`, then \`impel setup\`.\\n"
+    );
+    process.exit(1);
+  }
+  process.argv[1] = cli;
+  try {
+    await import(pathToFileURL(cli).href);
+  } catch (error) {
+    // The tree can heal between the completeness probe and the import, but
+    // this process's module cache may pin the torn state. A single fresh
+    // child re-reads the healed tree; a genuinely broken install fails once
+    // more there and its exit code propagates.
+    const rerun = spawnSync(process.execPath, [cli].concat(process.argv.slice(2)), {
+      stdio: "inherit",
+      windowsHide: true,
+    });
+    if (typeof rerun.status === "number") process.exit(rerun.status);
+    process.stderr.write(
+      "impel-entry: could not start " + cli + " (" +
+      (error && error.message ? error.message : String(error)) + ")\\n"
+    );
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(
+    "impel-entry: " + (error && error.message ? error.message : String(error)) + "\\n"
+  );
+  process.exit(1);
+});
+`;
+}
+
+/**
+ * Write the stable entry point if it is missing or stale. Only a real global
+ * package install may write it — a checkout or worktree run must never
+ * repoint the machine-wide shim at itself — and the caller is expected to be
+ * a build that is actually executing, which is what makes its own install
+ * path verified-good (`impel update` additionally refuses to cascade into a
+ * fresh build until postInstallCliVersion proves the install landed).
+ */
+export function ensureWindowsStableEntrypoint({
+  environment = process.env,
+  entrypoint = IMPEL_CLI_ENTRYPOINT,
+} = {}) {
+  if (!runningFromGlobalInstall(entrypoint)) return null;
+  const target = windowsStableEntrypointPath(environment);
+  if (!target) return null;
+  const content = renderStableEntrypoint(entrypoint);
+  try {
+    if (fs.readFileSync(target, "utf8") === content) return { path: target, written: false };
+  } catch {
+    // Missing or unreadable: rewrite below.
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const temporaryPath = `${target}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(temporaryPath, content, { mode: 0o700 });
+    fs.renameSync(temporaryPath, target);
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // The successful rename already removed the temporary file.
+    }
+  }
+  return { path: target, written: true };
+}
+
+/**
+ * Startup variant: a locked or unwritable shim must not fail the command —
+ * the previous shim still resolves the current install at run time — but the
+ * operator should see why it could not be refreshed.
+ */
+export function ensureWindowsStableEntrypointQuietly(options = {}) {
+  try {
+    return ensureWindowsStableEntrypoint(options);
+  } catch (error) {
+    console.error(
+      `impel: could not refresh the stable Windows entry point (${redactSecretText(error?.message || error)})`
+    );
+    return null;
+  }
+}

package/src/updates.js

@@ -122,8 +122,15 @@ export function writeUpdateCache(patch) {
   return next;
 }
 
+// A failed registry check must still count as "we tried": without stamping the
+// failure, a machine with broken registry access has a permanently stale cache
+// and EVERY TTY command respawns the detached refresh child — which on Windows
+// used to mean one more console window per command, forever.
+const UPDATE_CHECK_FAILURE_BACKOFF_MS = 60 * 60 * 1000;
+
 export function cacheIsFresh(cache, now = Date.now()) {
-  return Boolean(cache?.checkedAt && now - cache.checkedAt < UPDATE_CHECK_TTL_MS);
+  if (cache?.checkedAt && now - cache.checkedAt < UPDATE_CHECK_TTL_MS) return true;
+  return Boolean(cache?.lastFailedAt && now - cache.lastFailedAt < UPDATE_CHECK_FAILURE_BACKOFF_MS);
 }
 
 /** Fetch npm's latest version and record it; returns the updated cache (or null). */
@@ -131,7 +138,14 @@ export async function refreshUpdateCache(dependencies = {}) {
   const fetchLatest = dependencies.fetchRemoteVersion || fetchRemoteVersion;
   const writeCache = dependencies.writeCache || writeUpdateCache;
   const remoteVersion = await fetchLatest();
-  if (!remoteVersion) return null;
+  if (!remoteVersion) {
+    try {
+      writeCache({ lastFailedAt: Date.now() });
+    } catch {
+      // The stamp is a spawn-rate limiter, not required state.
+    }
+    return null;
+  }
   return writeCache({ remoteVersion, checkedAt: Date.now() });
 }
 
@@ -178,6 +192,10 @@ function spawnDetached(args) {
     const child = spawn(process.execPath, [path.join(CLI_ROOT, "bin", "impel.js"), ...args], {
       detached: true,
       stdio: "ignore",
+      // Windows: a detached console-subsystem child gets its OWN console — a
+      // visible Command Prompt window per spawn — unless it is hidden. This is
+      // the same option startDetachedFlush already passes.
+      windowsHide: true,
     });
     child.unref();
   } catch {