create-egregore 0.21.0-runtime-mvp.21 → 0.21.0-runtime-mvp.23

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.21.0-runtime-mvp.21
+// egregore-launcher-version: 0.21.0-runtime-mvp.23
 //
 // egregore — launch and browse Egregore instances from your terminal.
 // Installed by create-egregore. Reads ~/.egregore/instances.json.
@@ -35,7 +35,7 @@ const crypto = require("node:crypto");
 const { spawnSync, spawn } = require("node:child_process");
 const readline = require("node:readline");
 
-const VERSION = "0.21.0-runtime-mvp.21";
+const VERSION = "0.21.0-runtime-mvp.23";
 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");
@@ -285,7 +285,23 @@ function readRegistry() {
       if (key.includes("/.claude/worktrees/")) continue;
       if (seen.has(key)) continue;
       seen.add(key);
-      result.push(e);
+      // The checkout config is the canonical identity for a path. Older
+      // installers could overwrite registry labels when two organizations
+      // used the same repository/folder name, producing hybrid rows such as
+      // another org's slug beside the Curve Labs checkout.
+      let canonical = e;
+      try {
+        const config = JSON.parse(
+          fs.readFileSync(path.join(key, "egregore.json"), "utf-8")
+        );
+        canonical = {
+          ...e,
+          slug: config.slug || e.slug,
+          name: config.org_name || e.name,
+        };
+        if (config.org_id) canonical.org_id = config.org_id;
+      } catch {}
+      result.push(canonical);
     }
     return result;
   } catch {
@@ -2499,20 +2515,33 @@ function formatTelemetryLines(status) {
 function upgradeStatus(inst, { fetch = false } = {}) {
   const args = ["status"]; if (fetch) args.push("--fetch");
   const r = runUpgrade(inst, args);
-  if (!r || r.status !== 0 || !r.stdout) return null;
-  try { return JSON.parse(r.stdout); } catch { return null; }
+  if (!r || r.status !== 0 || !r.stdout) {
+    const detail = String((r && (r.stderr || r.stdout)) || "Runtime status probe failed")
+      .trim().split("\n")[0];
+    return { status: "unavailable", failure: { message: detail } };
+  }
+  try { return JSON.parse(r.stdout); } catch {
+    return { status: "unavailable", failure: { message: "Runtime status returned an unreadable response" } };
+  }
 }
 
 function upgradeStatusAsync(inst, cb) {
   const bridge = resolveUpgradeBridge(inst);
-  if (!bridge) return cb(null);
-  let buf = "";
+  if (!bridge) return cb({ status: "unavailable", failure: { message: "No Runtime update engine is installed" } });
+  let buf = ""; let err = "";
   try {
-    const child = spawn("bash", [bridge.script, "status"], { cwd: inst.path, stdio: ["ignore", "pipe", "ignore"], env: { ...process.env, ...bridge.env } });
+    const child = spawn("bash", [bridge.script, "status"], { cwd: inst.path, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...bridge.env } });
     child.stdout.on("data", (d) => { buf += d; });
-    child.on("close", () => { try { cb(JSON.parse(buf)); } catch { cb(null); } });
-    child.on("error", () => cb(null));
-  } catch { cb(null); }
+    child.stderr.on("data", (d) => { err += d; });
+    child.on("close", (code) => {
+      if (code === 0) {
+        try { cb(JSON.parse(buf)); return; } catch {}
+      }
+      const detail = String(err || buf || "Runtime status probe failed").trim().split("\n")[0];
+      cb({ status: "unavailable", failure: { message: detail } });
+    });
+    child.on("error", (error) => cb({ status: "unavailable", failure: { message: error.message } }));
+  } catch (error) { cb({ status: "unavailable", failure: { message: error.message } }); }
 }
 
 // Local retrieval health for the settings surface. Package-update state,
@@ -2632,6 +2661,7 @@ const UPGRADE_STATUS_LABEL = {
   active: "active",
   cancelled: "cancelled",
   "rolled-back": "rolled back",
+  unavailable: "unavailable",
 };
 
 // Settings-row truth for the Runtime update line. The row must say outright
@@ -2645,6 +2675,7 @@ function runtimeUpdateRowValue(st, candidate) {
     if (candidate && candidate !== v) return `${v} active ${YELLOW}· update available ${candidate}${RESET}`;
     return `${GREEN}${v} active${RESET}${candidate ? `${DIM} · up to date${RESET}` : ""}`;
   }
+  if (st.status === "unavailable") return `${YELLOW}update unavailable${RESET}`;
   if (st.status === "ready-to-activate") return `${GREEN}${upgradeSummary(st)}${RESET}`;
   if (st.status === "failed" || st.status === "interrupted") return `${YELLOW}${upgradeSummary(st)}${RESET}`;
   if (st.status === "preparing" || st.status === "pending") return `${DIM}${upgradeSummary(st)}${RESET}`;
@@ -2685,7 +2716,7 @@ function formatUpgradeLines(inst, st, { candidate = "", retrieval = null } = {})
   if (d.candidate_digest) lines.push(`Package digest: sha256 ${String(d.candidate_digest).slice(0, 16)}…`);
   // A recorded failure only needs attention while the transaction is stuck
   // on it; once a later prepare succeeds the line would contradict "ready".
