impel-cli 0.20.52 → 0.20.53

package/RELEASE_NOTES.md

@@ -1,5 +1,17 @@
 # Release notes
 
+## 0.20.53 — Launch distributed managed CLIs
+
+- Adds `impel claude` and `impel codex` fallback launch through an installed
+  tenant-managed app when a standalone CLI credential is not configured.
+- Selects an explicit `--tenant`, configured tenant, or the sole installed
+  tenant; ambiguous installations fail closed with an actionable tenant list.
+- Validates the fixed application root, adjacent managed manifest, runtime
+  ownership, platform, logical tenant identity, and enrollment credential
+  presence without reading or placing the credential on the command line.
+- Keeps the existing standalone Claude and Codex launch behavior unchanged
+  whenever its separate CLI credential is configured.
+
 ## 0.20.52 — Open embedded Tasks tickets safely
 
 - Makes cards, list rows, fleet items, and the card menu open their exact

package/package.json

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

package/src/cli.js

@@ -47,6 +47,8 @@ Work:
   impel codex [args...]                       Launch Codex with an isolated Impel profile
   impel codex --agent <id|exact-title> ...    Run one fixed tenant agent without a parent hop
   impel codex --benchmark ...                 Tag native-agent MCP calls as benchmark traffic
+  impel claude|codex --tenant <id> ...        Select an enrolled Managed Software Center tenant
+                                              when the CLI has no separate Impel authentication
   impel remote handoff|dispatch|handback      Move or control provider-native sessions remotely
   impel remote status|viewer|proxy            Inspect, control, or connect to a remote run
   impel tenant list                           List accessible organizations

package/src/commands/converge.js

@@ -15,6 +15,21 @@ import { createTenantRecoveryReportTracker } from "./tenantRecoveryReport.js";
 
 const RETRYABLE_TENANT_DISCOVERY_ERROR = /could not reach|request timed out|fetch failed|ECONNRESET|ECONNABORTED|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|network error|socket/iu;
 
+/**
+ * Wait before the single discovery retry.
+ *
+ * An immediate retry cannot change the answer for the failure it most often
+ * sees: the OS caches a negative DNS result, so a second lookup microseconds
+ * later reads the same cached entry. This is long enough for a resolver or
+ * interface blip to clear and short enough that nobody watching decides the
+ * command has hung.
+ */
+export const TENANT_DISCOVERY_RETRY_DELAY_MS = 1_500;
+
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
 function confirmed(answer) {
   return /^(?:y|yes)$/iu.test(String(answer || "").trim());
 }
