create-egregore 0.20.2 → 0.20.4

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.20.2
+// egregore-launcher-version: 0.20.4
 //
 // egregore — launch and browse Egregore instances from your terminal.
 // Installed by create-egregore. Reads ~/.egregore/instances.json.
@@ -33,7 +33,7 @@ const crypto = require("node:crypto");
 const { spawnSync, spawn } = require("node:child_process");
 const readline = require("node:readline");
 
-const VERSION = "0.20.2";
+const VERSION = "0.20.4";
 const REGISTRY = path.join(os.homedir(), ".egregore", "instances.json");
 const DEFAULT_FILE = path.join(os.homedir(), ".egregore", "default");
 const UPDATE_CACHE_FILE = path.join(os.homedir(), ".egregore", "update-check.json");
@@ -702,9 +702,8 @@ function codexSupportMessage(egregoreDir) {
     "  .codex/hooks.json",
     "  .codex/hooks/",
     "",
-    "Automatic repair did not complete. Retry with:",
-    "  npx -y create-egregore@latest --refresh-launcher",
-    "Then rerun egregore.",
+    "Restore this instance using its installed runtime version, then rerun egregore.",
+    "A global CLI refresh does not repair instance files.",
     "Egregore workflows appear as slash commands. In Codex, invoke them with the matching $skill token or ask in natural language.",
   ].join("\n");
 }
@@ -735,7 +734,7 @@ function piSupportMessage(egregoreDir) {
     "Pi meta-harness support is missing from this Egregore checkout.",
     `  path: ${egregoreDir}`,
     "",
-    "Run npx -y create-egregore@latest to install the packaged Pi runtime, then rerun egregore.",
+    "Restore this instance using its installed runtime version, then rerun egregore.",
   ].join("\n");
 }
 
@@ -754,31 +753,10 @@ function primeSupportMessage(egregoreDir) {
     "Prime Agent runtime support is missing from this Egregore checkout.",
     `  path: ${egregoreDir}`,
     "",
-    "Run npx -y create-egregore@latest to install the packaged Prime Agent runtime, then rerun egregore.",
+    "Restore this instance using its installed runtime version, then rerun egregore.",
   ].join("\n");
 }
 