-  if (d.failure && d.failure.message && (d.status === "failed" || d.status === "interrupted")) {
+  if (d.failure && d.failure.message && (["failed", "interrupted", "unavailable"].includes(d.status))) {
     lines.push(`Attention: ${d.failure.message}`);
   }
   if (d.rollback_version && d.status !== "none") lines.push(`Rollback target: ${d.rollback_version}`);
@@ -2760,6 +2791,7 @@ async function cmdSettingsRuntime(inst, args) {
     const st = upgradeStatus(inst, { fetch: fetchFlag });
     if (st === null) { process.stderr.write("Runtime update state is unavailable for this egregore.\n"); process.exitCode = 1; return; }
     emit(st);
+    if (st.status === "unavailable") process.exitCode = 1;
     if (action === "review" || (st.status !== "active" && st.status !== "none")) {
       process.stdout.write("\nWhat stays:\n");
       for (const s of UPGRADE_STAYS) process.stdout.write(`  · ${s}\n`);

package/lib/setup.js

@@ -219,17 +219,37 @@ function slugifyName(name) {
  *
  * Most Egregore forks are named "egregore", so deriving the target only from
  * the fork basename makes different organizations collide in the same parent
- * directory. If that default path is already a Git checkout with another
- * origin, leave it untouched and use egregore-{org-slug}. The fallback must
- * also be absent or point at the requested fork; otherwise stop rather than
- * guessing at another path.
+ * directory. If that default path already belongs to another configured org
+ * or Git origin, leave it untouched and use egregore-{org-slug}. The fallback
+ * must also be absent or belong to the requested org and fork; otherwise stop
+ * rather than guessing at another path.
  */
-function resolveEgregoreInstallDir(base, forkUrl, slug) {
+function configuredIdentityConflicts(dir, slug, orgId = "") {
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(path.join(dir, "egregore.json"), "utf-8"));
+  } catch {
+    return false;
+  }
+  const existingSlug = slugifyName(config.slug || "");
+  const requestedSlug = slugifyName(slug || "");
+  if (existingSlug && requestedSlug && existingSlug !== requestedSlug) return true;
+
+  const stable = (value) => typeof value === "string" && value && !value.startsWith("legacy-org:");
+  return stable(config.org_id) && stable(orgId) && config.org_id !== orgId;
+}
+
+function installTargetMatches(dir, forkUrl, slug, orgId = "") {
+  if (configuredIdentityConflicts(dir, slug, orgId)) return false;
+  const gitPath = path.join(dir, ".git");
+  return !fs.existsSync(gitPath) || gitRemoteMatches(dir, forkUrl);
+}
+
+function resolveEgregoreInstallDir(base, forkUrl, slug, orgId = "") {
   const forkDirName = forkUrl.split("/").pop().replace(/\.git$/, "");
   const requestedDir = path.join(base, forkDirName);
-  const requestedGitPath = path.join(requestedDir, ".git");
 
-  if (!fs.existsSync(requestedGitPath) || gitRemoteMatches(requestedDir, forkUrl)) {
+  if (installTargetMatches(requestedDir, forkUrl, slug, orgId)) {
     return { egregoreDir: requestedDir, redirectedFrom: null };
   }
 
@@ -237,15 +257,14 @@ function resolveEgregoreInstallDir(base, forkUrl, slug) {
   const fallbackDir = path.join(base, `egregore-${safeSlug}`);
   if (path.resolve(fallbackDir) === path.resolve(requestedDir)) {
     throw new Error(
-      `Refusing to install into ${requestedDir}: its Git origin does not match ${forkUrl}`
+      `Refusing to install into ${requestedDir}: it belongs to another Egregore or Git origin`
     );
   }
 
   if (fs.existsSync(fallbackDir)) {
-    const fallbackGitPath = path.join(fallbackDir, ".git");
-    if (!fs.existsSync(fallbackGitPath) || !gitRemoteMatches(fallbackDir, forkUrl)) {
+    if (!installTargetMatches(fallbackDir, forkUrl, slug, orgId)) {
       throw new Error(
-        `Refusing to install into ${fallbackDir}: the fallback path already belongs to another checkout or directory`
+        `Refusing to install into ${fallbackDir}: the fallback path already belongs to another Egregore, checkout, or directory`
       );
     }
   }
@@ -444,11 +463,16 @@ async function install(data, ui, targetDir, opts = {}) {
   const {
     egregoreDir,
     redirectedFrom,
-  } = resolveEgregoreInstallDir(base, fork_url, slug || github_org || org_name);
+  } = resolveEgregoreInstallDir(
+    base,
+    fork_url,
+    slug || github_org || org_name,
+    data.org_id || "",
+  );
   if (redirectedFrom) {
     forkDirName = path.basename(egregoreDir);
     ui.warn(
-      `${redirectedFrom} belongs to another Git origin — leaving it untouched and installing at ${egregoreDir}`
+      `${redirectedFrom} belongs to another Egregore or Git origin — leaving it untouched and installing at ${egregoreDir}`
     );
   }
   const memoryDirName = memory_url
@@ -1176,10 +1200,23 @@ function registerInstance(slug, name, egregoreDir, runtime) {
     }
   }
 
+  // The checkout config is canonical. A historic same-path install could pass
+  // another organization's label here and splice that label onto this path.
+  let canonicalOrgId = "";
+  try {
+    const config = JSON.parse(
+      fs.readFileSync(path.join(egregoreDir, "egregore.json"), "utf-8")
+    );
+    slug = config.slug || slug;
+    name = config.org_name || name;
+    canonicalOrgId = config.org_id || "";
+  } catch {}
+
   // Dedup by path (not slug) so multiple instances from the same org can coexist
   const idx = instances.findIndex((i) => i.path === egregoreDir);
   const previous = idx >= 0 ? instances[idx] : {};
   const entry = { ...previous, slug, name, path: egregoreDir };
+  if (canonicalOrgId) entry.org_id = canonicalOrgId;
   if (runtime) {
     entry.runtime = normalizeRuntime(runtime);
   } else if (!entry.runtime && entry.preferred_runtime) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-egregore",
-  "version": "0.21.0-runtime-mvp.21",
+  "version": "0.21.0-runtime-mvp.23",
   "description": "Set up Egregore for your team in one command — installs the egregore launcher and your choice of Claude Code, Codex, or Pi.",
   "license": "MIT",
   "bin": {

package/runtime/claude/bin/runtime-identity.sh

@@ -6,7 +6,12 @@ set -euo pipefail
 # legacy Local instances create opaque local IDs once. Network failure remains
 # non-fatal to startup and is retried next session.
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+RUNTIME_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# A launcher-carried bridge runs outside the selected instance. Keep code
+# rooted in the packaged Runtime while resolving and persisting identity in
+# exactly the instance the launcher selected.
+ROOT="${EGREGORE_INSTANCE_ROOT:-$RUNTIME_ROOT}"
+ROOT="$(cd "$ROOT" && pwd)"
 CONFIG="$ROOT/egregore.json"
 STATE="$ROOT/.egregore-state.json"
 
@@ -34,21 +39,52 @@ case "${1:-ensure}" in
     resolved && exit 0
     mode="$(jq -r 'if (.mode // "local") == "connected" or (.api_url // "") != "" then "connected" else "local" end' "$CONFIG" 2>/dev/null || echo local)"
     if [ "$mode" = "local" ]; then
-      EGREGORE_ROOT="$ROOT" python3 -m egregore_runtime.identity_cli initialize-local >/dev/null
+      EGREGORE_ROOT="$ROOT" \
+        PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+        python3 -m egregore_runtime.identity_cli initialize-local >/dev/null
     else
       api_url="$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)"
-      api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
-      [ -n "$api_url" ] && [ -n "$api_key" ] || exit 1
-      # Identity repair is read-only: select the already-existing account and
-      # membership records, then adopt their opaque IDs locally. If migration
-      # 038 has not reached the control plane, the next session retries.
-      control_plane="$(curl -sf "$api_url/api/org/status" \
-        -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
-        2>/dev/null || true)"
-      printf '%s' "$control_plane" | jq -e \
-        '.org_id | type == "string" and length > 0' >/dev/null 2>&1 || exit 1
       slug="$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)"
-      [ -n "$slug" ] || exit 1
+      api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+      [ -n "$api_url" ] && [ -n "$slug" ] || exit 1
+      # Identity repair selects already-existing account and membership
+      # records, then adopts their opaque IDs locally. If a stale credential
+      # belongs to another org, recover only the configured org's existing key
+      # through verified GitHub membership. No control-plane records are made.
+      control_plane=""
+      if [ -n "$api_key" ]; then
+        control_plane="$(curl -sf "$api_url/api/org/status" \
+          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
+          2>/dev/null || true)"
+      fi
+      if ! printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
+        (.org_id | type == "string" and length > 0) and .slug == $slug
+      ' >/dev/null 2>&1; then
+        # A historic path/namespace collision could leave this checkout with
+        # another Egregore's API key. Recover the configured org's existing key
+        # only through the membership-verifying endpoint, install it atomically,
+        # and retry. No credential bytes are printed.
+        github_token="$(grep '^GITHUB_TOKEN=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+        [ -n "$github_token" ] || exit 1
+        encoded_slug="$(printf '%s' "$slug" | jq -sRr @uri)"
+        recovered="$(curl -sf "$api_url/api/org/$encoded_slug/key" \
+          -H "Authorization: Bearer $github_token" --connect-timeout 2 --max-time 12 \
+          2>/dev/null || true)"
+        printf '%s' "$recovered" | jq -e --arg slug "$slug" '
+          (.api_key | type == "string" and length > 0) and .org_slug == $slug
+        ' >/dev/null 2>&1 || exit 1
+        printf '%s' "$recovered" | \
+          EGREGORE_ROOT="$ROOT" \
+          PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+          python3 -m egregore_runtime.identity_cli install-connected-key >/dev/null
+        api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+        control_plane="$(curl -sf "$api_url/api/org/status" \
+          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
+          2>/dev/null || true)"
+        printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
+          (.org_id | type == "string" and length > 0) and .slug == $slug
+        ' >/dev/null 2>&1 || exit 1
+      fi
       roster="$(curl -sf "$api_url/api/org/$slug/members?include_removed=true" \
         -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
         2>/dev/null || true)"
@@ -58,7 +94,9 @@ case "${1:-ensure}" in
         --argjson organization "$control_plane" \
         --argjson roster "$roster" \
         '{organization:$organization,roster:$roster}' | \
-        EGREGORE_ROOT="$ROOT" python3 -m egregore_runtime.identity_cli \
+        EGREGORE_ROOT="$ROOT" \
+          PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+          python3 -m egregore_runtime.identity_cli \
           reconcile-records >/dev/null
     fi
     resolved

package/runtime/claude/bin/runtime-upgrade.sh

@@ -28,13 +28,35 @@ _runtime() {
     python3 -m egregore_runtime.harness_cli "$@"
 }
 
+_ensure_identity() {
+  # Pre-Runtime instances can predate stable organization identity. Resolve it
+  # through the existing verified Local/Connected migration before computing
+  # the instance-scoped upgrade key; never infer identity from path or slug.
+  if jq -e '
+    .org_id | type == "string" and length > 0 and (startswith("legacy-org:") | not)
+  ' "$INSTANCE_ROOT/egregore.json" >/dev/null 2>&1; then
+    return 0
+  fi
+  EGREGORE_INSTANCE_ROOT="$INSTANCE_ROOT" \
+    PYTHONPATH="$SCRIPT_DIR${PYTHONPATH:+:$PYTHONPATH}" \
+    bash "$SCRIPT_DIR/bin/runtime-identity.sh" ensure
+}
+
+_run_upgrade() {
+  _ensure_identity || {
+    echo "Runtime update could not resolve this Egregore's stable identity." >&2
+    return 1
+  }
+  _runtime upgrade "$@"
+}
+
 case "${1:-}" in
-  status)   shift; _runtime upgrade status "$@" ;;
-  init)     shift; _runtime upgrade init "$@" ;;
-  prepare)  shift; _runtime upgrade prepare "$@" ;;
-  activate) shift; _runtime upgrade activate "$@" ;;
-  cancel)   shift; _runtime upgrade cancel "$@" ;;
-  rollback) shift; _runtime upgrade rollback "$@" ;;
+  status)   shift; _run_upgrade status "$@" ;;
+  init)     shift; _run_upgrade init "$@" ;;
+  prepare)  shift; _run_upgrade prepare "$@" ;;
+  activate) shift; _run_upgrade activate "$@" ;;
+  cancel)   shift; _run_upgrade cancel "$@" ;;
+  rollback) shift; _run_upgrade rollback "$@" ;;
   team-sync) shift; _runtime team-sync "$@" ;;
   *)
     echo "usage: bash bin/runtime-upgrade.sh {status|init --candidate <version>|prepare|activate|cancel|rollback|team-sync}" >&2

