xtrm-tools 0.7.7 → 0.7.9

package/cli/dist/index.cjs

@@ -43891,6 +43891,13 @@ async function setRuntimeEnabledPacks(skillsRoot, runtime, packNames) {
 }
 
 // src/core/skills-materializer.ts
+var PI_NPM_PROVIDED_SKILLS = /* @__PURE__ */ new Set([
+  "gitnexus-debugging",
+  "gitnexus-exploring",
+  "gitnexus-impact-analysis",
+  "gitnexus-pr-review",
+  "gitnexus-refactoring"
+]);
 function sortByName(entries) {
   return [...entries].sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -43929,11 +43936,12 @@ async function selectRuntimeSkills(runtime, skillsRoot) {
   const defaultSkills = await discoverDefaultSkills(skillsRoot);
   const enabledPackSkills = await collectEnabledPackSkills(skillsRoot, enabledPacks);
   const allSkills = sortByName([...defaultSkills, ...enabledPackSkills]);
-  assertNoRuntimeCollisions(runtime, allSkills);
+  const filteredSkills = runtime === "pi" ? allSkills.filter((s) => !PI_NPM_PROVIDED_SKILLS.has(s.name)) : allSkills;
+  assertNoRuntimeCollisions(runtime, filteredSkills);
   return {
     runtime,
     enabledPacks: [...enabledPacks],
-    skills: allSkills
+    skills: filteredSkills
   };
 }
 async function buildRuntimeTempView(runtime, skillsRoot, selectedSkills) {
@@ -44102,6 +44110,26 @@ function resolveStatuslineScript(worktreePath) {
   if ((0, import_node_fs.existsSync)(repoStatusline)) return repoStatusline;
   return null;
 }
+function ensureWorktreeSpecialists(worktreePath, mainRepoPath) {
+  const worktreeSpecialistsRoot = import_node_path5.default.join(worktreePath, ".specialists");
+  (0, import_node_fs.mkdirSync)(worktreeSpecialistsRoot, { recursive: true });
+  const specialistDirs = ["default", "user"];
+  for (const dirName of specialistDirs) {
+    const sourceDir = import_node_path5.default.join(mainRepoPath, ".specialists", dirName);
+    if (!(0, import_node_fs.existsSync)(sourceDir)) continue;
+    const targetDir = import_node_path5.default.join(worktreeSpecialistsRoot, dirName);
+    const symlinkTarget = import_node_path5.default.relative(import_node_path5.default.dirname(targetDir), sourceDir);
+    try {
+      const existing = (0, import_node_fs.lstatSync)(targetDir);
+      if (existing.isSymbolicLink() && (0, import_node_fs.readlinkSync)(targetDir) === symlinkTarget) {
+        continue;
+      }
+      (0, import_node_fs.rmSync)(targetDir, { recursive: true, force: true });
+    } catch {
+    }
+    (0, import_node_fs.symlinkSync)(symlinkTarget, targetDir, "dir");
+  }
+}
 function sessionMetaPath(worktreePath) {
   return import_node_path5.default.join(worktreePath, ".xtrm", "session-meta.json");
 }
@@ -44209,6 +44237,12 @@ async function launchWorktreeSession(opts) {
         }
       }
     }
