impel-cli 0.17.10 → 0.17.12

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.10",
+  "version": "0.17.12",
   "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/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/tasks.js

@@ -6,6 +6,7 @@ import {
   ensureTenantSelection,
   PAT_SCOPE_TASKS,
   PRODUCT_ACCESS_GATEWAY,
+  PRODUCT_ACCESS_IDENTITY,
   PRODUCT_ACCESS_WORKSPACE,
 } from "../tenants.js";
 
@@ -85,6 +86,9 @@ async function requestJson({ flags, path, query, method = "GET", body }) {
   if (selected.productAccess === PRODUCT_ACCESS_GATEWAY) {
     fail("impel tasks: Gateway members do not have workspace task access.");
   }
+  if (selected.productAccess === PRODUCT_ACCESS_IDENTITY) {
+    fail("impel tasks: Identity members do not have workspace task access.");
+  }
   if (selected.productAccess !== PRODUCT_ACCESS_WORKSPACE) {
     fail("impel tasks: the control plane did not return a live Workspace entitlement; retry after it is upgraded.");
   }

package/src/commands/update.js

@@ -99,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,

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/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/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/tenants.js

@@ -7,11 +7,19 @@ import {
 
 export const TENANT_CREDENTIAL_PREFIX = "impel_tenant_";
 export const PRODUCT_ACCESS_WORKSPACE = "workspace";
+export const PRODUCT_ACCESS_IDENTITY = "identity";
 export const PRODUCT_ACCESS_GATEWAY = "gateway";
 export const PAT_SCOPE_CLAUDE = "claude-code-gateway";
 export const PAT_SCOPE_CODEX = "codex-gateway";
 export const PAT_SCOPE_TASKS = "tasks";
-const PRODUCT_ACCESS_VALUES = new Set([PRODUCT_ACCESS_WORKSPACE, PRODUCT_ACCESS_GATEWAY]);
+// Additive entitlement hierarchy: Gateway < Identity + Gateway < Workspace.
+// Identity and Gateway members share the same gateway scopes and neither can
+// authorize workspace tasks; only Workspace members do.
+const PRODUCT_ACCESS_VALUES = new Set([
+  PRODUCT_ACCESS_WORKSPACE,
+  PRODUCT_ACCESS_IDENTITY,
+  PRODUCT_ACCESS_GATEWAY,
+]);
 const PROVIDER_SCOPE = Object.freeze({ claude: PAT_SCOPE_CLAUDE, codex: PAT_SCOPE_CODEX });
 const TENANT_ID_RE = /^[A-Za-z0-9_.-]{1,128}$/u;
 const PAT_SCOPE_RE = /^[a-z0-9][a-z0-9:._-]{0,63}$/u;
@@ -27,6 +35,7 @@ export function normalizeProductAccess(value, { allowMissing = false } = {}) {
 
 export function productAccessLabel(value) {
   if (value === PRODUCT_ACCESS_WORKSPACE) return "Workspace member";
+  if (value === PRODUCT_ACCESS_IDENTITY) return "Identity + Gateway member";
   if (value === PRODUCT_ACCESS_GATEWAY) return "Gateway member";
   return "Unknown";
 }