package/runtime/claude/egregore_runtime/identity_cli.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import os
 import sys
+import tempfile
 from pathlib import Path
 
 from .contracts import Permission
@@ -44,6 +45,55 @@ def _authorize_self(root: Path, permission: Permission, resource: str) -> int:
     return 0
 
 
+def _install_connected_key(root: Path, payload: dict) -> dict[str, str]:
+    """Install a membership-verified key without exposing it in output."""
+
+    config = json.loads((root / "egregore.json").read_text(encoding="utf-8"))
+    expected_slug = str(config.get("slug") or "").strip()
+    returned_slug = str(payload.get("org_slug") or "").strip()
+    api_key = str(payload.get("api_key") or "").strip()
+    if not expected_slug or returned_slug != expected_slug:
+        raise ValueError("recovered credential does not match the configured organization")
+    if not api_key or "\n" in api_key or "\r" in api_key:
+        raise ValueError("recovered credential is missing or malformed")
+
+    env_path = root / ".env"
+    existing = env_path.read_text(encoding="utf-8") if env_path.exists() else ""
+    output: list[str] = []
+    replaced = False
+    for line in existing.splitlines():
+        if line.startswith("EGREGORE_API_KEY="):
+            if not replaced:
+                output.append(f"EGREGORE_API_KEY={api_key}")
+                replaced = True
+            continue
+        output.append(line)
+    if not replaced:
+        output.append(f"EGREGORE_API_KEY={api_key}")
+
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=root,
+            prefix=".env.egregore-key.",
+            delete=False,
+        ) as handle:
+            temporary = Path(handle.name)
+            os.chmod(temporary, 0o600)
+            handle.write("\n".join(output) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, env_path)
+        temporary = None
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+    return {"org_slug": expected_slug}
+
+
 def main() -> int:
     root = Path(os.environ.get("EGREGORE_ROOT") or Path.cwd()).resolve()
     if len(sys.argv) > 1 and sys.argv[1] == "initialize-local":