+    try {
+      ensureWorktreeSpecialists(worktreePath, mainRepoRoot);
+    } catch (error48) {
+      const message = error48 instanceof Error ? error48.message : String(error48);
+      console.log(kleur_default.dim(`  warning: could not provision specialist definitions (${message})`));
+    }
     const localSettings = {};
     const statuslinePath = resolveStatuslineScript(worktreePath);
     if (statuslinePath) {
@@ -44735,21 +44769,51 @@ var import_child_process3 = require("child_process");
 var import_fs_extra9 = __toESM(require_lib(), 1);
 var import_path4 = __toESM(require("path"), 1);
 var import_node_os = require("os");
+var MANAGED_PI_EXTENSION_SOURCE_CANDIDATES = [
+  ["packages", "pi-extensions", "extensions"],
+  [".xtrm", "extensions"]
+];
+function resolveFirstExistingPath(rootDir, candidates) {
+  for (const candidate of candidates) {
+    const candidatePath = import_path4.default.join(rootDir, ...candidate);
+    if (import_fs_extra9.default.existsSync(candidatePath)) {
+      return candidatePath;
+    }
+  }
+  return null;
+}
 function resolvePkgRoot() {
   const candidates = [
     import_path4.default.resolve(__dirname, "../.."),
     import_path4.default.resolve(__dirname, "../../..")
   ];
-  for (const c of candidates) {
-    if (import_fs_extra9.default.existsSync(import_path4.default.join(c, ".xtrm", "extensions"))) return c;
+  for (const candidateRoot of candidates) {
+    if (resolveFirstExistingPath(candidateRoot, MANAGED_PI_EXTENSION_SOURCE_CANDIDATES)) {
+      return candidateRoot;
+    }
   }
   return candidates[0];
 }
+function resolveManagedPiExtensionsSourceDir(pkgRoot = resolvePkgRoot()) {
+  return resolveFirstExistingPath(pkgRoot, MANAGED_PI_EXTENSION_SOURCE_CANDIDATES);
+}
+function resolveManagedPiCoreSourceDir(pkgRoot = resolvePkgRoot()) {
+  return resolveFirstExistingPath(pkgRoot, [
+    ["packages", "pi-extensions", "src", "core"],
+    [".xtrm", "extensions", "core"]
+  ]);
+}
 var PI_AGENT_DIR = process.env.PI_AGENT_DIR || import_path4.default.join((0, import_node_os.homedir)(), ".pi", "agent");
 var PI_MCP_ADAPTER_OVERRIDE_DIR = import_path4.default.join(PI_AGENT_DIR, "extensions", "pi-mcp-adapter");
 var PI_MCP_ADAPTER_REQUIRED_ENTRY = "commands.js";
 var PROJECT_EXTENSIONS_ENTRY = "../.xtrm/extensions";
 var PROJECT_SKILLS_ENTRY = "../.xtrm/skills/active/pi";
+var PROJECT_EXTENSION_PACKAGE_ID = "npm:@jaggerxtrm/pi-extensions";
+var CONFLICTING_PI_PACKAGE_IDS = /* @__PURE__ */ new Set(["npm:pi-dex"]);
+var LEGACY_PROJECT_EXTENSION_ENTRIES = /* @__PURE__ */ new Set([
+  PROJECT_EXTENSIONS_ENTRY,
+  ".xtrm/extensions"
+]);
 var MANAGED_EXTENSIONS = [
   { id: "core", displayName: "@xtrm/pi-core", isLibrary: true, required: true },
   { id: "auto-session-name", displayName: "auto-session-name", required: false },
@@ -44779,6 +44843,10 @@ var ALWAYS_GLOBAL_INSTALL_PACKAGE_IDS = /* @__PURE__ */ new Set([
   "npm:pi-gitnexus",
   "npm:pi-serena-tools"
 ]);
+var PROJECT_REQUIRED_PACKAGE_IDS = [
+  PROJECT_EXTENSION_PACKAGE_ID,
+  ...MANAGED_PACKAGES.map((pkg) => pkg.id)
+];
 function getInstalledPiPackages() {
   const result = (0, import_child_process3.spawnSync)("pi", ["list"], { encoding: "utf8", stdio: "pipe" });
   if (result.status !== 0) return [];
@@ -44913,6 +44981,20 @@ function renderPiRuntimePlan(plan) {
     console.log(kleur_default.yellow("  \u26A0 Missing required items.\n"));
   }
 }
+function getProjectRequiredPackageStatuses(installedPkgIds) {
+  return PROJECT_REQUIRED_PACKAGE_IDS.map((packageId) => {
+    const managed = MANAGED_PACKAGES.find((pkg2) => pkg2.id === packageId);
+    const pkg = managed ?? {
+      id: PROJECT_EXTENSION_PACKAGE_ID,
+      displayName: "@jaggerxtrm/pi-extensions",
+      required: true
+    };
+    return {
+      pkg,
+      installed: installedPkgIds.includes(packageId)
+    };
+  });
+}
 function mergePiSyncResults(base, incoming) {
   return {
     extensionsAdded: [...base.extensionsAdded, ...incoming.extensionsAdded],
@@ -44933,10 +45015,63 @@ async function isPackagePresentInPiAgent(agentDir, piPackageId) {
   const packageDir = import_path4.default.join(agentDir, "npm", "node_modules", npmPackageName);
   return import_fs_extra9.default.pathExists(packageDir);
 }
-async function ensureAlwaysGlobalPiPackages(dryRun, log, agentDir = PI_AGENT_DIR, installRunner = (piPackageId) => {
-  const installResult = (0, import_child_process3.spawnSync)("pi", ["install", piPackageId], { stdio: "pipe", encoding: "utf8" });
-  return installResult.status;
-}) {
+var NPMJS_REGISTRY_URL = "https://registry.npmjs.org";
+function runPiPackageInstall(piPackageId, env2) {
+  const installResult = (0, import_child_process3.spawnSync)("pi", ["install", piPackageId], {
+    stdio: "pipe",
+    encoding: "utf8",
+    env: env2
+  });
+  return {
+    status: installResult.status,
+    stdout: installResult.stdout ?? "",
+    stderr: installResult.stderr ?? ""
+  };
+}
+function getPiPackageInstallOutput(result) {
+  return `${result.stdout}
+${result.stderr}`.trim();
+}
+function buildNpmjsRegistryEnv(baseEnv = process.env) {
+  return {
+    ...baseEnv,
+    NPM_CONFIG_REGISTRY: NPMJS_REGISTRY_URL,
+    npm_config_registry: NPMJS_REGISTRY_URL
+  };
+}
+function shouldRetryPiInstallViaNpmjs(piPackageId, output) {
+  if (piPackageId !== PROJECT_EXTENSION_PACKAGE_ID) return false;
+  const normalizedOutput = output.toLowerCase();
+  return normalizedOutput.includes("npmmirror") && normalizedOutput.includes("404");
+}
+function getPiPackageInstallFailureHint(piPackageId, output) {
+  if (!shouldRetryPiInstallViaNpmjs(piPackageId, output)) {
+    return [];
+  }
+  return [
+    `detected registry mirror 404 for ${piPackageId}`,
+    `best fix: npm config set @jaggerxtrm:registry ${NPMJS_REGISTRY_URL}`
+  ];
+}
+function installPiPackageWithFallback(piPackageId, log, installRunner = runPiPackageInstall) {
+  const initialResult = installRunner(piPackageId);
+  const initialOutput = getPiPackageInstallOutput(initialResult);
+  if ((initialResult.status ?? 1) === 0) {
+    return { status: initialResult.status, output: initialOutput, retriedWithNpmjs: false };
+  }
+  if (!shouldRetryPiInstallViaNpmjs(piPackageId, initialOutput)) {
+    return { status: initialResult.status, output: initialOutput, retriedWithNpmjs: false };
+  }
+  log?.(kleur_default.dim(`Detected npmmirror 404 for ${piPackageId}; retrying via ${NPMJS_REGISTRY_URL}`));
+  const retriedResult = installRunner(piPackageId, buildNpmjsRegistryEnv());
+  const retriedOutput = getPiPackageInstallOutput(retriedResult);
+  return {
+    status: retriedResult.status,
+    output: [initialOutput, retriedOutput].filter(Boolean).join("\n"),
+    retriedWithNpmjs: true
+  };
+}
+async function ensureAlwaysGlobalPiPackages(dryRun, log, agentDir = PI_AGENT_DIR, installRunner = runPiPackageInstall) {
   const installed = [];
   const failed = [];
   const packagesToEnsure = MANAGED_PACKAGES.filter((pkg) => ALWAYS_GLOBAL_INSTALL_PACKAGE_IDS.has(pkg.id));
@@ -44948,14 +45083,17 @@ async function ensureAlwaysGlobalPiPackages(dryRun, log, agentDir = PI_AGENT_DIR
       log?.(`[DRY RUN] pi install ${pkg.id}`);
       continue;
     }
-    const installStatus = installRunner(pkg.id);
-    if (installStatus === 0) {
+    const installAttempt = installPiPackageWithFallback(pkg.id, log, installRunner);
+    if (installAttempt.status === 0) {
       installed.push(pkg.id);
-      log?.(`${sym.ok} ${pkg.displayName} (global)`);
+      log?.(`${sym.ok} ${pkg.displayName} (global${installAttempt.retriedWithNpmjs ? ", npmjs fallback" : ""})`);
       continue;
     }
     failed.push(pkg.id);
     log?.(kleur_default.yellow(`\u26A0 ${pkg.displayName} \u2014 global install failed`));
+    for (const hint of getPiPackageInstallFailureHint(pkg.id, installAttempt.output)) {
+      log?.(kleur_default.yellow(`  \u2192 ${hint}`));
+    }
   }
   return { installed, failed };
 }
@@ -45095,30 +45233,90 @@ async function cleanupLegacyProjectExtensionCopies(projectRoot, dryRun, log) {
   }
   return { removed, failed };
 }
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => typeof entry === "string");
+}
+function pruneConflictingPiPackageEntries(entries) {
+  const kept = [];
+  const removed = [];
+  for (const entry of entries) {
+    if (CONFLICTING_PI_PACKAGE_IDS.has(entry)) {
+      removed.push(entry);
+      continue;
+    }
+    kept.push(entry);
+  }
+  return { kept, removed };
+}
+async function pruneConflictingPiPackagesFromSettings(settingsPath, scopeLabel, dryRun, log) {
+  if (!await import_fs_extra9.default.pathExists(settingsPath)) {
+    return [];
+  }
+  let existingSettings = {};
+  try {
+    existingSettings = await import_fs_extra9.default.readJson(settingsPath);
+  } catch {
+    return [];
+  }
+  const existingPackages = normalizeStringArray(existingSettings.packages);
+  const { kept, removed } = pruneConflictingPiPackageEntries(existingPackages);
+  if (removed.length === 0) {
+    return [];
+  }
+  if (dryRun) {
+    log?.(kleur_default.dim(`[DRY RUN] would remove conflicting Pi package(s) from ${scopeLabel}: ${removed.join(", ")}`));
+    return removed;
+  }
+  await import_fs_extra9.default.writeJson(settingsPath, { ...existingSettings, packages: kept }, { spaces: 2 });
+  log?.(kleur_default.dim(`Removed conflicting Pi package(s) from ${scopeLabel}: ${removed.join(", ")}`));
+  return removed;
+}
+async function cleanupConflictingPiPackageSettings(projectRoot, dryRun, log) {
+  await pruneConflictingPiPackagesFromSettings(
+    import_path4.default.join(PI_AGENT_DIR, "settings.json"),
+    "~/.pi/agent/settings.json",
+    dryRun,
+    log
+  );
+  await pruneConflictingPiPackagesFromSettings(
+    import_path4.default.join(projectRoot, ".pi", "settings.json"),
+    `${projectRoot}/.pi/settings.json`,
+    dryRun,
+    log
+  );
+}
 async function updatePiSettings(projectRoot, dryRun, log) {
-  const piSettingsPath = import_path4.default.join(projectRoot, ".pi", "settings.json");
+  const piDirPath = import_path4.default.join(projectRoot, ".pi");
+  const piSettingsPath = import_path4.default.join(piDirPath, "settings.json");
   if (dryRun) {
-    log?.(kleur_default.dim(`[DRY RUN] would update .pi/settings.json`));
+    log?.(kleur_default.dim(`[DRY RUN] would ensure .pi/settings.json with ${PROJECT_EXTENSION_PACKAGE_ID}`));
     return;
   }
+  await import_fs_extra9.default.ensureDir(piDirPath);
   let existingSettings = {};
   try {
     existingSettings = await import_fs_extra9.default.readJson(piSettingsPath);
   } catch {
-  }
-  const existingPackages = (existingSettings.packages ?? []).filter(
-    (p) => !p.startsWith("./extensions/")
-  );
-  await import_fs_extra9.default.ensureDir(import_path4.default.join(projectRoot, ".pi"));
-  await import_fs_extra9.default.writeJson(piSettingsPath, {
+    existingSettings = {};
+  }
+  const LEGACY_PACKAGE_IDS = /* @__PURE__ */ new Set(["npm:@xtrm/pi-extensions", "./extensions/"]);
+  const existingProjectPackages = normalizeStringArray(existingSettings.packages).filter((entry) => !LEGACY_PACKAGE_IDS.has(entry) && !entry.startsWith("./extensions/"));
+  const { kept: existingPackages } = pruneConflictingPiPackageEntries(existingProjectPackages);
+  if (!existingPackages.includes(PROJECT_EXTENSION_PACKAGE_ID)) {
+    existingPackages.push(PROJECT_EXTENSION_PACKAGE_ID);
+  }
+  const existingSkills = normalizeStringArray(existingSettings.skills).filter((entry) => entry !== PROJECT_SKILLS_ENTRY);
+  existingSkills.unshift(PROJECT_SKILLS_ENTRY);
+  const existingExtensions = normalizeStringArray(existingSettings.extensions).filter((entry) => !LEGACY_PROJECT_EXTENSION_ENTRIES.has(entry));
+  const nextSettings = {
     ...existingSettings,
-    extensions: [],
-    // Empty = Pi uses global ~/.pi/agent/extensions/
-    skills: [PROJECT_SKILLS_ENTRY],
-    packages: []
-    // Empty = packages installed globally at ~/.pi/agent/settings.json
-  }, { spaces: 2 });
-  log?.(kleur_default.dim(`Updated .pi/settings.json \u2192 global extensions + packages + .xtrm/skills/active/pi`));
+    extensions: existingExtensions,
+    skills: existingSkills,
+    packages: existingPackages
+  };
+  await import_fs_extra9.default.writeJson(piSettingsPath, nextSettings, { spaces: 2 });
+  log?.(kleur_default.dim(`Updated .pi/settings.json \u2192 ${PROJECT_EXTENSION_PACKAGE_ID} + ${PROJECT_SKILLS_ENTRY}`));
 }
 async function executePiSync(plan, sourceDir, targetDir, opts = {}) {
   const {
@@ -45188,13 +45386,16 @@ async function executePiSync(plan, sourceDir, targetDir, opts = {}) {
       continue;
     }
     try {
-      const r = (0, import_child_process3.spawnSync)("pi", installArgs, { stdio: "pipe", encoding: "utf8" });
-      if (r.status === 0) {
+      const installAttempt = installPiPackageWithFallback(pkg.id, log);
+      if (installAttempt.status === 0) {
         result.packagesInstalled.push(pkg.id);
-        log(`${sym.ok} ${pkg.displayName}`);
+        log(`${sym.ok} ${pkg.displayName}${installAttempt.retriedWithNpmjs ? " (npmjs fallback)" : ""}`);
       } else {
         result.failed.push(pkg.id);
         log(kleur_default.yellow(`\u26A0 ${pkg.displayName} \u2014 install failed`));
+        for (const hint of getPiPackageInstallFailureHint(pkg.id, installAttempt.output)) {
+          log(kleur_default.yellow(`  \u2192 ${hint}`));
+        }
       }
     } catch (err) {
       result.failed.push(pkg.id);
@@ -45203,114 +45404,20 @@ async function executePiSync(plan, sourceDir, targetDir, opts = {}) {
   }
   return result;
 }
-var EXTENSION_SOURCE_DIR = "ext-src";
-async function linkExtensionsToGlobal(repoRoot, dryRun = false, log = (msg) => console.log(kleur_default.dim(`    ${msg}`))) {
-  const globalExtDir = import_path4.default.join(PI_AGENT_DIR, "extensions");
-  const repoExtDir = import_path4.default.join(repoRoot, ".xtrm", EXTENSION_SOURCE_DIR);
-  const linked = [];
-  const failed = [];
-  if (!await import_fs_extra9.default.pathExists(repoExtDir)) {
-    log("No .xtrm/ext-src/ found \u2014 skipping global link");
-    return { linked, failed };
-  }
-  if (dryRun) {
-    log("[DRY RUN] would create extension symlinks in ~/.pi/agent/extensions/");
-    return { linked, failed };
-  }
-  await import_fs_extra9.default.ensureDir(globalExtDir);
-  const coreNodeModulesDir = import_path4.default.join(globalExtDir, "node_modules", "@xtrm");
-  const coreSymlinkPath = import_path4.default.join(coreNodeModulesDir, "pi-core");
-  const coreRelativeTarget = import_path4.default.join("..", "..", "core");
-  try {
-    await import_fs_extra9.default.ensureDir(coreNodeModulesDir);
-    const existing = await import_fs_extra9.default.lstat(coreSymlinkPath).catch(() => null);
-    if (existing) await import_fs_extra9.default.remove(coreSymlinkPath);
-    await import_fs_extra9.default.symlink(coreRelativeTarget, coreSymlinkPath);
-    log("\u2713 @xtrm/pi-core \u2192 global node_modules");
-  } catch (err) {
-    log(kleur_default.yellow(`\u26A0 @xtrm/pi-core symlink: ${err}`));
-  }
-  const entries = await import_fs_extra9.default.readdir(repoExtDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    if (entry.name === "node_modules") continue;
-    const extPath = import_path4.default.join(repoExtDir, entry.name);
-    const globalLink = import_path4.default.join(globalExtDir, entry.name);
-    try {
-      const existing = await import_fs_extra9.default.lstat(globalLink).catch(() => null);
-      if (existing) {
-        if (existing.isSymbolicLink()) {
-          const currentTarget = await import_fs_extra9.default.readlink(globalLink);
-          const resolvedTarget = import_path4.default.resolve(import_path4.default.dirname(globalLink), currentTarget);
-          if (resolvedTarget === import_path4.default.resolve(extPath)) {
-            continue;
-          }
-        }
-        await import_fs_extra9.default.remove(globalLink);
-      }
-      await import_fs_extra9.default.symlink(extPath, globalLink);
-      linked.push(entry.name);
-      log(`\u2713 ${entry.name} \u2192 .xtrm/${EXTENSION_SOURCE_DIR}/${entry.name}`);
-    } catch (err) {
-      failed.push(entry.name);
-      log(kleur_default.red(`\u2717 ${entry.name}: ${err}`));
-    }
-  }
-  return { linked, failed };
-}
-async function ensureNpmPackageExtensionSymlinks(log) {
-  const os9 = require("os");
-  const homeDir = os9.homedir();
-  const extensionsDir = import_path4.default.join(homeDir, ".pi", "agent", "extensions");
-  await import_fs_extra9.default.ensureDir(extensionsDir);
-  const npmPrefix = (0, import_child_process3.spawnSync)("npm", ["prefix", "-g"], { encoding: "utf8" }).stdout.trim();
-  const globalNodeModules = import_path4.default.join(npmPrefix, "lib", "node_modules");
-  const npmPackages = [
-    { packageName: "pi-gitnexus", symlinkName: "gitnexus" },
-    { packageName: "pi-serena-tools", symlinkName: "serena" }
-  ];
-  for (const { packageName, symlinkName } of npmPackages) {
-    const packagePath = import_path4.default.join(globalNodeModules, packageName);
-    const symlinkPath = import_path4.default.join(extensionsDir, symlinkName);
-    const packageExists = await import_fs_extra9.default.pathExists(packagePath);
-    if (!packageExists) {
-      log?.(kleur_default.yellow(`  \u26A0 ${packageName} not found in ${globalNodeModules}, skipping symlink`));
-      continue;
-    }
-    const symlinkExists = await import_fs_extra9.default.lstat(symlinkPath).catch(() => null);
-    if (symlinkExists?.isSymbolicLink()) {
-      const currentTarget = await import_fs_extra9.default.readlink(symlinkPath);
-      const resolvedTarget = import_path4.default.resolve(extensionsDir, currentTarget);
-      if (resolvedTarget === packagePath) {
-        log?.(kleur_default.dim(`  \u2713 ${symlinkName} symlink already correct`));
-        continue;
-      }
-      log?.(kleur_default.dim(`  Removing stale ${symlinkName} symlink`));
-      await import_fs_extra9.default.remove(symlinkPath);
-    } else if (symlinkExists) {
-      log?.(kleur_default.dim(`  Removing stale ${symlinkName} (not a symlink)`));
-      await import_fs_extra9.default.remove(symlinkPath);
-    }
-    const relativeTarget = import_path4.default.relative(extensionsDir, packagePath);
-    await import_fs_extra9.default.symlink(relativeTarget, symlinkPath);
-    log?.(kleur_default.dim(`  Created ${symlinkName} symlink \u2192 ${relativeTarget}`));
-  }
-}
 async function runPiRuntimeSync(opts = {}) {
   const { dryRun = false, isGlobal = false, projectRoot } = opts;
   const pkgRoot = resolvePkgRoot();
-  const sourceDir = import_path4.default.join(pkgRoot, ".xtrm", "extensions");
+  const sourceDir = resolveManagedPiExtensionsSourceDir(pkgRoot);
   const resolvedProjectRoot = projectRoot || process.cwd();
   const log = (msg) => console.log(kleur_default.dim(`    ${msg}`));
-  const emptyResult = {
+  const result = {
     extensionsAdded: [],
     extensionsUpdated: [],
     extensionsRemoved: [],
     packagesInstalled: [],
     failed: []
   };
-  const result = { ...emptyResult };
-  if (!await import_fs_extra9.default.pathExists(sourceDir)) {
+  if (!sourceDir || !await import_fs_extra9.default.pathExists(sourceDir)) {
     console.log(kleur_default.dim("\n  Managed extensions: skipped (not bundled in npm package)\n"));
     return result;
   }
@@ -45318,6 +45425,7 @@ async function runPiRuntimeSync(opts = {}) {
   if (preflight.staleOverride.remediated) {
     result.extensionsRemoved.push("pi-mcp-adapter");
   }
+  await cleanupConflictingPiPackageSettings(resolvedProjectRoot, dryRun, log);
   if (isGlobal) {
     const targetDir = import_path4.default.join(PI_AGENT_DIR, "extensions");
     const plan = await inventoryPiRuntime(sourceDir, targetDir);
@@ -45330,32 +45438,47 @@ async function runPiRuntimeSync(opts = {}) {
     });
     return mergePiSyncResults(result, synced);
   }
-  const linkResult = await linkExtensionsToGlobal(resolvedProjectRoot, dryRun, log);
-  result.extensionsAdded.push(...linkResult.linked);
-  result.failed.push(...linkResult.failed);
-  await ensureNpmPackageExtensionSymlinks(log);
   const installedPkgIds = getInstalledPiPackages();
-  const packageStatuses = [];
-  const missingPackages = [];
-  for (const pkg of MANAGED_PACKAGES) {
-    const isInstalled = installedPkgIds.includes(pkg.id);
-    const status = { pkg, installed: isInstalled };
-    packageStatuses.push(status);
-    if (!isInstalled) missingPackages.push(status);
-  }
+  const packageStatuses = getProjectRequiredPackageStatuses(installedPkgIds);
+  const missingPackages = packageStatuses.filter((status) => !status.installed);
   console.log(kleur_default.bold("\n  Pi Runtime"));
   console.log(kleur_default.dim("  " + "-".repeat(50)));
-  console.log(kleur_default.dim(`  Extensions: ~/.pi/agent/extensions/ \u2192 .xtrm/${EXTENSION_SOURCE_DIR}/`));
-  const pkgOk = packageStatuses.filter((s) => s.installed).length;
+  const extensionPackageInstalled = packageStatuses.some(
+    (status) => status.pkg.id === PROJECT_EXTENSION_PACKAGE_ID && status.installed
+  );
+  console.log(kleur_default.dim(`  Extensions: ${extensionPackageInstalled ? "package installed" : "package missing"} (${PROJECT_EXTENSION_PACKAGE_ID})`));
+  const pkgOk = packageStatuses.filter((status) => status.installed).length;
   console.log(kleur_default.dim(`  Packages:   ${pkgOk}/${packageStatuses.length} installed`));
   if (missingPackages.length > 0) {
-    const names = missingPackages.map((s) => s.pkg.displayName).join(", ");
+    const names = missingPackages.map((status) => status.pkg.displayName).join(", ");
     console.log(kleur_default.yellow(`  Missing:    ${names}`));
   }
   console.log(kleur_default.dim("  " + "-".repeat(50)));
   const legacyCleanup = await cleanupLegacyProjectExtensionCopies(resolvedProjectRoot, dryRun, log);
   result.extensionsRemoved.push(...legacyCleanup.removed);
   result.failed.push(...legacyCleanup.failed);
+  const globalExtDir = import_path4.default.join(PI_AGENT_DIR, "extensions");
+  if (await import_fs_extra9.default.pathExists(globalExtDir)) {
+    const MANAGED_EXT_IDS = new Set(MANAGED_EXTENSIONS.map((e) => e.id));
+    const STALE_SYMLINKS = /* @__PURE__ */ new Set([...MANAGED_EXT_IDS, "core", "gitnexus", "serena"]);
+    const globalEntries = await import_fs_extra9.default.readdir(globalExtDir, { withFileTypes: true });
+    for (const entry of globalEntries) {
+      if (entry.isSymbolicLink() && STALE_SYMLINKS.has(entry.name)) {
+        if (!dryRun) {
+          await import_fs_extra9.default.remove(import_path4.default.join(globalExtDir, entry.name));
+        }
+        result.extensionsRemoved.push(entry.name);
+        log(`Removed stale global symlink: ${entry.name}`);
+      }
+    }
+    const staleNodeModules = import_path4.default.join(globalExtDir, "node_modules");
+    if (await import_fs_extra9.default.pathExists(staleNodeModules)) {
+      if (!dryRun) {
+        await import_fs_extra9.default.remove(staleNodeModules);
+      }
+      log("Removed stale global extensions/node_modules");
+    }
+  }
   for (const status of missingPackages) {
     const { pkg } = status;
     if (dryRun) {
@@ -45363,13 +45486,16 @@ async function runPiRuntimeSync(opts = {}) {
       continue;
     }
     try {
-      const r = (0, import_child_process3.spawnSync)("pi", ["install", pkg.id], { stdio: "pipe", encoding: "utf8" });
-      if (r.status === 0) {
+      const installAttempt = installPiPackageWithFallback(pkg.id, log);
+      if (installAttempt.status === 0) {
         result.packagesInstalled.push(pkg.id);
-        log(`${sym.ok} ${pkg.displayName}`);
-      } else {
-        result.failed.push(pkg.id);
-        log(kleur_default.yellow(`\u26A0 ${pkg.displayName} \u2014 install failed`));
+        log(`${sym.ok} ${pkg.displayName}${installAttempt.retriedWithNpmjs ? " (npmjs fallback)" : ""}`);
+        continue;
+      }
+      result.failed.push(pkg.id);
+      log(kleur_default.yellow(`\u26A0 ${pkg.displayName} \u2014 install failed`));
+      for (const hint of getPiPackageInstallFailureHint(pkg.id, installAttempt.output)) {
+        log(kleur_default.yellow(`  \u2192 ${hint}`));
       }
     } catch (err) {
       result.failed.push(pkg.id);
@@ -45391,12 +45517,8 @@ async function runPiRuntimeSync(opts = {}) {
     }
   }
   await updatePiSettings(resolvedProjectRoot, dryRun, log);
-  const requiredFailed = missingPackages.filter(
-    (s) => s.pkg.required && result.failed.includes(s.pkg.id)
-  );
-  if (missingPackages.length === 0 || result.failed.length === 0) {
-    console.log(t.success("  \u2713 All required items present.\n"));
-  } else if (requiredFailed.length === 0) {
+  const requiredFailed = missingPackages.filter((status) => status.pkg.required && result.failed.includes(status.pkg.id));
+  if (requiredFailed.length === 0) {
     console.log(t.success("  \u2713 All required items present.\n"));
   } else {
     console.log(kleur_default.yellow("  \u26A0 Missing required items.\n"));
@@ -45633,21 +45755,21 @@ function hasSettingsEntry(entries, expectedEntry) {
   });
 }
 async function getPiProjectPointer(projectRoot) {
-  const projectExtensionsDir = import_path7.default.join(projectRoot, ".xtrm", "extensions");
   const settingsPath = import_path7.default.join(projectRoot, ".pi", "settings.json");
-  const hasProjectExtensions = await import_fs_extra11.default.pathExists(projectExtensionsDir);
   const hasSettingsFile = await import_fs_extra11.default.pathExists(settingsPath);
   if (!hasSettingsFile) {
-    return { hasProjectExtensions, pointsToXtrmExtensions: false };
+    return { hasProjectSettings: false, hasProjectExtensionPackage: false, pointsToXtrmExtensions: false };
   }
   try {
     const settings = await import_fs_extra11.default.readJson(settingsPath);
+    const packageEntries = Array.isArray(settings.packages) ? settings.packages.filter((entry) => typeof entry === "string") : [];
     return {
-      hasProjectExtensions,
+      hasProjectSettings: true,
+      hasProjectExtensionPackage: packageEntries.includes("npm:@jaggerxtrm/pi-extensions"),
       pointsToXtrmExtensions: hasSettingsEntry(settings.extensions, "../.xtrm/extensions")
     };
   } catch {
-    return { hasProjectExtensions, pointsToXtrmExtensions: false };
+    return { hasProjectSettings: true, hasProjectExtensionPackage: false, pointsToXtrmExtensions: false };
   }
 }
 function createPiCommand() {
@@ -45671,31 +45793,29 @@ function createPiCommand() {
     const projectRoot = resolveProjectRoot();
     const pointer = await getPiProjectPointer(projectRoot);
     const bundleRoot = await findRepoRoot();
-    const sourceDir = import_path7.default.join(bundleRoot, ".xtrm", "extensions");
+    const sourceDir = resolveManagedPiExtensionsSourceDir(bundleRoot);
     const globalTargetDir = import_path7.default.join(PI_AGENT_DIR4, "extensions");
-    if (!await import_fs_extra11.default.pathExists(sourceDir)) {
+    if (!sourceDir || !await import_fs_extra11.default.pathExists(sourceDir)) {
       console.log(kleur_default.dim("  \u25CB managed extensions not bundled in this install\n"));
       return;
     }
     const plan = await inventoryPiRuntime(sourceDir, globalTargetDir);
     const pkgOk = plan.packages.filter((s) => s.installed).length;
-    if (pointer.hasProjectExtensions && pointer.pointsToXtrmExtensions) {
+    const projectScoped = pointer.hasProjectExtensionPackage || pointer.pointsToXtrmExtensions;
+    if (projectScoped) {
       console.log(kleur_default.dim("  Scope:      project"));
-      console.log(kleur_default.dim("  Extensions: via .xtrm/extensions (.pi/settings.json)"));
+      console.log(kleur_default.dim(`  Extensions: package mode (npm:@jaggerxtrm/pi-extensions${pointer.hasProjectExtensionPackage ? "" : " missing"})`));
     } else {
       console.log(kleur_default.dim("  Scope:      global"));
       const extOk = plan.extensions.filter((s) => s.installed && !s.stale).length;
       console.log(kleur_default.dim(`  Extensions: ${extOk}/${plan.extensions.length} up-to-date`));
     }
     console.log(kleur_default.dim(`  Packages:   ${pkgOk}/${plan.packages.length} installed`));
-    if (pointer.hasProjectExtensions && !pointer.pointsToXtrmExtensions) {
-      console.log(kleur_default.yellow("  Settings:   .pi/settings.json is not pointing to ../.xtrm/extensions"));
-    }
     if (plan.missingPackages.length > 0) {
       const names = plan.missingPackages.map((s) => s.pkg.displayName).join(", ");
       console.log(kleur_default.yellow(`  Packages:   ${names}`));
     }
-    if (!pointer.pointsToXtrmExtensions) {
+    if (!projectScoped) {
       if (plan.missingExtensions.length > 0) {
         const names = plan.missingExtensions.map((s) => s.ext.displayName).join(", ");
         console.log(kleur_default.yellow(`  Missing:    ${names}`));
@@ -45708,13 +45828,16 @@ function createPiCommand() {
         console.log(kleur_default.red(`  Orphaned:   ${plan.orphanedExtensions.join(", ")}`));
       }
     }
-    const projectModeOk = pointer.hasProjectExtensions ? pointer.pointsToXtrmExtensions : true;
-    const hasGlobalDrift = !pointer.pointsToXtrmExtensions && !plan.allPresent;
+    const hasProjectSettingsDrift = !pointer.hasProjectSettings || !pointer.hasProjectExtensionPackage;
+    const hasGlobalDrift = !projectScoped && !plan.allPresent;
     const hasPackageDrift = plan.missingPackages.length > 0;
-    if (projectModeOk && !hasGlobalDrift && !hasPackageDrift) {
+    if (!hasProjectSettingsDrift && !hasGlobalDrift && !hasPackageDrift) {
       console.log(t.success("\n  \u2713 Pi runtime configuration looks healthy\n"));
       return;
     }
+    if (hasProjectSettingsDrift) {
+      console.log(kleur_default.yellow("  Settings:   .pi/settings.json missing managed npm:@jaggerxtrm/pi-extensions entry"));
+    }
     console.log(kleur_default.dim("\n  \u2192 run: xt pi reload\n"));
   });
   cmd.command("doctor").description("Diagnostic checks: pi installed, extensions deployed, packages present, orphaned extensions").action(async () => {
@@ -45745,7 +45868,8 @@ function createPiCommand() {
     const projectRoot = resolveProjectRoot();
     const pointer = await getPiProjectPointer(projectRoot);
     const bundleRoot = await findRepoRoot();
-    const sourceDir = import_path7.default.join(bundleRoot, ".xtrm", "extensions");
+    const sourceDir = resolveManagedPiExtensionsSourceDir(bundleRoot);
+    const coreSourceDir = resolveManagedPiCoreSourceDir(bundleRoot);
     const globalTargetDir = import_path7.default.join(PI_AGENT_DIR4, "extensions");
     try {
       const staleOverride = await remediateStalePiMcpAdapterOverride(false);
@@ -45762,7 +45886,7 @@ function createPiCommand() {
       allOk = false;
     }
     try {
-      const coreStatus = await ensureCorePackageSymlink(import_path7.default.join(sourceDir, "core"), projectRoot, false);
+      const coreStatus = coreSourceDir ? await ensureCorePackageSymlink(coreSourceDir, projectRoot, false) : "missing-source";
       if (coreStatus === "repaired" || coreStatus === "created") {
         console.log(t.success("  \u2713 repaired .xtrm/extensions/node_modules/@xtrm/pi-core symlink"));
       } else if (coreStatus === "ok") {
@@ -45774,15 +45898,21 @@ function createPiCommand() {
       console.log(kleur_default.yellow(`  \u26A0 failed to ensure @xtrm/pi-core symlink: ${error48}`));
       allOk = false;
     }
-    if (!await import_fs_extra11.default.pathExists(sourceDir)) {
+    if (!sourceDir || !await import_fs_extra11.default.pathExists(sourceDir)) {
       console.log(kleur_default.dim("  \u25CB managed extensions not bundled in this install"));
     } else {
       const plan = await inventoryPiRuntime(sourceDir, globalTargetDir);
-      if (pointer.hasProjectExtensions && pointer.pointsToXtrmExtensions) {
-        console.log(t.success("  \u2713 project runtime points to .xtrm/extensions"));
-      } else if (pointer.hasProjectExtensions) {
-        console.log(kleur_default.yellow("  \u26A0 .pi/settings.json does not include ../.xtrm/extensions"));
+      const projectScoped = pointer.hasProjectExtensionPackage || pointer.pointsToXtrmExtensions;
+      if (!pointer.hasProjectSettings) {
+        console.log(kleur_default.yellow("  \u26A0 missing .pi/settings.json; run xt pi reload to bootstrap project Pi settings"));
         allOk = false;
+      } else if (projectScoped) {
+        if (pointer.hasProjectExtensionPackage) {
+          console.log(t.success("  \u2713 project runtime uses npm:@jaggerxtrm/pi-extensions"));
+        } else {
+          console.log(kleur_default.yellow("  \u26A0 legacy project extension pointer detected; run xt pi reload to migrate"));
+          allOk = false;
+        }
       } else if (plan.missingExtensions.length === 0 && plan.staleExtensions.length === 0 && plan.orphanedExtensions.length === 0) {
         console.log(t.success(`  \u2713 global extensions deployed (${plan.extensions.length})`));
       } else {
@@ -45997,12 +46127,16 @@ async function installFromRegistry(params) {
         installed: 0,
         upToDate: drift.upToDate.length,
         driftedSkipped: drift.drifted.length,
-        forced: 0
+        forced: 0,
+        expectedInstalls: 0,
+        missingSourceSkipped: 0
       };
     }
   }
   let installed = 0;
   let forced = 0;
+  let expectedInstalls = 0;
+  let missingSourceSkipped = 0;
   for (const asset of Object.values(registry2.assets)) {
     for (const [filePath] of Object.entries(asset.files)) {
       const relativePath = toUserRelativePath(asset.source_dir, filePath);
@@ -46025,6 +46159,13 @@ async function installFromRegistry(params) {
       if (isDrifted && force) {
         forced += 1;
       }
+      expectedInstalls += 1;
+      const sourceExists = await import_fs_extra13.default.pathExists(sourcePath);
+      if (!sourceExists) {
+        missingSourceSkipped += 1;
+        console.log(kleur_default.yellow(`  \u26A0 Skipping missing source file: ${toPosix2(import_path8.default.relative(packageRoot, sourcePath))}`));
+        continue;
+      }
       if (dryRun) {
         const action = isDrifted ? "overwrite" : "install";
         console.log(kleur_default.dim(`  [DRY RUN] would ${action} ${relativePath}`));
@@ -46040,7 +46181,9 @@ async function installFromRegistry(params) {
     installed,
     upToDate: upToDateSet.size,
     driftedSkipped: force ? 0 : driftedSet.size,
-    forced
+    forced,
+    expectedInstalls,
+    missingSourceSkipped
   };
 }
 
@@ -46558,9 +46701,8 @@ function verifyClaudeRuntime(projectRoot) {
   return fallbackResult;
 }
 async function verifyPiRuntime(projectRoot) {
-  const pkgRoot = resolvePkgRoot2();
-  const sourceDir = import_path10.default.join(pkgRoot, ".xtrm", "extensions");
-  if (!await import_fs_extra16.default.pathExists(sourceDir)) {
+  const sourceDir = resolveManagedPiExtensionsSourceDir();
+  if (!sourceDir || !await import_fs_extra16.default.pathExists(sourceDir)) {
     return {
       extensions: [],
       packages: [],
@@ -46586,16 +46728,6 @@ ${gnStatus.stderr ?? ""}`.toLowerCase();
   const instructionHeaders = agentsMd || claudeMd;
   return { beadsInitialized, gitnexusIndexed, instructionHeaders };
 }
-function resolvePkgRoot2() {
-  const candidates = [
-    import_path10.default.resolve(__dirname, "../.."),
-    import_path10.default.resolve(__dirname, "../../..")
-  ];
-  for (const c of candidates) {
-    if (import_fs_extra16.default.existsSync(import_path10.default.join(c, ".xtrm", "extensions"))) return c;
-  }
-  return candidates[0];
-}
 async function runInitVerification(projectRoot) {
   const machinePlan = verifyMachineBootstrap();
   const claudeResult = verifyClaudeRuntime(projectRoot);
@@ -48617,7 +48749,7 @@ async function runProjectInit(opts = {}) {
   const userXtrmDir = ctx.targets[0];
   const registryPath = import_path15.default.join(packageRoot, ".xtrm", "registry.json");
   const registry2 = await import_fs_extra21.default.readJson(registryPath);
-  await installFromRegistry({
+  const registryInstallStats = await installFromRegistry({
     packageRoot,
     registry: registry2,
     userXtrmDir,
@@ -48625,6 +48757,10 @@ async function runProjectInit(opts = {}) {
     force: false,
     yes: true
   });
+  if (registryInstallStats.missingSourceSkipped > 0) {
+    console.log(kleur_default.yellow(`  \u26A0 Registry/source mismatch: skipped ${registryInstallStats.missingSourceSkipped} missing source file${registryInstallStats.missingSourceSkipped === 1 ? "" : "s"}.`));
+    console.log(kleur_default.yellow("    Init continued, but some skills/files may be absent until registry payload is corrected."));
+  }
   await scaffoldSkillsDefaultFromPackage({ packageRoot, userXtrmDir, dryRun: false });
   const mcpSync = await syncProjectMcpConfig(projectRoot, { preserveExistingFile: true });
   if (mcpSync.wroteFile) {