-function repairPortableRuntime(egregoreDir, runtime) {
-  const label = runtimeLabel(runtime);
-  process.stdout.write(`\n  ${CYAN}↻${RESET} ${BOLD}Repairing ${label} support${RESET}${DIM} — updating this checkout${RESET}\n`);
-  const result = spawnSync(
-    "npx",
-    ["-y", `${PUBLIC_NPX_PACKAGE}@latest`, "--refresh-launcher"],
-    {
-      cwd: egregoreDir,
-      stdio: "inherit",
-      env: { ...process.env, EGREGORE_RUNTIME_REPAIR: runtime },
-      timeout: 3 * 60 * 1000,
-    },
-  );
-  if (result.error || result.status !== 0) {
-    process.stderr.write(`  ${YELLOW}!${RESET} Automatic ${label} repair failed; the checkout was left in place.\n`);
-    return false;
-  }
-  process.stdout.write(`  ${GREEN}✓${RESET} ${label} support repaired\n\n`);
-  return true;
-}
-
 // Minimal y/N line prompt for pre-launch decisions (the TUI select machinery
 // is torn down by the time launch() runs).
 function confirmLine(question) {
@@ -908,19 +886,15 @@ async function launch(inst, runtimeOverride) {
     }
   }
   if (runtime === "codex") {
-    if (!hasCodexCoreSupport(inst.path)) {
-      if (!repairPortableRuntime(inst.path, runtime) || !hasCodexCoreSupport(inst.path)) {
-        die(codexSupportMessage(inst.path));
-      }
-    }
+    // Launching never changes an instance's runtime or release channel.
+    if (!hasCodexCoreSupport(inst.path)) die(codexSupportMessage(inst.path));
     const skillsInstalled = installCodexSkills(inst.path);
     const cardRendered = await renderCodexStartupCard(inst.path);
     if (!skillsInstalled || !cardRendered) {
       die(codexSupportMessage(inst.path));
     }
   } else if (runtime === "pi") {
-    if (!hasPiCoreSupport(inst.path) &&
-        (!repairPortableRuntime(inst.path, runtime) || !hasPiCoreSupport(inst.path))) {
+    if (!hasPiCoreSupport(inst.path)) {
       die(piSupportMessage(inst.path));
     }
   }
@@ -931,10 +905,7 @@ async function launch(inst, runtimeOverride) {
     // check + the trust-flag probe, which shells out to the binary), then a
     // single handoff line explains the remaining in-harness startup.
     const stopLoader = startSpinner("Starting Prime Agent");
-    let coreOk = hasPrimeCoreSupport(inst.path);
-    if (!coreOk && repairPortableRuntime(inst.path, runtime)) {
-      coreOk = hasPrimeCoreSupport(inst.path);
-    }
+    const coreOk = hasPrimeCoreSupport(inst.path);
     launchArgs = coreOk ? runtimeLaunchArgs(runtime, inst.path) : null;
     stopLoader();
     if (!coreOk) die(primeSupportMessage(inst.path));
@@ -1797,9 +1768,10 @@ async function cmdConnect(args) {
       console.log(`        ${DIM}${line}${RESET}`);
     }
   }
+  // Connect is an instance-scoped overlay; never refresh other runtimes here.
   const runtimeRefresh = spawnSync(
     "npx",
-    ["-y", `${PUBLIC_NPX_PACKAGE}@latest`, "--refresh-launcher"],
+    ["-y", `${PUBLIC_NPX_PACKAGE}@${VERSION}`, "--refresh-connect"],
     {
       cwd: inst.path,
       encoding: "utf-8",
@@ -1811,7 +1783,7 @@ async function cmdConnect(args) {
     console.log(`        ${GREEN}✓${RESET} Connect features installed`);
   } else {
     console.log(`        ${YELLOW}!${RESET} Connect features will retry on the next update`);
-    console.log(`          ${DIM}npx -y ${PUBLIC_NPX_PACKAGE}@latest --refresh-launcher${RESET}`);
+    console.log(`          ${DIM}npx -y ${PUBLIC_NPX_PACKAGE}@${VERSION} --refresh-connect${RESET}`);
   }
   console.log("");
   console.log(`  ${GREEN}✓${RESET} ${BOLD}${inst.slug}${RESET} is connected. Local files remain the source of truth.`);

package/bin/cli.js

@@ -25,27 +25,8 @@ const {
   ghCliExists,
   tryGhAuthOrLogin,
 } = require("../lib/auth");
-const {
-  hasCodexRuntimeSupport,
-  installCodexRuntime,
-  reportCodexRuntimeSummary,
-} = require("../lib/codex-runtime");
-const {
-  hasPiRuntimeSupport,
-  installPiRuntime,
-  reportPiRuntimeSummary,
-} = require("../lib/pi-runtime");
-const {
-  hasPrimeRuntimeSupport,
-  installPrimeRuntime,
-  reportPrimeRuntimeSummary,
-} = require("../lib/prime-runtime");
-const {
-  connectEligibility,
-  fetchConnectRuntimePack,
-  installConnectRuntime,
-  reportConnectRuntimeSummary,
-} = require("../lib/connect-runtime");
+// Global CLI maintenance never installs or reconciles instance runtimes.
+// Fresh installation and explicit instance updates own those writes.
 const {
   install,
   ghApi,
@@ -120,45 +101,6 @@ function assistantLabel(runtime) {
   return "Claude Code";
 }
 
-async function upgradePortableRuntimesForExisting(instances) {
-  for (const inst of instances) {
-    if (!inst || !inst.path || !fs.existsSync(inst.path)) continue;
-    try {
-      // Fetch and validate the private overlay before pruning the old public
-      // bundle. During the one-time ownership migration, an API outage must
-      // leave an existing Connect installation untouched.
-      const eligibility = connectEligibility(inst.path);
-      const connectPack = eligibility.eligible
-        ? await fetchConnectRuntimePack(inst.path)
-        : null;
-      const summary = installCodexRuntime(inst.path);
-      const ready = hasCodexRuntimeSupport(inst.path);
-      reportCodexRuntimeSummary(summary, ui, {
-        label: `Codex runtime for ${inst.slug || inst.name || path.basename(inst.path)}`,
-        includeConflicts: !ready,
-      });
-      const piSummary = installPiRuntime(inst.path);
-      const piReady = hasPiRuntimeSupport(inst.path);
-      reportPiRuntimeSummary(piSummary, ui, {
-        label: `Pi meta-harness for ${inst.slug || inst.name || path.basename(inst.path)}`,
-        includeConflicts: !piReady,
-      });
-      const primeSummary = installPrimeRuntime(inst.path);
-      const primeReady = hasPrimeRuntimeSupport(inst.path);
-      reportPrimeRuntimeSummary(primeSummary, ui, {
-        label: `Prime Agent runtime for ${inst.slug || inst.name || path.basename(inst.path)}`,
-        includeConflicts: !primeReady,
-      });
-      const connectSummary = await installConnectRuntime(inst.path, { validatedPack: connectPack });
-      reportConnectRuntimeSummary(connectSummary, ui, {
-        label: `Connect features for ${inst.slug || inst.name || path.basename(inst.path)}`,
-      });
-    } catch (err) {
-      ui.warn(`Could not refresh shell-runtime support for ${inst.path}: ${err.message}`);
-    }
-  }
-}
-
 async function chooseRuntime(args) {
   if (args.runtime) {
     try {
@@ -199,7 +141,6 @@ async function chooseRuntime(args) {
 }
 
 async function upgradeLauncherFromExisting(instances) {
-  await upgradePortableRuntimesForExisting(instances);
   const inst = instances.find((entry) => entry && entry.path && fs.existsSync(entry.path));
   if (!inst) return null;
   try {
@@ -433,7 +374,7 @@ function showHelp() {
   ui.info("  --force           Skip the in-repo detection check");
   ui.info("  --no-autolaunch   Don't launch the harness at the end (for CI)");
   ui.info("  --no-screens      Skip the full-screen welcome/ready bookends");
-  ui.info("  --refresh-launcher Refresh the Egregore CLI and runtime packs, then exit");
+  ui.info("  --refresh-launcher Refresh only the global Egregore CLI, then exit");
   ui.info("  -h, --help        Show this help");
   ui.info("");
 }
@@ -513,7 +454,6 @@ async function main() {
       ui.error("No installed Egregore instance was found. Run create-egregore without --refresh-launcher.");
       process.exit(1);
     }
-    await upgradePortableRuntimesForExisting(instances);
     const alias = await installLauncherBinary(instances[0].path, ui);
     if (!alias || !alias.binaryPath) {
       ui.error("Could not refresh the Egregore CLI.");
@@ -603,75 +543,20 @@ async function main() {
 }
 
 async function tokenFlow(api, token, ctx) {
-  const s = ui.spinner("Claiming setup token...");
-  let data;
-  try {
-    data = await api.claimToken(token);
-    s.stop(`Claimed — setting up ${ui.bold(data.org_name)}`);
-  } catch (err) {
-    s.fail("Token claim failed");
-    ui.error(err.message);
-    ui.info("");
-    ui.info("The token may have expired or already been used.");
-    ui.info("Visit egregore.xyz to get a new one, or run without --token:");
-    ui.info("  npx -y create-egregore@latest");
-    process.exit(1);
-  }
-
-  // Joiner tokens don't include a github_token — try gh CLI first. If gh is
-  // installed but logged out, run gh auth login instead of device flow.
-  if (!data.github_token || data.needs_cli_auth) {
-    const ghAuth = tryGhAuthOrLogin(ui, data.needs_cli_auth ? { mode: "join" } : {});
-    if (ghAuth) {
-      ui.success(`Using your ${ui.bold("gh")} CLI auth${ghAuth.user ? ` (${ghAuth.user})` : ""}`);
-      data.github_token = ghAuth.token;
-    } else if (ghCliExists()) {
-      ui.error("GitHub CLI auth did not complete.");
-      ui.info(`Run ${ui.bold("gh auth login")} and then re-run this command.`);
-      process.exit(1);
-    } else {
+  const { installFromToken } = require("../lib/token-install");
+  await installFromToken(api, token, ctx, {
+    ui, install, request: ghApi,
+    authenticate: async (forceLogin) => {
+      const auth = tryGhAuthOrLogin(ui, { mode: "join", requireRepoScope: true, forceLogin });
+      if (auth) return auth;
+      if (ghCliExists()) return null;
       if (!canUseInteractiveBrowserFlow()) {
         explainNoGhHeadless(ui);
-        process.exit(1);
+        return null;
       }
-      ui.info("\nSign in to your GitHub to complete setup.\n");
-      try {
-        data.github_token = await deviceFlow(ui, data.needs_cli_auth ? { mode: "join" } : {});
-        ui.success("Authenticated with GitHub");
-      } catch (err) {
-        ui.error(`GitHub auth failed: ${err.message}`);
-        process.exit(1);
-      }
-    }
-  }
-
-  // Token-mode setups already have their repo list baked in server-side. If
-  // the user's current working repo happens to match a managed-repo name, skip
-  // the clone/pull/configure step for it so we don't clobber uncommitted work.
-  const skipRepos = new Set();
-  if (ctx.prefilledRepo && Array.isArray(data.repos)) {
-    for (const r of data.repos) {
-      const n = typeof r === "string" ? r : r && r.name;
-      if (n && n === ctx.prefilledRepo.name) skipRepos.add(n);
-    }
-  }
-  try {
-    await install(data, ui, ctx.targetDir, {
-      skipRepos,
-      noAutolaunch: ctx.noAutolaunch,
-      noScreens: ctx.noScreens,
-      flowVariant: ctx.flowVariant,
-      runtime: ctx.runtime,
-    });
-    if (ctx.prefilledRepo && skipRepos.size === 0) {
-      console.log("");
-      ui.info(`Tip: add your current repo to managed_repos with:`);
-      ui.info(`  /add ${ctx.prefilledRepo.toplevel || `../${ctx.prefilledRepo.localName}`}`);
-    }
-  } catch (err) {
-    ui.error(`Install failed: ${err.message}`);
-    process.exit(1);
-  }
+      return { token: await deviceFlow(ui, { mode: "join", scope: "repo" }) };
+    },
+  });
 }
 
 async function interactiveFlow(api, ctx) {

package/lib/api.js

@@ -63,8 +63,12 @@ class EgregoreAPI {
     this.base = (baseUrl || DEFAULT_API).replace(/\/$/, "");
   }
 
-  async claimToken(token) {
-    return request("GET", `${this.base}/api/org/claim/${token}`);
+  async claimToken(token, githubToken) {
+    // Old APIs reject POST without consuming a one-time setup token. Never
+    // silently downgrade an authenticated retry to the legacy GET protocol.
+    return request(githubToken ? "POST" : "GET", `${this.base}/api/org/claim/${token}`, {
+      headers: githubToken ? { Authorization: `Bearer ${githubToken}` } : {},
+    });
   }
 
   async getOrgs(githubToken) {

package/lib/auth.js

@@ -212,7 +212,7 @@ function runGhAuthLogin(ui, opts = {}) {
 
 function tryGhAuthOrLogin(ui, opts = {}) {
   const existing = tryGhAuth();
-  if (existing) return existing;
+  if (existing && !opts.forceLogin && !(opts.requireRepoScope && existing.hasRepoScope === false)) return existing;
   if (!ghCliExists()) return null;
   return runGhAuthLogin(ui, opts);
 }

package/lib/install-access.js

@@ -0,0 +1,87 @@
+/** Repository access for a connected install. Never accept unrelated invitations. */
+class RepositoryAccessError extends Error {
+  constructor(message, canReauthenticate = false) {
+    super(message);
+    this.name = "RepositoryAccessError";
+    this.canReauthenticate = canReauthenticate;
+  }
+}
+
+function repositoryFromUrl(value) {
+  const url = new URL(value);
+  const name = url.pathname.replace(/^\//, "").replace(/\.git$/, "");
+  if (url.protocol !== "https:" || url.hostname !== "github.com" || url.username || url.password ||
+      url.search || url.hash || !/^[\w.-]+\/[\w.-]+$/.test(name)) {
+    throw new Error("Setup contains an invalid GitHub repository URL.");
+  }
+  return name;
+}
+
+function requiredRepositories(data) {
+  const names = [repositoryFromUrl(data.fork_url), repositoryFromUrl(data.memory_url)];
+  for (const entry of data.repos || []) {
+    const name = typeof entry === "string" ? entry : entry?.name;
+    if (!/^[\w.-]+$/.test(name || "") || name === "." || name === "..") {
+      throw new Error("Setup contains an invalid managed repository name.");
+    }
+    names.push(repositoryFromUrl(`https://github.com/${data.github_org}/${name}`));
+  }
+  return [...new Map(names.map(name => [name.toLowerCase(), name])).values()];
+}
+
+function matchesIdentity(data, user) {
+  // IDs survive account renames. Older payloads can only be checked by login.
+  if (data.github_id != null) return String(data.github_id) === String(user?.id);
+  return !!data.github_username && data.github_username.toLowerCase() === user?.login?.toLowerCase();
+}
+
+async function ensureRepositoryAccess(data, ui, { request, sleep = ms => new Promise(r => setTimeout(r, ms)) }) {
+  const token = data.github_token;
+  if (!token) throw new RepositoryAccessError("GitHub authentication is required for this installation.", true);
+  const who = await request("GET", "/user", token);
+  if (who.status !== 200) throw new RepositoryAccessError(`GitHub identity check failed (HTTP ${who.status}).`, who.status === 401 || who.status === 403);
+  if (!matchesIdentity(data, who.data)) throw new RepositoryAccessError("Your active GitHub account does not match the account that accepted this invitation. Sign in to that account and retry.");
+
+  const required = requiredRepositories(data);
+  async function missingRepos() {
+    const missing = [];
+    for (const name of required) {
+      const result = await request("GET", `/repos/${name}`, token);
+      if (result.status === 200 && result.data?.permissions?.pull !== false) continue;
+      if (![401, 403, 404, 200].includes(result.status)) {
+        throw new RepositoryAccessError(`GitHub access check for ${name} failed (HTTP ${result.status}). Retry the same install command.`);
+      }
+      missing.push(name);
+    }
+    return missing;
+  }
+  let missing = await missingRepos();
+  if (!missing.length) return required;
+  const wanted = new Set(missing.map(name => name.toLowerCase()));
+  // Collect before accepting: removing invitations while paginating would skip entries.
+  const invitations = [];
+  for (let page = 1; ; page++) {
+    const result = await request("GET", `/user/repository_invitations?per_page=100&page=${page}`, token);
+    if (result.status !== 200 || !Array.isArray(result.data)) {
+      throw new RepositoryAccessError(`Could not list GitHub repository invitations (HTTP ${result.status}); access is missing for ${missing.join(", ")}.`, [401, 403].includes(result.status));
+    }
+    invitations.push(...result.data.filter(inv => wanted.has(inv.repository?.full_name?.toLowerCase())));
+    if (result.data.length < 100) break;
+    if (page === 100) throw new RepositoryAccessError("GitHub returned too many invitation pages. Retry after reviewing pending invitations.");
+  }
+  let acceptanceError;
+  for (const inv of invitations) {
+    const result = await request("PATCH", `/user/repository_invitations/${inv.id}`, token);
+    if (result.status >= 200 && result.status < 300) ui.success(`Accepted invite to ${inv.repository.full_name}`);
+    else acceptanceError = new RepositoryAccessError(`Could not accept the GitHub invitation for ${inv.repository.full_name} (HTTP ${result.status}).`, [401, 403].includes(result.status));
+  }
+  // A concurrent acceptance can reject our PATCH yet leave effective access ready.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    missing = await missingRepos();
+    if (!missing.length) return required;
+    if (attempt < 2) await sleep(250 * (attempt + 1));
+  }
+  throw acceptanceError || new RepositoryAccessError(`GitHub access is still missing for ${missing.join(", ")}. Confirm this account has been invited to these repositories, then retry the same install command.`, true);
+}
+
+module.exports = { RepositoryAccessError, requiredRepositories, matchesIdentity, ensureRepositoryAccess };

package/lib/setup.js

@@ -29,6 +29,7 @@ const {
 const { commandExists } = require("./path-lookup");
 
 const https = require("node:https");
+const { RepositoryAccessError, ensureRepositoryAccess } = require("./install-access");
 
 function run(cmd, opts = {}) {
   return execSync(cmd, { stdio: "pipe", encoding: "utf-8", timeout: 60000, ...opts }).trim();
@@ -52,6 +53,7 @@ function ghApi(method, apiPath, token, body) {
         path: apiPath,
         method,
         headers,
+        timeout: 15000,
       },
       (res) => {
         let buf = "";
@@ -66,6 +68,7 @@ function ghApi(method, apiPath, token, body) {
       }
     );
     req.on("error", reject);
+    req.on("timeout", () => req.destroy(new Error("GitHub request timed out. Retry the same install command.")));
     if (payload) req.write(payload);
     req.end();
   });
@@ -416,9 +419,15 @@ async function install(data, ui, targetDir, opts = {}) {
   // steps are skipped. Falls through to the normal flow if anything is off.
   const alreadyInstalled = isFullySetUp(egregoreDir, memoryDir, fork_url, memory_url);
 
-  // Accept pending repo collaboration invitations (joiners get invited as collaborators)
-  if (github_token) configureGitCredentials(github_token);
-  await acceptPendingInvitations(github_token, github_org, ui);
+  // Verify before credential writes or cloning. The same verified credential
+  // handles Git operations, so an unrelated SSH account cannot take over.
+  if (opts.verifyAccess) {
+    const required = await ensureRepositoryAccess(data, ui, { request: ghApi });
+    for (const name of required) verifyGitAccess(`https://github.com/${name}.git`, github_token);
+  } else {
+    if (github_token) configureGitCredentials(github_token);
+    await acceptPendingInvitations(github_token, github_org, ui);
+  }
 
   if (alreadyInstalled) {
     ui.success(`Already installed at ${ui.bold(egregoreDir)} — refreshing setup`);
@@ -426,7 +435,9 @@ async function install(data, ui, targetDir, opts = {}) {
   } else {
     // 1. Clone fork (SSH first, HTTPS fallback — no token embedding)
     ui.step(1, totalSteps, "Cloning egregore...");
-    if (fs.existsSync(egregoreDir)) {
+    if (opts.verifyAccess) {
+      syncAuthenticatedRepository(fork_url, egregoreDir, github_token);
+    } else if (fs.existsSync(egregoreDir)) {
       ui.warn("egregore/ already exists — pulling latest");
       run("git pull", { cwd: egregoreDir });
     } else {
@@ -449,7 +460,9 @@ async function install(data, ui, targetDir, opts = {}) {
 
     // 2. Clone memory
     ui.step(2, totalSteps, "Cloning shared memory...");
-    if (fs.existsSync(memoryDir)) {
+    if (opts.verifyAccess) {
+      syncAuthenticatedRepository(memory_url, memoryDir, github_token);
+    } else if (fs.existsSync(memoryDir)) {
       ui.warn(`${memoryDirName}/ already exists — pulling latest`);
       run("git pull", { cwd: memoryDir });
     } else {
@@ -576,7 +589,9 @@ async function install(data, ui, targetDir, opts = {}) {
       continue;
     }
     try {
-      if (fs.existsSync(repoDir)) {
+      if (opts.verifyAccess) {
+        syncAuthenticatedRepository(`https://github.com/${github_org}/${repoName}.git`, repoDir, github_token);
+      } else if (fs.existsSync(repoDir)) {
         ui.warn(`${repoName}/ already exists — pulling latest`);
         run("git pull", { cwd: repoDir });
       } else {
@@ -588,7 +603,8 @@ async function install(data, ui, targetDir, opts = {}) {
       try { run("git config credential.helper store", { cwd: repoDir }); } catch {}
       clonedRepos.push(repoName);
       ui.success(`Cloned ${repoName}`);
-    } catch {
+    } catch (err) {
+      if (opts.verifyAccess) throw err;
       failedRepos.push(repoName);
       ui.warn(`Could not clone ${repoName} — you may not have access yet. Ask the org admin to grant access.`);
     }
@@ -823,6 +839,61 @@ function gitCloneEnv(base = process.env) {
   };
 }
 
+function authenticatedGitEnv(token, base = process.env) {
+  if (!token || /[\r\n]/.test(token)) throw new Error("A valid GitHub credential is required.");
+  const env = gitCloneEnv(base);
+  const count = Number(env.GIT_CONFIG_COUNT || 0);
+  if (!Number.isSafeInteger(count) || count < 0) throw new Error("Invalid Git configuration environment.");
+  const settings = [
+    ["credential.helper", ""],
+    ["http.https://github.com/.extraheader", ""],
+    ["http.https://github.com/.extraheader", `Authorization: Basic ${Buffer.from("x-access-token:" + token).toString("base64")}`],
+  ];
+  settings.forEach(([key, value], index) => {
+    env[`GIT_CONFIG_KEY_${count + index}`] = key;
+    env[`GIT_CONFIG_VALUE_${count + index}`] = value;
+  });
+  env.GIT_CONFIG_COUNT = String(count + settings.length);
+  return env;
+}
+
+function authenticatedGit(args, token, cwd) {
+  try {
+    return execFileSync("git", args, {
+      cwd, env: authenticatedGitEnv(token), timeout: 60000,
+      stdio: "pipe", encoding: "utf-8",
+    }).trim();
+  } catch (err) {
+    const detail = redactToken(err.stderr || err.message, token)
+      .split(Buffer.from("x-access-token:" + token).toString("base64")).join("***");
+    throw new Error(`Git ${args[0]} failed: ${detail.trim()}`);
+  }
+}
+
+function verifyGitAccess(url, token) {
+  try {
+    authenticatedGit(["ls-remote", url], token);
+  } catch (err) {
+    throw new RepositoryAccessError(
+      `Cannot read ${url} with the verified GitHub account. ${err.message}`,
+      /authentication|could not read Username|not found|403|access denied/i.test(err.message),
+    );
+  }
+}
+
+function syncAuthenticatedRepository(url, dir, token) {
+  if (fs.existsSync(dir)) {
+    const origin = authenticatedGit(["remote", "get-url", "origin"], token, dir);
+    if (normalizeGitUrl(origin) !== normalizeGitUrl(url)) {
+      throw new Error(`Refusing to update ${dir}: its Git origin differs from this setup.`);
+    }
+    // A retry reuses completed clones. Do not merge a remote default branch
+    // into a user's working branch or disturb changes made after the failure.
+  } else {
+    authenticatedGit(["clone", url, dir], token);
+  }
+}
+
 /**
  * Clone a repo, trying SSH first then HTTPS (no token embedded).
  * The repo:invite-scoped OAuth token can't clone — we rely on the
@@ -1021,7 +1092,7 @@ function codexSupportMessage(egregoreDir) {
     "  .codex/hooks.json",
     "  .codex/hooks/",
     "",
-    "Run npx -y create-egregore@latest to install the packaged Codex runtime, then rerun egregore.",
+    "Restore this instance using its installed runtime version, then rerun egregore.",
     "Egregore workflows appear as slash commands. In Codex, invoke them with the matching $skill token or ask in natural language.",
   ].join("\n");
 }
@@ -1035,7 +1106,7 @@ function piSupportMessage(egregoreDir) {
     "Pi meta-harness support is missing from this Egregore checkout.",
     `  path: ${egregoreDir}`,
     "",
-    "Run npx -y create-egregore@latest to install the packaged Pi runtime, then rerun egregore.",
+    "Restore this instance using its installed runtime version, then rerun egregore.",
     "Pi loads Egregore through project-local .pi resources and the shared portable skill corpus.",
   ].join("\n");
 }
@@ -1045,7 +1116,7 @@ function primeSupportMessage(egregoreDir) {
     "Prime Agent runtime support is missing from this Egregore checkout.",
     `  path: ${egregoreDir}`,
     "",
-    "Run npx -y create-egregore@latest to install the packaged Prime Agent runtime, then rerun egregore.",
+    "Restore this instance using its installed runtime version, then rerun egregore.",
     "Prime Agent loads Egregore through project-local .prime/agent resources and the shared portable skill corpus.",
   ].join("\n");
 }
@@ -1171,8 +1242,6 @@ async function launchOrInstruct(egregoreDir, alias, ui, ctx = {}) {
   console.log("");
 
   if (runtime === "codex") {
-    const codexRuntime = installCodexRuntime(egregoreDir);
-    reportCodexRuntimeSummary(codexRuntime, ui);
     if (!hasCodexCoreSupport(egregoreDir)) {
       ui.warn(codexSupportMessage(egregoreDir));
       ui.info(`Run ${ui.bold(aliasName)} after updating the checkout.`);
@@ -1188,8 +1257,6 @@ async function launchOrInstruct(egregoreDir, alias, ui, ctx = {}) {
       return;
     }
   } else if (runtime === "pi") {
-    const piRuntime = installPiRuntime(egregoreDir);
-    reportPiRuntimeSummary(piRuntime, ui);
     if (!hasPiRuntimeSupport(egregoreDir)) {
       ui.warn(piSupportMessage(egregoreDir));
       ui.info(`Run ${ui.bold(aliasName)} after updating the checkout.`);
@@ -1197,8 +1264,6 @@ async function launchOrInstruct(egregoreDir, alias, ui, ctx = {}) {
       return;
     }
   } else if (runtime === "prime") {
-    const primeRuntime = installPrimeRuntime(egregoreDir);
-    reportPrimeRuntimeSummary(primeRuntime, ui);
     if (!hasPrimeRuntimeSupport(egregoreDir)) {
       ui.warn(primeSupportMessage(egregoreDir));
       ui.info(`Run ${ui.bold(aliasName)} after updating the checkout.`);
@@ -1309,11 +1374,15 @@ function appendLocalBinToRc(ui) {
  */
 async function installLauncherBinary(egregoreDir, ui) {
   const template = readLauncherTemplate();
-  const candidates = [
-    { dir: "/usr/local/bin", location: "system" },
-    { dir: "/opt/homebrew/bin", location: "system" },
-    { dir: path.join(os.homedir(), ".local", "bin"), location: "user" },
-  ];
+  // An explicit destination must never fall through to machine-wide paths.
+  const configuredBinDir = process.env.EGREGORE_LAUNCHER_BIN_DIR;
+  const candidates = configuredBinDir
+    ? [{ dir: path.resolve(configuredBinDir), location: "user" }]
+    : [
+        { dir: "/usr/local/bin", location: "system" },
+        { dir: "/opt/homebrew/bin", location: "system" },
+        { dir: path.join(os.homedir(), ".local", "bin"), location: "user" },
+      ];
 
   let chosen = null;
   for (const c of candidates) {
@@ -1546,6 +1615,9 @@ module.exports = {
   redactToken,
   configureGitCredentials,
   gitCloneEnv,
+  authenticatedGitEnv,
+  verifyGitAccess,
+  syncAuthenticatedRepository,
   assistantInstallCommand,
   initMemoryDirs,
   ensureDevelop,