@@ -77,6 +127,11 @@ def main() -> int:
         result = reconcile_control_plane_identity(root, response)
         print(json.dumps({"status": "reconciled", **result}, sort_keys=True))
         return 0
+    if len(sys.argv) > 1 and sys.argv[1] == "install-connected-key":
+        payload = json.load(sys.stdin)
+        result = _install_connected_key(root, payload)
+        print(json.dumps({"status": "installed", **result}, sort_keys=True))
+        return 0
     payload = json.load(sys.stdin)
     result = reconcile_control_plane_identity(root, payload)
     print(json.dumps({"status": "reconciled", **result}, sort_keys=True))

package/runtime/codex/bin/runtime-identity.sh

@@ -6,7 +6,12 @@ set -euo pipefail
 # legacy Local instances create opaque local IDs once. Network failure remains
 # non-fatal to startup and is retried next session.
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+RUNTIME_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# A launcher-carried bridge runs outside the selected instance. Keep code
+# rooted in the packaged Runtime while resolving and persisting identity in
+# exactly the instance the launcher selected.
+ROOT="${EGREGORE_INSTANCE_ROOT:-$RUNTIME_ROOT}"
+ROOT="$(cd "$ROOT" && pwd)"
 CONFIG="$ROOT/egregore.json"
 STATE="$ROOT/.egregore-state.json"
 
@@ -34,21 +39,52 @@ case "${1:-ensure}" in
     resolved && exit 0
     mode="$(jq -r 'if (.mode // "local") == "connected" or (.api_url // "") != "" then "connected" else "local" end' "$CONFIG" 2>/dev/null || echo local)"
     if [ "$mode" = "local" ]; then
-      EGREGORE_ROOT="$ROOT" python3 -m egregore_runtime.identity_cli initialize-local >/dev/null
+      EGREGORE_ROOT="$ROOT" \
+        PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+        python3 -m egregore_runtime.identity_cli initialize-local >/dev/null
     else
       api_url="$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)"
-      api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
-      [ -n "$api_url" ] && [ -n "$api_key" ] || exit 1
-      # Identity repair is read-only: select the already-existing account and
-      # membership records, then adopt their opaque IDs locally. If migration
-      # 038 has not reached the control plane, the next session retries.
-      control_plane="$(curl -sf "$api_url/api/org/status" \
-        -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
-        2>/dev/null || true)"
-      printf '%s' "$control_plane" | jq -e \
-        '.org_id | type == "string" and length > 0' >/dev/null 2>&1 || exit 1
       slug="$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)"
-      [ -n "$slug" ] || exit 1
+      api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+      [ -n "$api_url" ] && [ -n "$slug" ] || exit 1
+      # Identity repair selects already-existing account and membership
+      # records, then adopts their opaque IDs locally. If a stale credential
+      # belongs to another org, recover only the configured org's existing key
+      # through verified GitHub membership. No control-plane records are made.
+      control_plane=""
+      if [ -n "$api_key" ]; then
+        control_plane="$(curl -sf "$api_url/api/org/status" \
+          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
+          2>/dev/null || true)"
+      fi
+      if ! printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
+        (.org_id | type == "string" and length > 0) and .slug == $slug
+      ' >/dev/null 2>&1; then
+        # A historic path/namespace collision could leave this checkout with
+        # another Egregore's API key. Recover the configured org's existing key
+        # only through the membership-verifying endpoint, install it atomically,
+        # and retry. No credential bytes are printed.
+        github_token="$(grep '^GITHUB_TOKEN=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+        [ -n "$github_token" ] || exit 1
+        encoded_slug="$(printf '%s' "$slug" | jq -sRr @uri)"
+        recovered="$(curl -sf "$api_url/api/org/$encoded_slug/key" \
+          -H "Authorization: Bearer $github_token" --connect-timeout 2 --max-time 12 \
+          2>/dev/null || true)"
+        printf '%s' "$recovered" | jq -e --arg slug "$slug" '
+          (.api_key | type == "string" and length > 0) and .org_slug == $slug
+        ' >/dev/null 2>&1 || exit 1
+        printf '%s' "$recovered" | \
+          EGREGORE_ROOT="$ROOT" \
+          PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+          python3 -m egregore_runtime.identity_cli install-connected-key >/dev/null
+        api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+        control_plane="$(curl -sf "$api_url/api/org/status" \
+          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
+          2>/dev/null || true)"
+        printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
+          (.org_id | type == "string" and length > 0) and .slug == $slug
+        ' >/dev/null 2>&1 || exit 1
+      fi
       roster="$(curl -sf "$api_url/api/org/$slug/members?include_removed=true" \
         -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
         2>/dev/null || true)"
