impel-cli 0.13.1 → 0.13.2

package/README.md

@@ -642,7 +642,7 @@ Invocation uses the clients' native agent behavior:
 
 ```text
 # Claude Code / Claude Desktop Code tab: guaranteed explicit selection
-@agent-research-agent investigate the dependency change
+@research-agent investigate the dependency change
 
 # Claude blocking CLI
 claude --agent research-agent -p "investigate the dependency change"
@@ -715,8 +715,11 @@ Their visible bundle names use the organization display name, for example
 a stable, unique bundle identifier and gateway configuration:
 
 - Impel Claude is an APFS-cloned vendored copy of the official app with its own
-  bundle and helper identities. Its LaunchServices environment sets the
-  vendor-supported `CLAUDE_USER_DATA_DIR` and writes the 3P gateway
+  bundle and helper identities. Its LaunchServices environment sets both the
+  vendor-supported `CLAUDE_USER_DATA_DIR` and Claude Code's
+  `CLAUDE_CONFIG_DIR` to the tenant-private profile. This isolates browser
+  state, sessions, plugins, MCP servers, skills, and native `@` agents from
+  `~/.claude`, while the app writes the 3P gateway
   `configLibrary` below `~/.config/impel/apps/tenants/<org>/claude`. A new
   isolated profile defaults to the Code app while preserving any app selection
   the user makes afterward. A narrowly version-checked compatibility patch
@@ -818,6 +821,18 @@ available: `IMPEL_CODESIGN_ADHOC=1` forces ad-hoc signing, and
 `IMPEL_CODESIGN_IDENTITY=<name>` signs with a specific existing identity (e.g. a
 real `Developer ID Application: …`).
 
+Older Claude profiles already encrypt browser data with the macOS login
+Keychain item named `Claude Safe Storage`. Impel keeps that namespace immutable
+so an update never makes existing cookies or storage unreadable. Because each
+tenant app has a distinct bundle identity, macOS asks once before that app may
+use the legacy item: enter the Mac login password and choose **Always Allow**.
+Choosing **Allow** grants access for only that launch and therefore prompts
+again next time. The stable Impel signature keeps a successful Always Allow
+grant valid across later app updates. Clean profiles instead start with a
+persisted tenant-specific Safe Storage namespace, so they never request access
+to the shared vendor item. Impel does not weaken or silently rewrite Keychain
+access lists.
+
 The Claude 3P config necessarily contains the PAT because that app accepts a
 gateway API key rather than a token-helper command. It is stored in the same
 owner-only Impel config tree as the primary credential. ChatGPT/Codex uses a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "Configure Claude Code and Codex CLI to talk to Impel's gateway, authenticated by an Impel Personal Access Token",
   "type": "module",
   "bin": {

package/src/apps.js

@@ -83,6 +83,8 @@ const CLAUDE_PLAN_USAGE_GUARD = "if(!Ze().hasOrgPolicyBackend())return;if((r=fr(
 const IMPEL_CLAUDE_PLAN_USAGE_GUARD = `${"if(!wze())return;".padEnd("if(!Ze().hasOrgPolicyBackend())return;".length, " ")}if((r=fr())`;
 const CLAUDE_PLAN_USAGE_REQUEST = 'P.net.fetch(`${ht()}/api/organizations/${o}/usage`,{signal:AbortSignal.timeout(mcr)})';
 const IMPEL_CLAUDE_PLAN_USAGE_REQUEST = 'P.net.fetch("https://gateway.useimpel.com/ui/a/u",{headers:{key:dR(Oe()).apiKey}})'.padEnd(CLAUDE_PLAN_USAGE_REQUEST.length, " ");
+const LEGACY_CLAUDE_SAFE_STORAGE_NAME = "Claude";
+const CLAUDE_SAFE_STORAGE_METADATA = "safe-storage.json";
 
 export const FALLBACK_MODELS = [
   { id: "claude-opus-4-8", provider: "claude", display_name: "Claude Opus 4.8", family: "opus", family_default: true, default: true, context_window: 200000 },
@@ -152,7 +154,7 @@ export const CURRENT_CONFIG_VERSION = 10;
 // — which is what made every `impel update` re-trigger macOS permission
 // prompts. Bump this ONLY when a code change alters the bytes of a built
 // bundle; leave it alone for changes that don't touch bundle contents.
-export const BUNDLE_BUILD_FINGERPRINT = "bundle-2026-07-16.2";
+export const BUNDLE_BUILD_FINGERPRINT = "bundle-2026-07-16.3";
 
 /** Parse the tenant's install manifest, or null when absent/corrupt. */
 export function readTenantManifest(homeDir = os.homedir(), tenantId = null) {
@@ -352,6 +354,130 @@ export function appPaths(homeDir = os.homedir(), tenantId = null, {
   };
 }
 
+function readClaudeSafeStorageMetadata(paths) {
+  const metadataPath = path.join(paths.claude.root, CLAUDE_SAFE_STORAGE_METADATA);
+  try {
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+    if (
+      metadata?.schemaVersion !== 1
+      || typeof metadata.appName !== "string"
+      || !metadata.appName.trim()
+      || metadata.appName.length > 256
+    ) {
+      throw new Error("invalid contents");
+    }
+    return metadata;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw new Error(`Claude Safe Storage metadata is invalid: ${metadataPath}`);
+  }
+}
+
+/**
+ * Electron keys macOS Safe Storage by app.name. Existing profiles already have
+ * encrypted data under `Claude Safe Storage`, so changing their name would make
+ * that data unreadable. New profiles can safely start with an immutable,
+ * tenant-specific namespace and never touch the vendor/shared Keychain item.
+ */
+export function ensureClaudeSafeStorageName(paths, tenantId = null) {
+  const existing = readClaudeSafeStorageMetadata(paths);
+  if (existing) return existing.appName;
+  const hasExistingProfile = fs.existsSync(paths.claude.userData)
+    && fs.readdirSync(paths.claude.userData).length > 0;
+  const appName = hasExistingProfile
+    ? LEGACY_CLAUDE_SAFE_STORAGE_NAME
+    : `Impel Claude${tenantId ? ` [${normalizeTenantId(tenantId)}]` : ""}`;
+  writeAtomic(path.join(paths.claude.root, CLAUDE_SAFE_STORAGE_METADATA), `${JSON.stringify({
+    schemaVersion: 1,
+    appName,
+    mode: hasExistingProfile ? "legacy" : "tenant",
+  }, null, 2)}\n`, 0o600);
+  return appName;
+}
+
+const CLAUDE_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+function managedClaudeDesktopSessionIds(userData) {
+  const root = path.join(userData, "claude-code-sessions");
+  if (!fs.existsSync(root) || fs.lstatSync(root).isSymbolicLink()) return new Set();
+  const ids = new Set();
+  const pending = [root];
+  while (pending.length > 0) {
+    const directory = pending.pop();
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const candidate = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        pending.push(candidate);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      try {
+        const metadata = JSON.parse(fs.readFileSync(candidate, "utf8"));
+        if (CLAUDE_SESSION_ID_RE.test(metadata?.cliSessionId || "")) ids.add(metadata.cliSessionId);
+      } catch {
+        // A corrupt historical session remains in place; other sessions can
+        // still be migrated safely.
+      }
+    }
+  }
+  return ids;
+}
+
+/**
+ * Before v0.13.2 the desktop bundle isolated Electron state but omitted
+ * CLAUDE_CONFIG_DIR, so its embedded Claude Code transcripts fell through to
+ * ~/.claude. Copy only transcripts referenced by this app profile's own
+ * session metadata into the private config root. Native history is never
+ * removed or rewritten, and unrelated session IDs are ignored.
+ */
+export function migrateLegacyClaudeAppSessions(userData, homeDir = os.homedir()) {
+  const sessionIds = managedClaudeDesktopSessionIds(userData);
+  if (sessionIds.size === 0) return 0;
+  const nativeProjects = path.join(homeDir, ".claude", "projects");
+  const privateProjects = path.join(userData, "projects");
+  if (!fs.existsSync(nativeProjects) || fs.lstatSync(nativeProjects).isSymbolicLink()) return 0;
+  if (fs.existsSync(privateProjects) && fs.lstatSync(privateProjects).isSymbolicLink()) {
+    throw new Error(`refusing to migrate Claude sessions into symlinked profile path ${privateProjects}`);
+  }
+
+  let copied = 0;
+  for (const project of fs.readdirSync(nativeProjects, { withFileTypes: true })) {
+    if (!project.isDirectory() || project.isSymbolicLink()) continue;
+    const sourceDirectory = path.join(nativeProjects, project.name);
+    const destinationDirectory = path.join(privateProjects, project.name);
+    if (fs.existsSync(destinationDirectory) && fs.lstatSync(destinationDirectory).isSymbolicLink()) {
+      throw new Error(`refusing to migrate Claude sessions into symlinked project path ${destinationDirectory}`);
+    }
+    for (const entry of fs.readdirSync(sourceDirectory, { withFileTypes: true })) {
+      if (!entry.isFile() || entry.isSymbolicLink() || !entry.name.endsWith(".jsonl")) continue;
+      const sessionId = entry.name.slice(0, -".jsonl".length);
+      if (!sessionIds.has(sessionId)) continue;
+      const source = path.join(sourceDirectory, entry.name);
+      const destination = path.join(destinationDirectory, entry.name);
+      if (fs.existsSync(destination) && fs.lstatSync(destination).isSymbolicLink()) {
+        throw new Error(`refusing to overwrite symlinked Claude session transcript ${destination}`);
+      }
+      const sourceStat = fs.statSync(source);
+      if (fs.existsSync(destination) && fs.statSync(destination).mtimeMs >= sourceStat.mtimeMs) continue;
+      fs.mkdirSync(destinationDirectory, { recursive: true, mode: 0o700 });
+      fs.chmodSync(destinationDirectory, 0o700);
+      const temporary = `${destination}.tmp-${process.pid}`;
+      try {
+        fs.copyFileSync(source, temporary);
+        fs.chmodSync(temporary, 0o600);
+        fs.renameSync(temporary, destination);
+        fs.utimesSync(destination, sourceStat.atime, sourceStat.mtime);
+        fs.chmodSync(destination, 0o600);
+        copied += 1;
+      } finally {
+        fs.rmSync(temporary, { force: true });
+      }
+    }
+  }
+  return copied;
+}
+
 export async function fetchGatewayModels(config, fetchImpl = fetch) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 20000);
@@ -395,6 +521,9 @@ export function installManagedAppFiles({
     claudeUserData,
     tenantName: config.tenantName,
   });
+  const claudeSafeStorageName = targets.includes("claude")
+    ? ensureClaudeSafeStorageName(paths, config.tenantId)
+    : null;
   if (targets.includes("chatgpt")) secureAllManagedCodexHomes({ appsRoot: paths.root });
   fs.mkdirSync(paths.tenantRoot, { recursive: true, mode: 0o700 });
   if (writeTokenHelperFile) writeTokenHelper(paths.tokenHelper, config.tenantId);
@@ -409,6 +538,7 @@ export function installManagedAppFiles({
   const installed = [];
   for (const target of targets) {
     if (target === "claude") {
+      migrateLegacyClaudeAppSessions(paths.claude.userData, homeDir);
       writeClaudeDefaultApp(paths);
       writeClaudeConfig(paths, config, models);
     }
@@ -421,14 +551,23 @@ export function installManagedAppFiles({
         assertPinnedVendorAppVersion(target, resolvedVendorPaths[target]);
       }
       if (target === "chatgpt") writeVendoredChatGPTBundle(paths, resolvedVendorPaths.chatgpt, config.gatewayUrl);
-      else writeVendoredClaudeBundle(paths, resolvedVendorPaths.claude, config.gatewayUrl);
+      else writeVendoredClaudeBundle(
+        paths,
+        resolvedVendorPaths.claude,
+        config.gatewayUrl,
+        claudeSafeStorageName,
+      );
       if (config.tenantId) {
         // A successful tenant-specific rebuild supersedes the old global
         // launcher. Other tenant launchers have distinct names and survive.
         fs.rmSync(appPaths(homeDir)[target].launcher, { recursive: true, force: true });
       }
     }
-    installed.push({ target, launcher: paths[target].launcher });
+    installed.push({
+      target,
+      launcher: paths[target].launcher,
+      ...(target === "claude" ? { safeStorageName: claudeSafeStorageName } : {}),
+    });
   }
 
   writeAtomic(path.join(paths.tenantRoot, "manifest.json"), JSON.stringify({
@@ -992,7 +1131,7 @@ exec ${node} ${cli} token${tenantArgs}
   writeAtomic(target, script, 0o700);
 }
 
-function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl) {
+function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl, safeStorageName) {
   if (!vendorPath) throw new Error("Claude vendor app is unavailable");
   const executableName = APP_DEFINITIONS.claude.executableNames.find((name) => (
     fs.existsSync(path.join(vendorPath, "Contents", "MacOS", name))
@@ -1026,6 +1165,7 @@ function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl) {
       );
       planUsageRequestPatchCount = patchClaudePlanUsageRequest(asarPath);
     }
+    const safeStorageNamePatchCount = patchClaudeSafeStorageName(asarPath);
     const newAsarHash = asarHeaderHash(asarPath);
 
     updateBundleIdentity(plistPath, {
@@ -1035,7 +1175,15 @@ function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl) {
       name: paths.claude.displayName,
     });
     updateAsarIntegrityPlist(plistPath, oldAsarHash, newAsarHash);
+    // Claude Desktop separates its Electron profile from Claude Code's config
+    // root. Keep both on the tenant-private path: CLAUDE_USER_DATA_DIR isolates
+    // browser/app state, while CLAUDE_CONFIG_DIR controls sessions, plugins,
+    // MCP servers, skills, and native `@` agents used by the embedded runtime.
+    // Without the latter, the app silently falls back to ~/.claude and can
+    // expose an unrelated tenant's agents or secret-bearing MCP configuration.
     setPlistEnvironmentString(plistPath, "CLAUDE_USER_DATA_DIR", paths.claude.userData);
+    setPlistEnvironmentString(plistPath, "CLAUDE_CONFIG_DIR", paths.claude.userData);
+    setPlistEnvironmentString(plistPath, "IMPEL_CN", safeStorageName);
     rebrandElectronHelpers(staging, {
       fromName: "Claude",
       toName: paths.claude.displayName,
@@ -1054,10 +1202,13 @@ function writeVendoredClaudeBundle(paths, vendorPath, gatewayUrl) {
       bundleIdentifier: paths.claude.bundleIdentifier,
       displayName: paths.claude.displayName,
       profileRoot: paths.claude.userData,
+      configRoot: paths.claude.userData,
+      safeStorageName,
       launchMode: "LSEnvironment",
       patches: {
         aggregatePlanUsageGuard: planUsageGuardPatchCount,
         aggregatePlanUsageRequest: planUsageRequestPatchCount,
+        safeStorageName: safeStorageNamePatchCount,
       },
       asarHeaderSha256: newAsarHash,
     }, null, 2) + "\n", 0o644);
@@ -1239,6 +1390,24 @@ function patchClaudePlanUsageRequest(asarPath) {
   return applyFixedWidthAsarPatches(asarPath, archive, patches, "Claude plan-usage gateway request");
 }
 
+function patchClaudeSafeStorageName(asarPath) {
+  const archive = fs.readFileSync(asarPath);
+  const source = archive.toString("latin1");
+  const startupPattern = /([A-Za-z_$][\w$]*)\.app\.isPackaged\|\|\1\.app\.setName\("Claude"\)/gu;
+  const patches = [...source.matchAll(startupPattern)].map((match) => {
+    const original = match[0];
+    const replacement = `${match[1]}.app.setName(process.env.IMPEL_CN)`;
+    if (replacement.length > original.length) {
+      throw new Error("Claude Safe Storage app-name replacement no longer fits the vendor ASAR contract");
+    }
+    return { offset: match.index, original, replacement: replacement.padEnd(original.length, " ") };
+  });
+  if (patches.length !== 1) {
+    throw new Error(`Claude Safe Storage app-name patch expected 1 match, found ${patches.length}`);
+  }
+  return applyFixedWidthAsarPatches(asarPath, archive, patches, "Claude Safe Storage app name");
+}
+
 function patchFastModeAuthGate(asarPath) {
   const archive = fs.readFileSync(asarPath);
   const source = archive.toString("latin1");

package/src/commands/apps.js

@@ -56,6 +56,8 @@ import {
   windowsClaudeUserData,
 } from "../windowsApps.js";
 
+const CLAUDE_KEYCHAIN_NOTICE = "Claude Keychain: enter your Mac login password and choose Always Allow on the first prompt for this tenant; Allow is temporary.";
+
 // Each isolated desktop app maps to a client CLI + the env override that points
 // that CLI at the app's private profile, so skill syncing lands in the app's
 // installation rather than a global one.
@@ -626,6 +628,11 @@ export async function cmdApps(argv, overrides = {}) {
     const verb = action === "install" ? "Installed" : "Updated";
     io.log(`${verb} ${item.launcher}${rebuilt.has(item.target) ? "" : " (bundle already current)"}`);
   }
+  if (installed.some((item) => (
+    item.target === "claude"
+    && rebuilt.has(item.target)
+    && item.safeStorageName === "Claude"
+  ))) io.log(CLAUDE_KEYCHAIN_NOTICE);
   console.log(`Models: ${catalog.models.length} from ${catalog.source}. Normal ~/.claude and ~/.codex profiles were not changed.`);
 
   // Best-effort: sync the Bifrost shared skills into each installed isolated app
@@ -745,6 +752,11 @@ export async function provisionAndOpenManagedApps({
       io.log(`Installed and configured ${item.launcher} for tenant ${config.tenantId}.`);
     }
   }
+  if (installed.some((item) => (
+    item.target === "claude"
+    && staleBundleTargets.includes(item.target)
+    && item.safeStorageName === "Claude"
+  ))) io.log(CLAUDE_KEYCHAIN_NOTICE);
 
   // Match explicit install setup without penalizing repeat opens: this helper
   // only runs when the zero-network fast path has detected drift or first use.

package/src/windowsApps.js

@@ -329,7 +329,7 @@ export function removeManagedWindowsChatGPTApp(appsRoot) {
   fs.rmSync(windowsChatGPTCacheRoot(appsRoot), { recursive: true, force: true });
 }
 
-/** Launch the signed vendor app with only its profile root redirected to Impel. */
+/** Launch the signed vendor app with all mutable Claude state redirected to Impel. */
 export function launchWindowsClaudeApp(binary, userData, dependencies = {}) {
   const io = {
     environment: process.env,
@@ -341,11 +341,17 @@ export function launchWindowsClaudeApp(binary, userData, dependencies = {}) {
   const environment = { ...io.environment };
   // These developer-only overrides require a signed CDP token and must never
   // bleed from an unrelated native Claude session into the managed app.
-  const managedKeys = new Set(["CLAUDE_USER_DATA_DIR", "CLAUDE_CDP_AUTH", "CLAUDE_AI_URL"]);
+  const managedKeys = new Set([
+    "CLAUDE_USER_DATA_DIR",
+    "CLAUDE_CONFIG_DIR",
+    "CLAUDE_CDP_AUTH",
+    "CLAUDE_AI_URL",
+  ]);
   for (const key of Object.keys(environment)) {
     if (managedKeys.has(key.toUpperCase())) delete environment[key];
   }
   environment.CLAUDE_USER_DATA_DIR = userData;
+  environment.CLAUDE_CONFIG_DIR = userData;
 
   return new Promise((resolve, reject) => {
     const child = io.spawnProcess(binary, [], {