impel-cli 0.20.53 → 0.20.54

package/RELEASE_NOTES.md

@@ -1,5 +1,27 @@
 # Release notes
 
+## 0.20.54 — Restore ChatGPT Store compatibility and scope skills per tenant
+
+- Restores managed ChatGPT/Codex installation on Windows by pinning Store
+  package `26.814.5167.0` (embedded Codex `0.148.0-alpha.15`) — the build the
+  Store actually fulfills, after it stopped serving the previous package.
+  Retains exact package, publisher, executable, and runtime verification.
+- Holds the macOS ChatGPT desktop pin at `26.810.41047` (embedded Codex
+  `0.148.0-alpha.9`) rather than advancing it with Windows. Build
+  `26.814.41957` breaks the managed Tasks board: its view is destroyed instead
+  of hidden when returning to the app. The pins are deliberately split for this
+  release and rejoin once a macOS build passes the launch smoke.
+- Syncs skills with the selected tenant's credential so tenant-scoped skills
+  reach managed profiles. An uncredentialed fetch returns the gateway's
+  globals-only view with a 200, so the previous sync silently installed global
+  skills only.
+- Reconciles each managed profile against the fetched view, removing skills
+  this CLI installed that the tenant no longer receives, and leaving
+  user-installed skills untouched.
+- Leaves installed skills byte-identical and exits non-zero when the gateway
+  cannot determine the tenant, so an identity outage can never be mistaken for
+  an empty view.
+
 ## 0.20.53 — Launch distributed managed CLIs
 
 - Adds `impel claude` and `impel codex` fallback launch through an installed

package/package.json

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

package/src/apps.js

@@ -105,17 +105,38 @@ export const PINNED_VENDOR_APPS = Object.freeze({
     }),
   }),
   chatgpt: Object.freeze({
+    // DELIBERATELY SPLIT FROM THE WINDOWS PIN BELOW (2026-08-18).
+    //
+    // These normally move together, and the default should remain one
+    // coordinated build. macOS is held one build back because ChatGPT
+    // 26.814.41957 changed its onboarding flow and the managed Tasks board's
+    // WebContentsView is destroyed rather than hidden when navigating back to
+    // the app: the launch smoke fails reproducibly with zero surviving board
+    // targets. That is a real incompatibility with the desktop-tasks
+    // integration, not a flaky check, so the newer macOS build is not shipped
+    // until it is fixed.
+    //
+    // Windows cannot wait: the Store stopped fulfilling the old package
+    // entirely, so holding both would leave Windows unable to install at all.
+    // Rejoin the two as soon as a macOS build passes the launch smoke.
     version: "26.810.41047",
     codexVersion: "0.148.0-alpha.9",
     bundleName: "ChatGPT.app",
     windows: Object.freeze({
       storeProductId: "9PLM9XGG6VKS",
       packageName: "OpenAI.Codex",
-      // The Microsoft Store manifest identifies this exact reviewed build.
-      // Keep one Windows package version so the manifest contract and local
-      // AppX validation cannot silently drift apart again.
-      packageVersion: "26.810.4967.0",
-      codexVersion: "0.148.0-alpha.9",
+      // The exact AppX version Windows registers for this Store product, and
+      // the only version production validates: ensureWindowsChatGPTApp installs
+      // by storeProductId and then fail-closed-checks the REGISTERED package
+      // against this value. updateManifestUrl below is advertisement, read by
+      // the contract test alone and never by the install path.
+      //
+      // Those two disagree as of 2026-08-18: the manifest advertises
+      // 26.814.5517.0 while the Store installs 26.814.5167.0. Pin what actually
+      // installs — a pin matching only the advertisement would fail closed on
+      // every real machine.
+      packageVersion: "26.814.5167.0",
+      codexVersion: "0.148.0-alpha.15",
       publisherId: "2p2nqsd0c76g0",
       executable: "app\\ChatGPT.exe",
       updateManifestUrl: "https://persistent.oaistatic.com/codex-app-prod/windows-store-update.json",

package/src/commands/apps.js

@@ -42,6 +42,7 @@ import {
   readTenantManifest,
   removeManagedApps,
 } from "../apps.js";
+import { resolveSkillCredential } from "../skillBundle.js";
 import { resolveSkillsGateway, syncSkillsSafe } from "../skills.js";
 import { syncAgentProfilesSafe } from "../agents.js";
 import { secureManagedCodexHome } from "../codexSecurity.js";
@@ -490,7 +491,7 @@ export async function reconcileWindowsTenantApps({
     // Merge the sync env so an app-embedded binary (IMPEL_CODEX_BIN) satisfies
     // the availability check even when no standalone CLI is installed.
     if (io.findBinary(client, { ...environment, ...env }, "win32")) {
-      if (RUNTIME_BRAND.features.skills) await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label, homeDir: os.homedir() });
+      if (RUNTIME_BRAND.features.skills) await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), credential: resolveSkillCredential(config), env, label, homeDir: os.homedir() });
       agentTargets.push(target);
     } else {
       io.log(`Skipping skill/agent sync for ${label} — no ${client === "claude" ? "Claude Code" : "Codex"} binary is available to run plugin commands.`);
@@ -611,7 +612,7 @@ export async function reconcileMacTenantApps({
   for (const item of installed) {
     const { client, env, label } = appSkillTarget(item.target, paths);
     if (io.findBinary(client, environment, "darwin")) {
-      if (RUNTIME_BRAND.features.skills) await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label, homeDir: os.homedir() });
+      if (RUNTIME_BRAND.features.skills) await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), credential: resolveSkillCredential(config), env, label, homeDir: os.homedir() });
       agentItems.push(item);
     }
     if (item.target === "chatgpt") io.secureCodexHome(paths.chatgpt.codexHome);