@@ -58,7 +94,9 @@ case "${1:-ensure}" in
         --argjson organization "$control_plane" \
         --argjson roster "$roster" \
         '{organization:$organization,roster:$roster}' | \
-        EGREGORE_ROOT="$ROOT" python3 -m egregore_runtime.identity_cli \
+        EGREGORE_ROOT="$ROOT" \
+          PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+          python3 -m egregore_runtime.identity_cli \
           reconcile-records >/dev/null
     fi
     resolved

package/runtime/codex/bin/runtime-upgrade.sh

@@ -28,13 +28,35 @@ _runtime() {
     python3 -m egregore_runtime.harness_cli "$@"
 }
 
+_ensure_identity() {
+  # Pre-Runtime instances can predate stable organization identity. Resolve it
+  # through the existing verified Local/Connected migration before computing
+  # the instance-scoped upgrade key; never infer identity from path or slug.
+  if jq -e '
+    .org_id | type == "string" and length > 0 and (startswith("legacy-org:") | not)
+  ' "$INSTANCE_ROOT/egregore.json" >/dev/null 2>&1; then
+    return 0
+  fi
+  EGREGORE_INSTANCE_ROOT="$INSTANCE_ROOT" \
+    PYTHONPATH="$SCRIPT_DIR${PYTHONPATH:+:$PYTHONPATH}" \
+    bash "$SCRIPT_DIR/bin/runtime-identity.sh" ensure
+}
+
+_run_upgrade() {
+  _ensure_identity || {
+    echo "Runtime update could not resolve this Egregore's stable identity." >&2
+    return 1
+  }
+  _runtime upgrade "$@"
+}
+
 case "${1:-}" in
-  status)   shift; _runtime upgrade status "$@" ;;
-  init)     shift; _runtime upgrade init "$@" ;;
-  prepare)  shift; _runtime upgrade prepare "$@" ;;
-  activate) shift; _runtime upgrade activate "$@" ;;
-  cancel)   shift; _runtime upgrade cancel "$@" ;;
-  rollback) shift; _runtime upgrade rollback "$@" ;;
+  status)   shift; _run_upgrade status "$@" ;;
+  init)     shift; _run_upgrade init "$@" ;;
+  prepare)  shift; _run_upgrade prepare "$@" ;;
+  activate) shift; _run_upgrade activate "$@" ;;
+  cancel)   shift; _run_upgrade cancel "$@" ;;
+  rollback) shift; _run_upgrade rollback "$@" ;;
   team-sync) shift; _runtime team-sync "$@" ;;
   *)
     echo "usage: bash bin/runtime-upgrade.sh {status|init --candidate <version>|prepare|activate|cancel|rollback|team-sync}" >&2

package/runtime/codex/egregore_runtime/identity_cli.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import os
 import sys
+import tempfile
 from pathlib import Path
 
 from .contracts import Permission
@@ -44,6 +45,55 @@ def _authorize_self(root: Path, permission: Permission, resource: str) -> int:
     return 0
 
 
+def _install_connected_key(root: Path, payload: dict) -> dict[str, str]:
+    """Install a membership-verified key without exposing it in output."""
+
+    config = json.loads((root / "egregore.json").read_text(encoding="utf-8"))
+    expected_slug = str(config.get("slug") or "").strip()
+    returned_slug = str(payload.get("org_slug") or "").strip()
+    api_key = str(payload.get("api_key") or "").strip()
+    if not expected_slug or returned_slug != expected_slug:
+        raise ValueError("recovered credential does not match the configured organization")
+    if not api_key or "\n" in api_key or "\r" in api_key:
+        raise ValueError("recovered credential is missing or malformed")
+
+    env_path = root / ".env"
+    existing = env_path.read_text(encoding="utf-8") if env_path.exists() else ""
+    output: list[str] = []
+    replaced = False
+    for line in existing.splitlines():
+        if line.startswith("EGREGORE_API_KEY="):
+            if not replaced:
+                output.append(f"EGREGORE_API_KEY={api_key}")
+                replaced = True
+            continue
+        output.append(line)
+    if not replaced:
+        output.append(f"EGREGORE_API_KEY={api_key}")
+
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=root,
+            prefix=".env.egregore-key.",
+            delete=False,
+        ) as handle:
+            temporary = Path(handle.name)
+            os.chmod(temporary, 0o600)
+            handle.write("\n".join(output) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, env_path)
+        temporary = None
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+    return {"org_slug": expected_slug}
+
+
 def main() -> int:
     root = Path(os.environ.get("EGREGORE_ROOT") or Path.cwd()).resolve()
     if len(sys.argv) > 1 and sys.argv[1] == "initialize-local":
@@ -77,6 +127,11 @@ def main() -> int:
         result = reconcile_control_plane_identity(root, response)
         print(json.dumps({"status": "reconciled", **result}, sort_keys=True))
         return 0
+    if len(sys.argv) > 1 and sys.argv[1] == "install-connected-key":
+        payload = json.load(sys.stdin)
+        result = _install_connected_key(root, payload)
+        print(json.dumps({"status": "installed", **result}, sort_keys=True))
+        return 0
     payload = json.load(sys.stdin)
     result = reconcile_control_plane_identity(root, payload)
     print(json.dumps({"status": "reconciled", **result}, sort_keys=True))

package/runtime/pi/bin/runtime-identity.sh