@@ -36,6 +51,7 @@ export async function cmdConverge(argv = [], overrides = {}) {
     environment: process.env,
     preparePlatformClis,
     discoveryLogger: console,
+    sleep,
     ...overrides,
   };
   if (overrides.prepareWindowsClis && !overrides.preparePlatformClis) {
@@ -59,6 +75,7 @@ export async function cmdConverge(argv = [], overrides = {}) {
       return false;
     }
     io.discoveryLogger.log("Tenants: discovery request failed transiently; retrying once…");
+    await io.sleep(TENANT_DISCOVERY_RETRY_DELAY_MS);
     try {
       listing = await io.fetchTenants(config);
     } catch (retryError) {

package/src/commands/launch.js

@@ -29,6 +29,12 @@ import { IMPEL_NATIVE_BENCHMARK_ENV } from "../selfInvocation.js";
 import { resolveReviewedVendorCliBinary } from "../vendorCliBinaries.js";
 import { PINNED_VENDOR_CLI_VERSIONS } from "../vendorCliVersions.js";
 import { RUNTIME_BRAND } from "../runtimeBrand.js";
+import {
+  installedManagedAppCandidates,
+  parseManagedTenantArgument,
+  runManagedAppCli,
+  selectManagedAppCandidate,
+} from "../managedApps.js";
 import {
   cacheProviderReadiness,
   cachedProviderReadiness,
@@ -462,7 +468,23 @@ export async function cmdLaunch(tool, argv) {
   }
   const config = loadConfig();
   if (!config?.pat) {
-    console.error(`impel ${tool}: not authenticated. Run \`impel auth\` first.`);
+    try {
+      const parsed = parseManagedTenantArgument(nativeArgv);
+      const candidate = selectManagedAppCandidate(installedManagedAppCandidates(tool), {
+        requestedTenant: parsed.tenantId,
+        configuredTenant: config?.tenantId || null,
+      });
+      if (candidate) {
+        const exitCode = await runManagedAppCli(candidate, tool, parsed.argv);
+        if (exitCode !== 0) process.exitCode = exitCode;
+        return;
+      }
+    } catch (error) {
+      console.error(`impel ${tool}: ${redactSecretText(error?.message || error)}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.error(`impel ${tool}: not authenticated and no enrolled managed application is installed. Run \`impel auth\` or install it from Managed Software Center.`);
     process.exitCode = 1;
     return;
   }

package/src/managedApps.js

@@ -0,0 +1,194 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+const TENANT = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/u;
+const APPLICATION_BY_TOOL = Object.freeze({ claude: "claude", codex: "chatgpt" });
+
+function regularFile(file) {
+  try {
+    const stat = fs.lstatSync(file);
+    return stat.isFile() && !stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function parseCandidate(manifestPath, launcher, tool, platform, home) {
+  if (!regularFile(manifestPath) || !regularFile(launcher)) return null;
+  let manifest;
+  try {
+    const raw = fs.readFileSync(manifestPath, "utf8");
+    if (Buffer.byteLength(raw, "utf8") > 512 * 1024) return null;
+    manifest = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const applicationId = APPLICATION_BY_TOOL[tool];
+  const tenantId = manifest?.tenant?.id;
+  const expectedPlatform = platform === "win32" ? "windows" : "macos";
+  if (
+    manifest?.schemaVersion !== 2
+    || manifest?.kind !== "com.useimpel.managed-application"
+    || manifest?.runtime?.owner !== "impel-apps"
+    || manifest?.runtime?.entrypoint !== "engine/main.mjs"
+    || manifest?.platform !== expectedPlatform
+    || manifest?.application?.id !== applicationId
+    || manifest?.application?.adapter !== applicationId
+    || !TENANT.test(tenantId || "")
+    || String(tenantId).includes("..")
+    || manifest?.logicalApplicationId !== `${tenantId}.${applicationId}`
+  ) return null;
+  const credential = path.join(home, ".config", "impel", "apps", "credentials", `${tenantId}.json`);
+  if (!regularFile(credential)) return null;
+  return {
+    tenantId,
+    tenantDisplayName: typeof manifest.tenant.displayName === "string" ? manifest.tenant.displayName : tenantId,
+    launcher,
+    manifestPath,
+  };
+}
+
+function macCandidates(tool, home, applicationsRoot) {
+  let entries;
+  try {
+    entries = fs.readdirSync(applicationsRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.endsWith(".app")) continue;
+    const root = path.join(applicationsRoot, entry.name, "Contents");
+    const candidate = parseCandidate(
+      path.join(root, "Resources", "app-manifest.json"),
+      path.join(root, "MacOS", "impel-apps-launcher"),
+      tool,
+      "darwin",
+      home,
+    );
+    if (candidate) candidates.push(candidate);
+  }
+  return candidates;
+}
+
+function windowsCandidates(tool, home, applicationsRoot) {
+  const candidates = [];
+  let tenants;
+  try {
+    tenants = fs.readdirSync(applicationsRoot, { withFileTypes: true });
+  } catch {
+    return candidates;
+  }
+  for (const tenant of tenants) {
+    if (!tenant.isDirectory() || !TENANT.test(tenant.name) || tenant.name.includes("..")) continue;
+    const root = path.join(applicationsRoot, tenant.name, APPLICATION_BY_TOOL[tool]);
+    const candidate = parseCandidate(
+      path.join(root, "resources", "app-manifest.json"),
+      path.join(root, "impel-apps-launcher.exe"),
+      tool,
+      "win32",
+      home,
+    );
+    if (candidate) candidates.push(candidate);
+  }
+  return candidates;
+}
+
+export function installedManagedAppCandidates(tool, {
+  platform = process.platform,
+  home = os.homedir(),
+  applicationsRoot = platform === "win32"
+    ? path.join(process.env.ProgramFiles || "C:\\Program Files", "Impel", "Apps")
+    : "/Applications",
+} = {}) {
+  if (!APPLICATION_BY_TOOL[tool]) return [];
+  const candidates = platform === "win32"
+    ? windowsCandidates(tool, home, applicationsRoot)
+    : platform === "darwin" ? macCandidates(tool, home, applicationsRoot) : [];
+  return candidates.sort((left, right) => left.tenantId.localeCompare(right.tenantId));
+}
+
+export function parseManagedTenantArgument(argv) {
+  const passthrough = [];
+  let tenantId = null;
+  let literal = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (literal) {
+      passthrough.push(argument);
+      continue;
+    }
+    if (argument === "--") {
+      literal = true;
+      passthrough.push(argument);
+      continue;
+    }
+    if (argument === "--tenant") {
+      tenantId = argv[index += 1] || null;
+      continue;
+    }
+    if (argument.startsWith("--tenant=")) {
+      tenantId = argument.slice("--tenant=".length) || null;
+      continue;
+    }
+    passthrough.push(argument);
+  }
+  if (tenantId !== null && (!TENANT.test(tenantId) || tenantId.includes(".."))) {
+    throw new Error("--tenant requires a valid managed tenant id");
+  }
+  return { tenantId, argv: passthrough };
+}
+
+export function selectManagedAppCandidate(candidates, {
+  requestedTenant = null,
+  environment = process.env,
+  configuredTenant = null,
+} = {}) {
+  const tenantId = requestedTenant || environment.IMPEL_MANAGED_TENANT || configuredTenant;
+  if (tenantId) {
+    const selected = candidates.find((candidate) => candidate.tenantId === tenantId);
+    if (!selected) throw new Error(`no installed managed application is available for tenant "${tenantId}"`);
+    return selected;
+  }
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.length === 0) return null;
+  throw new Error(
+    `more than one managed tenant is installed (${candidates.map(({ tenantId: id }) => id).join(", ")}); pass --tenant <id>`,
+  );
+}
+
+function childExitCode(code, signal) {
+  if (Number.isInteger(code)) return code;
+  const signalNumber = signal ? os.constants.signals[signal] : null;
+  return Number.isInteger(signalNumber) ? 128 + signalNumber : 1;
+}
+
+export function runManagedAppCli(candidate, tool, argv, {
+  environment = process.env,
+  cwd = process.cwd(),
+  spawnProcess = spawn,
+} = {}) {
+  return new Promise((resolve) => {
+    const child = spawnProcess(candidate.launcher, ["--managed-cli", tool, "--", ...argv], {
+      cwd,
+      env: environment,
+      stdio: "inherit",
+      windowsHide: false,
+    });
+    let settled = false;
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      console.error(`impel ${tool}: could not launch the managed application: ${error.message}`);
+      resolve(127);
+    });
+    child.once("exit", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      resolve(childExitCode(code, signal));
+    });
+  });
+}
+

package/src/tenants.js

@@ -25,6 +25,10 @@ const PRODUCT_ACCESS_VALUES = new Set([
 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;
+// Node surfaces a name-resolution failure through these `getaddrinfo` codes.
+// `EAI_AGAIN` is a transient resolver error; `ENOTFOUND` is a negative answer
+// the OS then caches, which is why an immediate retry re-reads the same result.
+const DNS_FAILURE_CODES = new Set(["ENOTFOUND", "EAI_AGAIN"]);
 
 export function normalizeProductAccess(value, { allowMissing = false } = {}) {
   if ((value === undefined || value === null || value === "") && allowMissing) return null;
@@ -136,7 +140,15 @@ export async function fetchTenants(config, fetchImpl = fetchHttp1) {
       signal: controller.signal,
     });
   } catch (error) {
-    const message = error?.name === "AbortError" ? "request timed out" : error?.message || error;
+    // A resolver failure is not a control-plane outage, and the raw
+    // `getaddrinfo ENOTFOUND` reads like one. Name the machine's own DNS so the
+    // remedy is looked for locally. The `could not reach` prefix is preserved
+    // because `cmdConverge` matches on it to decide the failure is retryable.
+    const message = error?.name === "AbortError"
+      ? "request timed out"
+      : DNS_FAILURE_CODES.has(error?.code)
+        ? `${error.code}; this machine could not resolve the hostname. Check its DNS resolver or VPN`
+        : error?.message || error;
     throw new Error(`could not reach ${appUrl}: ${redactSecretText(message)}`);
   } finally {
     clearTimeout(timeout);