@@ -859,6 +860,7 @@ export async function cmdWindowsApps(argv, overrides = {}) {
             io.syncSkills({
               client,
               gatewayUrl: resolveSkillsGateway(config.gatewayUrl),
+              credential: resolveSkillCredential(config),
               env,
               label,
               homeDir: os.homedir(),
@@ -1119,7 +1121,7 @@ export async function cmdApps(argv, overrides = {}) {
     const { client, env, label } = appSkillTarget(item.target, paths);
     if (RUNTIME_BRAND.features.skills && !flags["skip-skills"]) {
       await withProgress(`Syncing skills for ${label}`, (spinner) => (
-        io.syncSkills({ client, gatewayUrl, env, label, homeDir: os.homedir(), logger: createProgressLogger(spinner) })
+        io.syncSkills({ client, gatewayUrl, credential: resolveSkillCredential(config), env, label, homeDir: os.homedir(), logger: createProgressLogger(spinner) })
       ));
     }
     if (item.target === "chatgpt") io.secureCodexHome(paths.chatgpt.codexHome);
@@ -1250,7 +1252,7 @@ export async function provisionAndOpenManagedApps({
     const { client, env, label } = appSkillTarget(item.target, paths);
     if (RUNTIME_BRAND.features.skills) {
       await withProgress(`Syncing skills for ${label}`, (spinner) => (
-        io.syncSkills({ client, gatewayUrl, env, label, homeDir: os.homedir(), logger: createProgressLogger(spinner) })
+        io.syncSkills({ client, gatewayUrl, credential: resolveSkillCredential(config), env, label, homeDir: os.homedir(), logger: createProgressLogger(spinner) })
       ));
     }
     if (item.target === "chatgpt") io.secureCodexHome(paths.chatgpt.codexHome);
@@ -1422,7 +1424,7 @@ async function refreshApps(targets, { staleOnly = false, tenantId = null } = {},
   const gatewayUrl = resolveSkillsGateway(config.gatewayUrl);
   for (const status of supportedStatuses) {
     const { client, env, label } = appSkillTarget(status.target, tenantPaths);
-    if (RUNTIME_BRAND.features.skills) await io.syncSkills({ client, gatewayUrl, env, label, homeDir: os.homedir() });
+    if (RUNTIME_BRAND.features.skills) await io.syncSkills({ client, gatewayUrl, credential: resolveSkillCredential(config), env, label, homeDir: os.homedir() });
     if (status.target === "chatgpt") io.secureCodexHome(tenantPaths.chatgpt.codexHome);
   }
   if (RUNTIME_BRAND.features.agents) {

package/src/commands/converge.js

@@ -12,6 +12,7 @@ import { promptText } from "../prompt.js";
 import { describeCliFailure, preparePlatformClis } from "../platformSetup.js";
 import { restoreNativeProfiles } from "./use.js";
 import { createTenantRecoveryReportTracker } from "./tenantRecoveryReport.js";
+import { resolveSkillCredential } from "../skillBundle.js";
 
 const RETRYABLE_TENANT_DISCOVERY_ERROR = /could not reach|request timed out|fetch failed|ECONNRESET|ECONNABORTED|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|network error|socket/iu;
 
@@ -152,6 +153,7 @@ export async function cmdConverge(argv = [], overrides = {}) {
       const inspected = await io.preparePlatformClis({
         gatewayUrl: config.gatewayUrl,
         tenantId: selected.id,
+        credential: resolveSkillCredential({ pat: config.pat, tenantId: selected.id }),
         platform: io.platform,
         skipInstall: true,
       });
@@ -183,6 +185,7 @@ export async function cmdConverge(argv = [], overrides = {}) {
           prepared = await io.preparePlatformClis({
             gatewayUrl: config.gatewayUrl,
             tenantId: selected.id,
+            credential: resolveSkillCredential({ pat: config.pat, tenantId: selected.id }),
             platform: io.platform,
             skipInstall: false,
             installTools,
@@ -234,6 +237,7 @@ export async function cmdConverge(argv = [], overrides = {}) {
             skipInstall: true,
             // Goals re-run before every system-risk step: the probe must be
             // pure discovery — no installs, profile writes, or skill syncs.
+            // Deliberately no credential: nothing here reaches a skills fetch.
             inspectOnly: true,
           });
           return prepared.missingAfter.length === 0;
@@ -249,6 +253,7 @@ export async function cmdConverge(argv = [], overrides = {}) {
           return io.preparePlatformClis({
             gatewayUrl: config.gatewayUrl,
             tenantId: selected.id,
+            credential: resolveSkillCredential({ pat: config.pat, tenantId: selected.id }),
             platform: io.platform,
             skipInstall: true,
           });

package/src/commands/skills.js

@@ -14,6 +14,7 @@ import { CODEX_HOME } from "../codexSetup.js";
 import { tenantCliProfilePaths } from "../cliProfiles.js";
 import { CLAUDE_CONFIG_ID, appPaths } from "../apps.js";
 import { environmentValue } from "../nativeProcess.js";
+import { resolveSkillCredential } from "../skillBundle.js";
 import { resolveSkillsGateway, syncSkillsSafe } from "../skills.js";
 import { ensureTenantSelection } from "../tenants.js";
 import { windowsClaudeUserData, windowsManagedChatGPTRoot } from "../windowsApps.js";
@@ -113,6 +114,7 @@ export async function cmdSkills(argv, overrides = {}) {
     loadConfig,
     ensureTenantSelection,
     managedProfiles: managedSkillProfiles,
+    resolveCredential: resolveSkillCredential,
     syncSkills: syncSkillsSafe,
     ...overrides,
   };
@@ -121,6 +123,10 @@ export async function cmdSkills(argv, overrides = {}) {
   const tenantId = config?.pat
     ? (await io.ensureTenantSelection(config)).tenantId
     : null;
+  // Bound to the tenant just selected, not to the bare PAT: on a multi-tenant
+  // account the PAT alone resolves to identity's default tenant, which is not
+  // necessarily the one these profiles are configured for.
+  const credential = io.resolveCredential(config);
   const clients = target === "all" ? ["claude", "codex"] : [target];
   const profiles = clients.flatMap((client) => (
     io.managedProfiles(client, {
@@ -129,15 +135,27 @@ export async function cmdSkills(argv, overrides = {}) {
     }).map((profile) => ({ client, profile }))
   ));
 
-  await withProgress(`Syncing skills into ${profiles.length} managed profile${profiles.length === 1 ? "" : "s"}`, (spinner) => (
+  const results = await withProgress(`Syncing skills into ${profiles.length} managed profile${profiles.length === 1 ? "" : "s"}`, (spinner) => (
     mapWithConcurrency(profiles, 4, ({ client, profile }) => (
       io.syncSkills({
         client,
         gatewayUrl,
+        credential,
         env: profile.env,
         label: profile.label,
         logger: createProgressLogger(spinner),
       })
     ))
   ));
+
+  // Contract §2: an unavailable gateway must exit non-zero. It is reported
+  // rather than thrown because the other profiles' syncs are still valid work
+  // and their results have already been printed.
+  if (results.some((result) => result?.reason === "unavailable")) {
+    console.error(
+      "impel skills: the gateway could not determine this machine's tenant. "
+      + "Installed skills were left unchanged; re-run `impel skills sync` once it recovers.",
+    );
+    process.exitCode = 1;
+  }
 }

package/src/macSetup.js

@@ -171,6 +171,10 @@ function installationFailure(result, thrown = null) {
 export async function prepareMacClis({
   gatewayUrl,
   tenantId,
+  // Tenant credential for the authenticated skills fetch. Optional: an
+  // unauthenticated setup still provisions profiles, it just receives the
+  // gateway's globals-only view (see syncSkills).
+  credential = null,
   skipInstall = false,
   inspectOnly = false,
   installTools = ["claude", "codex"],
@@ -246,6 +250,7 @@ export async function prepareMacClis({
     await io.syncSkills({
       client: "claude",
       gatewayUrl,
+      credential,
       env: {
         CLAUDE_CONFIG_DIR: claudeProfile.configDir,
         IMPEL_CLAUDE_BIN: binaries.claude,
@@ -259,6 +264,7 @@ export async function prepareMacClis({
     await io.syncSkills({
       client: "codex",
       gatewayUrl,
+      credential,
       env: {
         CODEX_HOME: codexProfile.codexHome,
         IMPEL_CODEX_BIN: binaries.codex,

package/src/provisioning.js

@@ -7,6 +7,7 @@ import { crossAppModelsEnabled, redactSecretText } from "./config.js";
 import { ensureImpelClaudeProfile, ensureImpelCodexProfile, tenantCliProfilePaths } from "./cliProfiles.js";
 import { mapWithConcurrency } from "./progress.js";
 import { registerTenantShellEntries } from "./shellEntries.js";
+import { resolveSkillCredential } from "./skillBundle.js";
 import { resolveSkillsGateway, syncSkillsSafe } from "./skills.js";
 import {
   normalizeTenantId,
@@ -128,6 +129,10 @@ async function prepareTenantCli(config, tenant, io, binaries) {
       if (RUNTIME_BRAND.features.skills) await io.syncSkills({
         client,
         gatewayUrl,
+        // Scoped to THIS tenant, not the config's currently selected one: this
+        // loop provisions every accessible tenant, so a credential built from
+        // the selected tenant would give every profile the same tenant's view.
+        credential: resolveSkillCredential({ pat: config.pat, tenantId: tenant.id }),
         env: definition.env(profile),
         label: `Impel ${client === "claude" ? "Claude" : "Codex"} CLI (${tenant.id})`,
         // Lets Windows spawns use a git-safe cwd (see skillSyncSpawnDirectory).

package/src/skillBundle.js

@@ -0,0 +1,389 @@
+// Fetches the selected tenant's skills from the Bifrost registry and
+// reconciles them into a managed client profile's `skills/` directory.
+//
+// Contract: impel-gateway `docs/skills-tenant-scope-cli-contract.md`.
+//
+// Why this exists at all: the gateway filters every skills-serving surface by
+// the requesting tenant, and "no credential" is not an error there — it is the
+// globals-only view, served with a 200. The vendor plugin commands
+// (`claude plugin install`, `codex plugin add`) fetch the gateway themselves
+// and cannot be given a credential, so every profile they populate receives
+// globals only. This module is the authenticated path: it asks the gateway for
+// the bundle AS THE TENANT and writes the answer to disk itself.
+//
+// Three gateway outcomes, deliberately NOT unified (contract §2):
+//
+//   200 + view      -> authoritative; install it and remove managed skills
+//                      absent from it.
+//   200 + globals   -> also authoritative (the credential was refused, not
+//                      unanswered). Reconcile, but say so: on a machine that
+//                      expected scoped skills this usually means the credential
+//                      never arrived.
+//   503 unavailable -> identity could not answer. CHANGE NOTHING ON DISK.
+//
+// The 503 rule is the load-bearing one. An identity outage rendered as an empty
+// view is indistinguishable from "your tenant's skills were all removed", and
+// the removal pass below would then faithfully delete every working skill on
+// the machine. So a failed fetch must never reach reconciliation as an empty
+// collection — it aborts before touching anything.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+
+import { normalizeGatewayUrl, redactSecretText } from "./config.js";
+import { normalizeTenantId, tenantCredential } from "./tenants.js";
+
+/** Marks the skills this CLI installed, so reconciliation never touches a user's own. */
+export const MANAGED_SKILL_MANIFEST = ".impel-managed-skills.json";
+export const MANAGED_SKILL_MANIFEST_VERSION = 1;
+
+/** The tenant-filtered bundle of every skill the requesting tenant may see. */
+const BUNDLE_PATH = "/api/skills/serve/all/download.zip";
+
+const BUNDLE_FETCH_TIMEOUT_MS = 60_000;
+// The gateway serves this from a serverless function with a cold TTFB, and the
+// bundle is a megabyte-scale zip. One retry covers a cold start; more would
+// just extend an outage the caller should hear about promptly.
+const BUNDLE_FETCH_ATTEMPTS = 2;
+
+// A decompressed bundle is a few megabytes. This ceiling is far above that and
+// exists only so a malformed or hostile response cannot exhaust memory.
+const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 16 * 1024 * 1024;
+const MAX_ENTRIES = 4096;
+
+// Skill directory names are the first path segment of every bundle entry and
+// become directories under the profile. Constrain them to what the registry
+// actually publishes so no entry can traverse, hide, or collide with the
+// manifest.
+const SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+
+/**
+ * Thrown when the gateway could not determine the tenant (contract §2, row 3).
+ *
+ * A distinct type rather than a flag because the whole point is that callers
+ * must not treat it like an empty view: an `instanceof` check is harder to
+ * collapse by accident than an `if (result.skills.length === 0)`.
+ */
+export class SkillsUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SkillsUnavailableError";
+  }
+}
+
+/** The bundle URL for a gateway origin. */
+export function skillBundleUrl(gatewayUrl) {
+  return `${normalizeGatewayUrl(gatewayUrl)}${BUNDLE_PATH}`;
+}
+
+/**
+ * Fetch the tenant's skill bundle.
+ *
+ * The credential rides an `Authorization: Bearer` header. It is a tenant
+ * credential (PAT scoped to one tenant id), never the bare PAT: the bare PAT
+ * resolves to whatever tenant identity picks for it, which on a multi-tenant
+ * account is not necessarily the tenant the caller selected.
+ *
+ * Returns the raw zip bytes. Throws SkillsUnavailableError for anything that
+ * means "the answer is unknown" — a 5xx, a transport failure, or a timeout —
+ * so no caller can mistake an outage for an empty tenant.
+ */
+export async function fetchSkillBundle({
+  gatewayUrl,
+  credential,
+  fetchImpl = fetch,
+  timeoutMs = BUNDLE_FETCH_TIMEOUT_MS,
+  attempts = BUNDLE_FETCH_ATTEMPTS,
+}) {
+  if (!credential) {
+    // Deliberately not a silent globals-only fetch. A caller that reached here
+    // without a credential has a bug, and quietly serving it the narrow view is
+    // exactly the failure this module exists to end.
+    throw new SkillsUnavailableError("a tenant credential is required to fetch tenant-scoped skills");
+  }
+  const url = skillBundleUrl(gatewayUrl);
+  let lastError = null;
+  for (let attempt = 0; attempt < Math.max(1, attempts); attempt += 1) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImpl(url, {
+        headers: { authorization: `Bearer ${credential}`, accept: "application/zip" },
+        signal: controller.signal,
+      });
+      if (response.status >= 500) {
+        // The gateway's "identity could not answer" branch. Retry once — a cold
+        // start looks the same from here — then surface it as unavailable.
+        lastError = new SkillsUnavailableError(
+          `the gateway could not determine this machine's tenant (HTTP ${response.status})`,
+        );
+        continue;
+      }
+      if (!response.ok) {
+        // A 4xx is an answer: the credential is rejected or the route is gone.
+        // Still not something to reconcile against, but it will not fix itself
+        // on a retry, so fail immediately and name it.
+        throw new SkillsUnavailableError(`the skills registry rejected this request (HTTP ${response.status})`);
+      }
+      const bytes = Buffer.from(await response.arrayBuffer());
+      if (bytes.length > MAX_BUNDLE_BYTES) {
+        throw new SkillsUnavailableError("the skills registry returned an implausibly large bundle");
+      }
+      return bytes;
+    } catch (error) {
+      if (error instanceof SkillsUnavailableError && !String(error.message).includes("HTTP 5")) {
+        throw error;
+      }
+      lastError = error?.name === "AbortError"
+        ? new SkillsUnavailableError(`the skills registry did not respond within ${timeoutMs}ms`)
+        : error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  throw lastError instanceof SkillsUnavailableError
+    ? lastError
+    : new SkillsUnavailableError(
+      `could not reach the skills registry: ${redactSecretText(lastError?.message || lastError)}`,
+    );
+}
+
+/**
+ * Read a zip archive into `{ path, contents }` entries.
+ *
+ * Written here rather than shelling out to `unzip`/`tar`: this CLI is
+ * dependency-free by design, and Windows has no dependable bundled unzip.
+ *
+ * The central directory is the authority for what the archive contains — the
+ * local headers are not, because the gateway streams entries with data
+ * descriptors (bit 3 set), which leaves the local header's sizes zeroed.
+ */
+export function readZipEntries(buffer) {
+  const eocd = findEndOfCentralDirectory(buffer);
+  if (!eocd) throw new Error("the skills bundle is not a readable zip archive");
+  const { entryCount, directoryOffset } = eocd;
+  if (entryCount > MAX_ENTRIES) throw new Error("the skills bundle declares too many entries");
+
+  const entries = [];
+  let offset = directoryOffset;
+  for (let index = 0; index < entryCount; index += 1) {
+    if (offset + 46 > buffer.length || buffer.readUInt32LE(offset) !== 0x02014b50) {
+      throw new Error("the skills bundle has a malformed central directory");
+    }
+    const method = buffer.readUInt16LE(offset + 10);
+    const compressedSize = buffer.readUInt32LE(offset + 20);
+    const uncompressedSize = buffer.readUInt32LE(offset + 24);
+    const nameLength = buffer.readUInt16LE(offset + 28);
+    const extraLength = buffer.readUInt16LE(offset + 30);
+    const commentLength = buffer.readUInt16LE(offset + 32);
+    const localOffset = buffer.readUInt32LE(offset + 42);
+    const name = buffer.toString("utf8", offset + 46, offset + 46 + nameLength);
+    offset += 46 + nameLength + extraLength + commentLength;
+
+    // Directory entries carry a trailing slash and no content.
+    if (name.endsWith("/")) continue;
+    if (uncompressedSize > MAX_ENTRY_BYTES) {
+      throw new Error(`the skills bundle entry "${name}" is implausibly large`);
+    }
+    entries.push({
+      path: name,
+      contents: inflateEntry(buffer, localOffset, method, compressedSize, name),
+    });
+  }
+  return entries;
+}
+
+function findEndOfCentralDirectory(buffer) {
+  // The EOCD is at the tail, after a comment of up to 64 KiB.
+  const earliest = Math.max(0, buffer.length - (0xffff + 22));
+  for (let index = buffer.length - 22; index >= earliest; index -= 1) {
+    if (buffer.readUInt32LE(index) !== 0x06054b50) continue;
+    return {
+      entryCount: buffer.readUInt16LE(index + 10),
+      directoryOffset: buffer.readUInt32LE(index + 16),
+    };
+  }
+  return null;
+}
+
+function inflateEntry(buffer, localOffset, method, compressedSize, name) {
+  if (localOffset + 30 > buffer.length || buffer.readUInt32LE(localOffset) !== 0x04034b50) {
+    throw new Error(`the skills bundle entry "${name}" has a malformed header`);
+  }
+  // Only the name/extra lengths are trustworthy in a local header when a data
+  // descriptor is in play; the sizes come from the central directory above.
+  const nameLength = buffer.readUInt16LE(localOffset + 26);
+  const extraLength = buffer.readUInt16LE(localOffset + 28);
+  const start = localOffset + 30 + nameLength + extraLength;
+  const payload = buffer.subarray(start, start + compressedSize);
+  if (method === 0) return Buffer.from(payload);
+  if (method !== 8) throw new Error(`the skills bundle entry "${name}" uses an unsupported compression method`);
+  return zlib.inflateRawSync(payload);
+}
+
+/**
+ * Group flat zip entries into skills, keyed by their top-level directory.
+ *
+ * Rejects rather than sanitizes anything that does not look like a published
+ * skill file. A bundle is a trusted-ish source, but it is still remote input
+ * being written to a path derived from its own contents, so absolute paths,
+ * `..` segments, and backslash separators are refused outright — silently
+ * "cleaning" such a path is how a traversal becomes a write outside the
+ * profile.
+ */
+export function groupBundleSkills(entries) {
+  const skills = new Map();
+  for (const entry of entries) {
+    const normalized = String(entry.path).replace(/^\.\//u, "");
+    if (!normalized
+      || normalized.includes("\\")
+      || normalized.startsWith("/")
+      || /^[A-Za-z]:/u.test(normalized)
+      || normalized.split("/").some((segment) => segment === ".." || segment === "." || segment === "")) {
+      throw new Error(`the skills bundle contains an unsafe path "${entry.path}"`);
+    }
+    const [name, ...rest] = normalized.split("/");
+    if (!SKILL_NAME_RE.test(name)) {
+      throw new Error(`the skills bundle contains an unsafe skill name "${name}"`);
+    }
+    if (rest.length === 0) continue; // A stray top-level file is not part of any skill.
+    if (!skills.has(name)) skills.set(name, []);
+    skills.get(name).push({ path: rest.join("/"), contents: entry.contents });
+  }
+  // A directory with no SKILL.md is not a skill either client will load, and
+  // writing it would leave an inert directory that reconciliation then has to
+  // reason about forever.
+  for (const [name, files] of skills) {
+    if (!files.some((file) => file.path === "SKILL.md")) skills.delete(name);
+  }
+  return skills;
+}
+
+/** Stable digest of one skill's full contents, used to skip unchanged writes. */
+export function skillDigest(files) {
+  const hash = crypto.createHash("sha256");
+  for (const file of [...files].sort((left, right) => left.path.localeCompare(right.path))) {
+    hash.update(file.path);
+    hash.update("\0");
+    hash.update(file.contents);
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function readManagedManifest(manifestPath) {
+  let raw;
+  try {
+    const stat = fs.lstatSync(manifestPath);
+    if (stat.isSymbolicLink() || !stat.isFile()) return null;
+    raw = fs.readFileSync(manifestPath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const manifest = JSON.parse(raw);
+    if (manifest?.version !== MANAGED_SKILL_MANIFEST_VERSION || !Array.isArray(manifest.skills)) return null;
+    // Only well-formed names survive; a corrupted entry must not become a
+    // deletion target on the next pass.
+    manifest.skills = manifest.skills.filter((name) => typeof name === "string" && SKILL_NAME_RE.test(name));
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+
+function removeSkillDirectory(directory) {
+  // Never follow a symlink out of the profile: remove the link itself.
+  let stat;
+  try {
+    stat = fs.lstatSync(directory);
+  } catch {
+    return;
+  }
+  if (stat.isSymbolicLink()) fs.unlinkSync(directory);
+  else fs.rmSync(directory, { recursive: true, force: true });
+}
+
+function writeSkill(skillsDir, name, files) {
+  const target = path.join(skillsDir, name);
+  // Replace wholesale rather than merging: a skill that dropped a file upstream
+  // must not keep a stale copy of it locally.
+  removeSkillDirectory(target);
+  for (const file of files) {
+    const filePath = path.join(target, file.path);
+    // Belt and braces over groupBundleSkills' checks: assert the resolved path
+    // is still inside the skill directory after the OS has had its say.
+    const resolved = path.resolve(filePath);
+    if (resolved !== path.resolve(target) && !resolved.startsWith(path.resolve(target) + path.sep)) {
+      throw new Error(`refusing to write skill file outside ${target}`);
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, file.contents);
+  }
+}
+
+/**
+ * Reconcile one profile's `skills/` directory against the fetched view.
+ *
+ * Reconciliation, not append (contract §3): a skill this CLI installed that has
+ * left the tenant's view is removed. The manifest is what bounds that — only
+ * names recorded in a previous managed sync are deletion candidates, so a skill
+ * the user wrote or installed by other means is never touched, even if it
+ * shares a name with something the registry once served.
+ */
+export function reconcileSkills(skillsDir, skills, { now = new Date() } = {}) {
+  fs.mkdirSync(skillsDir, { recursive: true });
+  const manifestPath = path.join(skillsDir, MANAGED_SKILL_MANIFEST);
+  const prior = readManagedManifest(manifestPath);
+  const priorDigests = prior?.digests && typeof prior.digests === "object" ? prior.digests : {};
+  const previouslyManaged = new Set(prior?.skills || []);
+
+  const installed = [];
+  const updated = [];
+  const digests = {};
+  for (const [name, files] of [...skills].sort(([left], [right]) => left.localeCompare(right))) {
+    const digest = skillDigest(files);
+    digests[name] = digest;
+    installed.push(name);
+    const unchanged = priorDigests[name] === digest
+      && previouslyManaged.has(name)
+      && fs.existsSync(path.join(skillsDir, name, "SKILL.md"));
+    if (unchanged) continue;
+    writeSkill(skillsDir, name, files);
+    updated.push(name);
+  }
+
+  const present = new Set(installed);
+  const removed = [];
+  for (const name of previouslyManaged) {
+    if (present.has(name)) continue;
+    removeSkillDirectory(path.join(skillsDir, name));
+    removed.push(name);
+  }
+
+  fs.writeFileSync(manifestPath, `${JSON.stringify({
+    version: MANAGED_SKILL_MANIFEST_VERSION,
+    syncedAt: now.toISOString(),
+    skills: installed,
+    digests,
+  }, null, 2)}\n`);
+
+  return { installed, updated, removed: removed.sort() };
+}
+
+/**
+ * Resolve the tenant credential for a skills fetch, or null when the CLI is not
+ * authenticated. Callers degrade to a warning rather than failing: an
+ * unauthenticated machine legitimately has no tenant view to ask for.
+ */
+export function resolveSkillCredential(config) {
+  if (!config?.pat || !config?.tenantId) return null;
+  try {
+    return tenantCredential(config.pat, normalizeTenantId(config.tenantId));
+  } catch {
+    return null;
+  }
+}

package/src/skills.js

@@ -21,10 +21,18 @@
 
 import { spawn } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 import { resolveDefaultGateway, normalizeGatewayUrl } from "./config.js";
 import { findNativeBinary, nativeCommandInvocation } from "./nativeProcess.js";
+import {
+  fetchSkillBundle,
+  groupBundleSkills,
+  readZipEntries,
+  reconcileSkills,
+  SkillsUnavailableError,
+} from "./skillBundle.js";
 import { findReviewedVendorCliBinary } from "./vendorCliBinaries.js";
 import { PINNED_VENDOR_CLI_VERSIONS } from "./vendorCliVersions.js";
 
@@ -269,6 +277,180 @@ export function skillSyncSpawnDirectory({
   }
 }
 
+/**
+ * The `skills/` directory the client reads for a profile described by `env`.
+ *
+ * Both clients discover skills from a plain directory under their profile root
+ * — `<CLAUDE_CONFIG_DIR>/skills` and `<CODEX_HOME>/skills` — which is what lets
+ * the authenticated sync install a tenant's view without going through the
+ * vendor plugin machinery at all. An absent override means the native profile,
+ * exactly as a bare `claude` or `codex` would resolve it.
+ */
+export function profileSkillsDirectory(client, env = {}, { homeDir = os.homedir() } = {}) {
+  return path.join(profileRoot(client, env, { homeDir }), "skills");
+}
+
+/**
+ * The profile root a client resolves for these env overrides.
+ *
+ * Callers that manage the NATIVE profile pass no override, meaning "wherever a
+ * bare `claude`/`codex` would look". That is a resolution, not an absence, and
+ * it has to be computed rather than left implicit: `runSkillCommand` merges
+ * `process.env` into every child, so an ambient `CLAUDE_CONFIG_DIR` — which is
+ * exactly what an `impel claude` session sets — would otherwise silently
+ * redirect a native-profile command at the isolated profile.
+ */
+export function profileRoot(client, env = {}, { homeDir = os.homedir() } = {}) {
+  if (client === "claude") return env.CLAUDE_CONFIG_DIR || path.join(homeDir, ".claude");
+  return env.CODEX_HOME || process.env.CODEX_HOME || path.join(homeDir, ".codex");
+}
+
+/**
+ * Env overrides that pin a vendor command to exactly `root`.
+ *
+ * Without this, "no override" means "inherit", and the inherited value wins.
+ * Pinning makes the profile a command reads identical to the one this module
+ * inspected and wrote — otherwise cleanup can detect state in one profile and
+ * mutate another.
+ */
+function profilePinnedEnv(client, env, root) {
+  return client === "claude"
+    ? { ...env, CLAUDE_CONFIG_DIR: root }
+    : { ...env, CODEX_HOME: root };
+}
+
+/**
+ * Install the tenant's skills straight into a managed profile (IMP-576).
+ *
+ * This is the authenticated path, and it is the only one that can see a
+ * tenant-scoped skill: the vendor plugin commands below fetch the gateway
+ * themselves with no credential, and the gateway answers an uncredentialed
+ * request with the globals-only view — a 200, not an error. So a profile
+ * populated only by those commands silently receives globals forever.
+ *
+ * Returns a result the caller reports, or `null` when there is no credential to
+ * sync with, which tells the caller to fall back to the unauthenticated plugin
+ * path rather than leaving the profile with nothing.
+ */
+/**
+ * Retire the globals-only plugin the pre-IMP-576 sync installed.
+ *
+ * Every machine that ran an older impel-cli has `bifrost-all-skills` installed
+ * as a vendor plugin, holding the unauthenticated (globals-only) view. Once the
+ * authenticated path writes those same skills into the profile directly, the
+ * plugin copy is both redundant and stale — the client would load
+ * `research-software` twice, from two different snapshots.
+ *
+ * Best-effort by design: this is cleanup of a superseded mechanism, and a
+ * machine with no vendor binary has no plugin to remove anyway. Failures are
+ * silent because the authenticated sync has already succeeded by this point,
+ * and a warning here would report a healthy profile as degraded.
+ */
+async function retireLegacySkillPlugin({ runCommand, commandBinary, env, client, homeDir, root }) {
+  if (!commandBinary) return;
+  // Pin the child to the profile this sync inspected. Detection reads `root`
+  // directly, so an inherited override would let us find the plugin in one
+  // profile and uninstall from another.
+  env = profilePinnedEnv(client, env, root);
+  // The exact ids to uninstall come from the profile's own registry, never from
+  // a guess. Claude registers the plugin as PLUGIN@MARKETPLACE and rejects the
+  // bare id with "not found in installed plugins" once it was installed from a
+  // named marketplace — the same trap buildSkillCommands already documents for
+  // `plugin update`. Reading the registry also means a profile carrying an
+  // older marketplace name is still cleaned up.
+  const plugins = installedLegacySkillPlugins(client, env, { homeDir, root });
+  if (plugins.length === 0) return;
+  try {
+    const help = await runCommand(commandBinary, ["plugin", "--help"], env);
+    if (help.missing || !help.ok) return;
+    for (const plugin of plugins) {
+      await runCommand(commandBinary, ["plugin", "remove", plugin], env);
+    }
+  } catch {
+    // The profile is already correct; a failed cleanup is not worth surfacing.
+  }
+}
+
+/**
+ * Ids under which the pre-IMP-576 bundled plugin is currently installed.
+ *
+ * Claude records installs in `plugins/installed_plugins.json` keyed by
+ * `PLUGIN@MARKETPLACE`; Codex records marketplaces in config.toml and its
+ * `plugin remove` accepts the bare plugin name, so only Claude needs the
+ * qualified lookup. An unreadable or absent registry yields nothing to do.
+ */
+export function installedLegacySkillPlugins(client, env = {}, { homeDir = os.homedir(), root = null } = {}) {
+  if (client !== "claude") return [SKILL_PLUGIN_NAME];
+  const profile = root || profileRoot(client, env, { homeDir });
+  let registry;
+  try {
+    registry = JSON.parse(fs.readFileSync(path.join(profile, "plugins", "installed_plugins.json"), "utf8"));
+  } catch {
+    return [];
+  }
+  const plugins = registry?.plugins;
+  if (!plugins || typeof plugins !== "object" || Array.isArray(plugins)) return [];
+  return Object.keys(plugins).filter((id) => id === SKILL_PLUGIN_NAME || id.startsWith(`${SKILL_PLUGIN_NAME}@`));
+}
+
+async function syncTenantSkills({
+  client,
+  gatewayUrl,
+  credential,
+  env,
+  homeDir,
+  fetchImpl,
+  logger,
+  displayLabel,
+  runCommand,
+  commandBinary,
+}) {
+  if (!credential) return null;
+  let bundle;
+  try {
+    bundle = await fetchSkillBundle({ gatewayUrl, credential, fetchImpl });
+  } catch (error) {
+    if (error instanceof SkillsUnavailableError) {
+      // Contract §2: an unavailable answer must leave the installed set exactly
+      // as it is. Returning here — before reconcileSkills is ever reached — is
+      // what guarantees that; there is no partial-write path to unwind.
+      logger.warn(
+        `impel: skill sync for ${displayLabel} could not be completed (${error.message}); `
+        + "installed skills were left unchanged.",
+      );
+      return { client, label: displayLabel, synced: false, reason: "unavailable", changed: false };
+    }
+    throw error;
+  }
+
+  const skills = groupBundleSkills(readZipEntries(bundle));
+  // Resolved once and reused for the write, the detection, and the removal, so
+  // those three can never disagree about which profile they are operating on.
+  const resolvedHome = homeDir || os.homedir();
+  const root = profileRoot(client, env, { homeDir: resolvedHome });
+  const { installed, updated, removed } = reconcileSkills(path.join(root, "skills"), skills);
+  // Only after the tenant view is safely on disk: removing the legacy plugin
+  // first would leave a machine with no skills at all if the write then failed.
+  await retireLegacySkillPlugin({ runCommand, commandBinary, env, client, homeDir: resolvedHome, root });
+  const changes = [
+    ...(updated.length ? [`${updated.length} updated`] : []),
+    ...(removed.length ? [`${removed.length} removed`] : []),
+  ];
+  logger.log(
+    `Skills: ${displayLabel} up to date (${installed.length} skill${installed.length === 1 ? "" : "s"}`
+    + `${changes.length ? `, ${changes.join(", ")}` : ""}).`,
+  );
+  return {
+    client,
+    label: displayLabel,
+    synced: true,
+    reason: "tenant-scoped",
+    installed,
+    updated,
+    removed,
+  };
+}
+
 const SKILL_COMMAND_TIMEOUT_MS = 120_000;
 const SKILL_COMMAND_OUTPUT_LIMIT = 10 * 1024 * 1024;
 
@@ -495,6 +677,7 @@ export async function syncSkills({
   gatewayUrl,
   env = {},
   label,
+  credential = null,
   fetchImpl = fetch,
   run = runSkillCommand,
   logger = console,
@@ -515,24 +698,68 @@ export async function syncSkills({
     return { client, label: displayLabel, skipped: true, reason: "disabled" };
   }
 
+  // Callers that manage real profiles pass their home directory so Windows
+  // spawns happen from a git-safe cwd (see skillSyncSpawnDirectory).
+  const spawnDirectory = skillSyncSpawnDirectory({ platform, homeDir });
+  const runCommand = spawnDirectory
+    ? (commandBin, commandArgs, commandEnv) => run(commandBin, commandArgs, commandEnv, { cwd: spawnDirectory })
+    : run;
+
   let commandBinary = spec.bin;
+  let vendorBinaryMissing = false;
   if (platform === "darwin" && run === runSkillCommand) {
     commandBinary = findVendorBinary(client, { ...process.env, ...env }, platform);
-    if (!commandBinary) {
+    vendorBinaryMissing = !commandBinary;
+  }
+
+  // The authenticated path first: it is the only one that can see this tenant's
+  // scoped skills. It needs no vendor binary — it writes the profile directly —
+  // so a version-drifted or entirely absent vendor CLI must not stop it. That is
+  // why the binary check above only records its result here instead of returning.
+  if (credential) {
+    try {
+      const result = await syncTenantSkills({
+        client,
+        gatewayUrl,
+        credential,
+        env,
+        homeDir,
+        fetchImpl,
+        logger,
+        displayLabel,
+        runCommand,
+        commandBinary,
+      });
+      if (result) return result;
+    } catch (error) {
+      // Reaching here means the bundle was fetched but could not be read or
+      // written — a malformed archive, or an unwritable profile. Fall through
+      // to the unauthenticated plugin path so the profile still gets globals
+      // rather than nothing, and say plainly that scoped skills are missing.
       logger.warn(
-        `impel: skipping skill sync for ${displayLabel} — reviewed ${spec.label} `
-        + `v${PINNED_VENDOR_CLI_VERSIONS[client]} is not installed; run \`impel update\`.`,
+        `impel: tenant-scoped skill sync for ${displayLabel} failed (${error?.message || error}); `
+        + "falling back to the shared marketplace, which serves global skills only.",
       );
-      return { client, label: displayLabel, skipped: true, reason: "binary-version-mismatch" };
     }
+  } else {
+    // No credential is not a failure — an unauthenticated machine has no tenant
+    // view to ask for — but it is worth naming, because the gateway answers an
+    // uncredentialed fetch with a 200 and the narrow view, so the profile below
+    // will look successfully synced while missing every scoped skill.
+    logger.warn(
+      `impel: syncing global skills only for ${displayLabel} — no tenant credential is available. `
+      + "Run `impel setup` to receive this tenant's scoped skills.",
+    );
   }
 
-  // Callers that manage real profiles pass their home directory so Windows
-  // spawns happen from a git-safe cwd (see skillSyncSpawnDirectory).
-  const spawnDirectory = skillSyncSpawnDirectory({ platform, homeDir });
-  const runCommand = spawnDirectory
-    ? (commandBin, commandArgs, commandEnv) => run(commandBin, commandArgs, commandEnv, { cwd: spawnDirectory })
-    : run;
+  // Only the unauthenticated plugin path below actually needs the vendor CLI.
+  if (vendorBinaryMissing) {
+    logger.warn(
+      `impel: skipping skill sync for ${displayLabel} — reviewed ${spec.label} `
+      + `v${PINNED_VENDOR_CLI_VERSIONS[client]} is not installed; run \`impel update\`.`,
+    );
+    return { client, label: displayLabel, skipped: true, reason: "binary-version-mismatch" };
+  }
 
   try {
     // Confirm the binary and its `plugin` subcommand exist before doing anything.

package/src/windowsSetup.js

@@ -120,6 +120,10 @@ function installationFailure(result, thrown = null) {
 export async function prepareWindowsClis({
   gatewayUrl,
   tenantId,
+  // Tenant credential for the authenticated skills fetch. Optional: an
+  // unauthenticated setup still provisions profiles, it just receives the
+  // gateway's globals-only view (see syncSkills).
+  credential = null,
   skipInstall = false,
   inspectOnly = false,
   installTools = ["claude", "codex"],
@@ -222,6 +226,7 @@ export async function prepareWindowsClis({
     await io.syncSkills({
       client: "claude",
       gatewayUrl,
+      credential,
       env: { CLAUDE_CONFIG_DIR: claudeProfile.configDir },
       label: "Impel isolated Claude (impel claude)",
       // Lets Windows spawns use a git-safe cwd (see skillSyncSpawnDirectory).
@@ -232,6 +237,7 @@ export async function prepareWindowsClis({
     await io.syncSkills({
       client: "codex",
       gatewayUrl,
+      credential,
       env: { CODEX_HOME: codexProfile.codexHome },
       label: "Impel isolated Codex (impel codex)",
       homeDir: os.homedir(),