@@ -6,7 +6,12 @@ set -euo pipefail
 # legacy Local instances create opaque local IDs once. Network failure remains
 # non-fatal to startup and is retried next session.
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+RUNTIME_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# A launcher-carried bridge runs outside the selected instance. Keep code
+# rooted in the packaged Runtime while resolving and persisting identity in
+# exactly the instance the launcher selected.
+ROOT="${EGREGORE_INSTANCE_ROOT:-$RUNTIME_ROOT}"
+ROOT="$(cd "$ROOT" && pwd)"
 CONFIG="$ROOT/egregore.json"
 STATE="$ROOT/.egregore-state.json"
 
@@ -34,21 +39,52 @@ case "${1:-ensure}" in
     resolved && exit 0
     mode="$(jq -r 'if (.mode // "local") == "connected" or (.api_url // "") != "" then "connected" else "local" end' "$CONFIG" 2>/dev/null || echo local)"
     if [ "$mode" = "local" ]; then
-      EGREGORE_ROOT="$ROOT" python3 -m egregore_runtime.identity_cli initialize-local >/dev/null
+      EGREGORE_ROOT="$ROOT" \
+        PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+        python3 -m egregore_runtime.identity_cli initialize-local >/dev/null
     else
       api_url="$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)"
-      api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
-      [ -n "$api_url" ] && [ -n "$api_key" ] || exit 1
-      # Identity repair is read-only: select the already-existing account and
-      # membership records, then adopt their opaque IDs locally. If migration
-      # 038 has not reached the control plane, the next session retries.
-      control_plane="$(curl -sf "$api_url/api/org/status" \
-        -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
-        2>/dev/null || true)"
-      printf '%s' "$control_plane" | jq -e \
-        '.org_id | type == "string" and length > 0' >/dev/null 2>&1 || exit 1
       slug="$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)"
-      [ -n "$slug" ] || exit 1
+      api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+      [ -n "$api_url" ] && [ -n "$slug" ] || exit 1
+      # Identity repair selects already-existing account and membership
+      # records, then adopts their opaque IDs locally. If a stale credential
+      # belongs to another org, recover only the configured org's existing key
+      # through verified GitHub membership. No control-plane records are made.
+      control_plane=""
+      if [ -n "$api_key" ]; then
+        control_plane="$(curl -sf "$api_url/api/org/status" \
+          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
+          2>/dev/null || true)"
+      fi
+      if ! printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
+        (.org_id | type == "string" and length > 0) and .slug == $slug
+      ' >/dev/null 2>&1; then
+        # A historic path/namespace collision could leave this checkout with
+        # another Egregore's API key. Recover the configured org's existing key
+        # only through the membership-verifying endpoint, install it atomically,
+        # and retry. No credential bytes are printed.
+        github_token="$(grep '^GITHUB_TOKEN=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+        [ -n "$github_token" ] || exit 1
+        encoded_slug="$(printf '%s' "$slug" | jq -sRr @uri)"
+        recovered="$(curl -sf "$api_url/api/org/$encoded_slug/key" \
+          -H "Authorization: Bearer $github_token" --connect-timeout 2 --max-time 12 \
+          2>/dev/null || true)"
+        printf '%s' "$recovered" | jq -e --arg slug "$slug" '
+          (.api_key | type == "string" and length > 0) and .org_slug == $slug
+        ' >/dev/null 2>&1 || exit 1
+        printf '%s' "$recovered" | \
+          EGREGORE_ROOT="$ROOT" \
+          PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+          python3 -m egregore_runtime.identity_cli install-connected-key >/dev/null
+        api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+        control_plane="$(curl -sf "$api_url/api/org/status" \
+          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
+          2>/dev/null || true)"
+        printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
+          (.org_id | type == "string" and length > 0) and .slug == $slug
+        ' >/dev/null 2>&1 || exit 1
+      fi
       roster="$(curl -sf "$api_url/api/org/$slug/members?include_removed=true" \
         -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
         2>/dev/null || true)"
@@ -58,7 +94,9 @@ case "${1:-ensure}" in
         --argjson organization "$control_plane" \
         --argjson roster "$roster" \
         '{organization:$organization,roster:$roster}' | \
-        EGREGORE_ROOT="$ROOT" python3 -m egregore_runtime.identity_cli \
+        EGREGORE_ROOT="$ROOT" \
+          PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+          python3 -m egregore_runtime.identity_cli \
           reconcile-records >/dev/null
     fi
     resolved

package/runtime/pi/bin/runtime-upgrade.sh

@@ -28,13 +28,35 @@ _runtime() {
     python3 -m egregore_runtime.harness_cli "$@"
 }
 
+_ensure_identity() {
+  # Pre-Runtime instances can predate stable organization identity. Resolve it
+  # through the existing verified Local/Connected migration before computing
+  # the instance-scoped upgrade key; never infer identity from path or slug.
+  if jq -e '
+    .org_id | type == "string" and length > 0 and (startswith("legacy-org:") | not)
+  ' "$INSTANCE_ROOT/egregore.json" >/dev/null 2>&1; then
+    return 0
+  fi
+  EGREGORE_INSTANCE_ROOT="$INSTANCE_ROOT" \
+    PYTHONPATH="$SCRIPT_DIR${PYTHONPATH:+:$PYTHONPATH}" \
+    bash "$SCRIPT_DIR/bin/runtime-identity.sh" ensure
+}
+
+_run_upgrade() {
+  _ensure_identity || {
+    echo "Runtime update could not resolve this Egregore's stable identity." >&2
+    return 1
+  }
+  _runtime upgrade "$@"
+}
+
 case "${1:-}" in
-  status)   shift; _runtime upgrade status "$@" ;;
-  init)     shift; _runtime upgrade init "$@" ;;
-  prepare)  shift; _runtime upgrade prepare "$@" ;;
-  activate) shift; _runtime upgrade activate "$@" ;;
-  cancel)   shift; _runtime upgrade cancel "$@" ;;
-  rollback) shift; _runtime upgrade rollback "$@" ;;
+  status)   shift; _run_upgrade status "$@" ;;
+  init)     shift; _run_upgrade init "$@" ;;
+  prepare)  shift; _run_upgrade prepare "$@" ;;
+  activate) shift; _run_upgrade activate "$@" ;;
+  cancel)   shift; _run_upgrade cancel "$@" ;;
+  rollback) shift; _run_upgrade rollback "$@" ;;
   team-sync) shift; _runtime team-sync "$@" ;;
   *)
     echo "usage: bash bin/runtime-upgrade.sh {status|init --candidate <version>|prepare|activate|cancel|rollback|team-sync}" >&2

package/runtime/pi/egregore_runtime/identity_cli.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import os
 import sys
+import tempfile
 from pathlib import Path
 
 from .contracts import Permission
@@ -44,6 +45,55 @@ def _authorize_self(root: Path, permission: Permission, resource: str) -> int:
     return 0
 
 
+def _install_connected_key(root: Path, payload: dict) -> dict[str, str]:
+    """Install a membership-verified key without exposing it in output."""
+
+    config = json.loads((root / "egregore.json").read_text(encoding="utf-8"))
+    expected_slug = str(config.get("slug") or "").strip()
+    returned_slug = str(payload.get("org_slug") or "").strip()
+    api_key = str(payload.get("api_key") or "").strip()
+    if not expected_slug or returned_slug != expected_slug:
+        raise ValueError("recovered credential does not match the configured organization")
+    if not api_key or "\n" in api_key or "\r" in api_key:
+        raise ValueError("recovered credential is missing or malformed")
+
+    env_path = root / ".env"
+    existing = env_path.read_text(encoding="utf-8") if env_path.exists() else ""
+    output: list[str] = []
+    replaced = False
+    for line in existing.splitlines():
+        if line.startswith("EGREGORE_API_KEY="):
+            if not replaced:
+                output.append(f"EGREGORE_API_KEY={api_key}")
+                replaced = True
+            continue
+        output.append(line)
+    if not replaced:
+        output.append(f"EGREGORE_API_KEY={api_key}")
+
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=root,
+            prefix=".env.egregore-key.",
+            delete=False,
+        ) as handle:
+            temporary = Path(handle.name)
+            os.chmod(temporary, 0o600)
+            handle.write("\n".join(output) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, env_path)
+        temporary = None
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+    return {"org_slug": expected_slug}
+
+
 def main() -> int:
     root = Path(os.environ.get("EGREGORE_ROOT") or Path.cwd()).resolve()
     if len(sys.argv) > 1 and sys.argv[1] == "initialize-local":
@@ -77,6 +127,11 @@ def main() -> int:
         result = reconcile_control_plane_identity(root, response)
         print(json.dumps({"status": "reconciled", **result}, sort_keys=True))
         return 0
+    if len(sys.argv) > 1 and sys.argv[1] == "install-connected-key":
+        payload = json.load(sys.stdin)
+        result = _install_connected_key(root, payload)
+        print(json.dumps({"status": "installed", **result}, sort_keys=True))
+        return 0
     payload = json.load(sys.stdin)
     result = reconcile_control_plane_identity(root, payload)
     print(json.dumps({"status": "reconciled", **result}, sort_keys=True))

package/runtime/prime/bin/runtime-identity.sh

@@ -6,7 +6,12 @@ set -euo pipefail
 # legacy Local instances create opaque local IDs once. Network failure remains
 # non-fatal to startup and is retried next session.
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+RUNTIME_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# A launcher-carried bridge runs outside the selected instance. Keep code
+# rooted in the packaged Runtime while resolving and persisting identity in
+# exactly the instance the launcher selected.
+ROOT="${EGREGORE_INSTANCE_ROOT:-$RUNTIME_ROOT}"
+ROOT="$(cd "$ROOT" && pwd)"
 CONFIG="$ROOT/egregore.json"
 STATE="$ROOT/.egregore-state.json"
 
@@ -34,21 +39,52 @@ case "${1:-ensure}" in
     resolved && exit 0
     mode="$(jq -r 'if (.mode // "local") == "connected" or (.api_url // "") != "" then "connected" else "local" end' "$CONFIG" 2>/dev/null || echo local)"
     if [ "$mode" = "local" ]; then
-      EGREGORE_ROOT="$ROOT" python3 -m egregore_runtime.identity_cli initialize-local >/dev/null
+      EGREGORE_ROOT="$ROOT" \
+        PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+        python3 -m egregore_runtime.identity_cli initialize-local >/dev/null
     else
       api_url="$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)"
-      api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
-      [ -n "$api_url" ] && [ -n "$api_key" ] || exit 1
-      # Identity repair is read-only: select the already-existing account and
-      # membership records, then adopt their opaque IDs locally. If migration
-      # 038 has not reached the control plane, the next session retries.
-      control_plane="$(curl -sf "$api_url/api/org/status" \
-        -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
-        2>/dev/null || true)"
-      printf '%s' "$control_plane" | jq -e \
-        '.org_id | type == "string" and length > 0' >/dev/null 2>&1 || exit 1
       slug="$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)"
-      [ -n "$slug" ] || exit 1
+      api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+      [ -n "$api_url" ] && [ -n "$slug" ] || exit 1
+      # Identity repair selects already-existing account and membership
+      # records, then adopts their opaque IDs locally. If a stale credential
+      # belongs to another org, recover only the configured org's existing key
+      # through verified GitHub membership. No control-plane records are made.
+      control_plane=""
+      if [ -n "$api_key" ]; then
+        control_plane="$(curl -sf "$api_url/api/org/status" \
+          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
+          2>/dev/null || true)"
+      fi
+      if ! printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
+        (.org_id | type == "string" and length > 0) and .slug == $slug
+      ' >/dev/null 2>&1; then
+        # A historic path/namespace collision could leave this checkout with
+        # another Egregore's API key. Recover the configured org's existing key
+        # only through the membership-verifying endpoint, install it atomically,
+        # and retry. No credential bytes are printed.
+        github_token="$(grep '^GITHUB_TOKEN=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+        [ -n "$github_token" ] || exit 1
+        encoded_slug="$(printf '%s' "$slug" | jq -sRr @uri)"
+        recovered="$(curl -sf "$api_url/api/org/$encoded_slug/key" \
+          -H "Authorization: Bearer $github_token" --connect-timeout 2 --max-time 12 \
+          2>/dev/null || true)"
+        printf '%s' "$recovered" | jq -e --arg slug "$slug" '
+          (.api_key | type == "string" and length > 0) and .org_slug == $slug
+        ' >/dev/null 2>&1 || exit 1
+        printf '%s' "$recovered" | \
+          EGREGORE_ROOT="$ROOT" \
+          PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+          python3 -m egregore_runtime.identity_cli install-connected-key >/dev/null
+        api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
+        control_plane="$(curl -sf "$api_url/api/org/status" \
+          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
+          2>/dev/null || true)"
+        printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
+          (.org_id | type == "string" and length > 0) and .slug == $slug
+        ' >/dev/null 2>&1 || exit 1
+      fi
       roster="$(curl -sf "$api_url/api/org/$slug/members?include_removed=true" \
         -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
         2>/dev/null || true)"
@@ -58,7 +94,9 @@ case "${1:-ensure}" in
         --argjson organization "$control_plane" \
         --argjson roster "$roster" \
         '{organization:$organization,roster:$roster}' | \
-        EGREGORE_ROOT="$ROOT" python3 -m egregore_runtime.identity_cli \
+        EGREGORE_ROOT="$ROOT" \
+          PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+          python3 -m egregore_runtime.identity_cli \
           reconcile-records >/dev/null
     fi
     resolved

package/runtime/prime/bin/runtime-upgrade.sh

@@ -28,13 +28,35 @@ _runtime() {
     python3 -m egregore_runtime.harness_cli "$@"
 }
 
+_ensure_identity() {
+  # Pre-Runtime instances can predate stable organization identity. Resolve it
+  # through the existing verified Local/Connected migration before computing
+  # the instance-scoped upgrade key; never infer identity from path or slug.
+  if jq -e '
+    .org_id | type == "string" and length > 0 and (startswith("legacy-org:") | not)
+  ' "$INSTANCE_ROOT/egregore.json" >/dev/null 2>&1; then
+    return 0
+  fi
+  EGREGORE_INSTANCE_ROOT="$INSTANCE_ROOT" \
+    PYTHONPATH="$SCRIPT_DIR${PYTHONPATH:+:$PYTHONPATH}" \
+    bash "$SCRIPT_DIR/bin/runtime-identity.sh" ensure
+}
+
+_run_upgrade() {
+  _ensure_identity || {
+    echo "Runtime update could not resolve this Egregore's stable identity." >&2
+    return 1
+  }
+  _runtime upgrade "$@"
+}
+
 case "${1:-}" in
-  status)   shift; _runtime upgrade status "$@" ;;
-  init)     shift; _runtime upgrade init "$@" ;;
-  prepare)  shift; _runtime upgrade prepare "$@" ;;
-  activate) shift; _runtime upgrade activate "$@" ;;
-  cancel)   shift; _runtime upgrade cancel "$@" ;;
-  rollback) shift; _runtime upgrade rollback "$@" ;;
+  status)   shift; _run_upgrade status "$@" ;;
+  init)     shift; _run_upgrade init "$@" ;;
+  prepare)  shift; _run_upgrade prepare "$@" ;;
+  activate) shift; _run_upgrade activate "$@" ;;
+  cancel)   shift; _run_upgrade cancel "$@" ;;
+  rollback) shift; _run_upgrade rollback "$@" ;;
   team-sync) shift; _runtime team-sync "$@" ;;
   *)
     echo "usage: bash bin/runtime-upgrade.sh {status|init --candidate <version>|prepare|activate|cancel|rollback|team-sync}" >&2

package/runtime/prime/egregore_runtime/identity_cli.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import os
 import sys
+import tempfile
 from pathlib import Path
 
 from .contracts import Permission
@@ -44,6 +45,55 @@ def _authorize_self(root: Path, permission: Permission, resource: str) -> int:
     return 0
 
 
+def _install_connected_key(root: Path, payload: dict) -> dict[str, str]:
+    """Install a membership-verified key without exposing it in output."""
+
+    config = json.loads((root / "egregore.json").read_text(encoding="utf-8"))
+    expected_slug = str(config.get("slug") or "").strip()
+    returned_slug = str(payload.get("org_slug") or "").strip()
+    api_key = str(payload.get("api_key") or "").strip()
+    if not expected_slug or returned_slug != expected_slug:
+        raise ValueError("recovered credential does not match the configured organization")
+    if not api_key or "\n" in api_key or "\r" in api_key:
+        raise ValueError("recovered credential is missing or malformed")
+
+    env_path = root / ".env"
+    existing = env_path.read_text(encoding="utf-8") if env_path.exists() else ""
+    output: list[str] = []
+    replaced = False
+    for line in existing.splitlines():
+        if line.startswith("EGREGORE_API_KEY="):
+            if not replaced:
+                output.append(f"EGREGORE_API_KEY={api_key}")
+                replaced = True
+            continue
+        output.append(line)
+    if not replaced:
+        output.append(f"EGREGORE_API_KEY={api_key}")
+
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=root,
+            prefix=".env.egregore-key.",
+            delete=False,
+        ) as handle:
+            temporary = Path(handle.name)
+            os.chmod(temporary, 0o600)
+            handle.write("\n".join(output) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, env_path)
+        temporary = None
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+    return {"org_slug": expected_slug}
+
+
 def main() -> int:
     root = Path(os.environ.get("EGREGORE_ROOT") or Path.cwd()).resolve()
     if len(sys.argv) > 1 and sys.argv[1] == "initialize-local":
@@ -77,6 +127,11 @@ def main() -> int:
         result = reconcile_control_plane_identity(root, response)
         print(json.dumps({"status": "reconciled", **result}, sort_keys=True))
         return 0
+    if len(sys.argv) > 1 and sys.argv[1] == "install-connected-key":
+        payload = json.load(sys.stdin)
+        result = _install_connected_key(root, payload)
+        print(json.dumps({"status": "installed", **result}, sort_keys=True))
+        return 0
     payload = json.load(sys.stdin)
     result = reconcile_control_plane_identity(root, payload)
     print(json.dumps({"status": "reconciled", **result}, sort_keys=True))